# Mustache Files

Please note that:
You don't need to use Mustache templates in your application.
If you need any info about any part of the template, you can refer to its documentation or use on-page help.
But you can read the following for more info such as the purpose of using a template engine and how it may help you find your way around Ace admin template better.
If you think there's something I'm missing here or more info is needed, just let me know.

### 1. What is it?

- Probably you are already using a template system in your application.

  It may be natively supported by your framework of choice or may be an external library.

  For example PHP Smarty or Ruby's ERB are such template engines.

  The main purpose of using a template system is to separate presentation from application logic

- But Ace admin's demo pages are static HTML and not an application.
  Therefore the main reason for using Mustache templates is to create demo pages which have similar layout and looks but different content.
  In other words, we use templates to break down large HTML pages into smaller parts that can be easily modified and maintained.
- Mustache is a templating system with implementations available in many languages including Javascript, PHP, Ruby, etc.
  For an overview you can see this page: http://mustache.github.io/mustache.5.html
  I'm using it to create the HTML output.
  I've also overridden the partial template loader mechanism to automatically load partial templates as needed.
- You can view or edit Mustache(.mustache) files using your favorite text or HTML editor and enable HTML syntax highlighting for it.

  You can also click on each file name provided in the following sections and view its content inside your browser.

### 2. What does it contain?

- Let's start with the following file which is the default layout file:
  (you can click on in to view its content)
  `mustache/app/views/layouts/default.mustache`
  As you can see it contains some HTML code and some special tags (Mustache tags).
  There are 6 kinds of Mustache tags used here:
  1. Variables that are used for printing a piece of data such as `{{page.title}}` or `{{site.title}}`
  2. Partial template tags that start with a `>` such as `{{> layout.sidebar}}`.
     The engine tries to load current layout's `sidebar` template file.
     It starts by looking inside
     `mustache/app/views/layouts/partials/default`
     folder and if not found, it will look for it inside `mustache/app/views/layouts/partials/_shared`
     In our case, sidebar's HTML code is shared between default & empty layouts. So it's located at:
     `mustache/app/views/layouts/partials/_shared/sidebar.mustache`
  3. Section tags that print a piece of code or data if a variable is defined and is not false/null.
     For example inside our sidebar `mustache/app/views/layouts/partials/_shared/sidebar.mustache` there is:

         <div id="sidebar" class="sidebar
         {{#page.horizontal-menu}} h-sidebar{{/page.horizontal-menu}}

     The `h-sidebar` class will be printed only if a `page.horizontal-menu` variable is defined and is not false or null.
  4. Inverted Section tags that print a piece of code or data if a variable is not defined or is false/null. Again in our `sidebar` mustache file we have:

         {{^page.side_menu_collapsible}}
          {{^page.responsive_style_2}}
           responsive
          {{/page.responsive_style_2}}
         {{/page.side_menu_collapsible}}

     The `responsive` class will be printed only if `page.side_menu_collapsible` and `page.responsive_style_2` variables are NOT defined or are false/null.
  5. Non-Empty List tags are used to print a list of items when the variable is a non-empty array:

         {{#conversation_list}}
           <h3>{{title}}</h3>
           <div class="content">{{content}}</div>
           <div class="time">{{time}}</div>
         {{/conversation_list}}

  6. Comment tags such as `{{! This is a comment}}`. These are ignored and won't be converted to HTML comments.
- In our case variables and options come under some different names:
  1. `site.*` for example `site.title`
  2. `layout.*` for example `layout.sidebar_items`
  3. `page.*` for example `page.title` or `page.content`
  4. And other variables such as `path.assets`, etc.
  For example `site.remote_jquery` inside `mustache/app/views/layouts/partials/_shared/_template/jquery.mustache` is an option that specifies whether we should use remote (CDN) jquery files or not when generating our HTML output.
  Following `Data Files` section describes where data is loaded from.

### 3. Templates Files

- Our layout files are inside `mustache/app/views/layouts` folder which includes:
  (Move mouse over each item to see full path)
  - `mustache/app/views/layouts/default.mustache`
    Default layout file for all pages except for login and empty.html file.
  - `mustache/app/views/layouts/login.mustache`
    Login page layout file.
  - `mustache/app/views/layouts/empty.mustache`
    Empty page's layout file. It is similar to default layout but the partials are slightly different so a separate file is used.
  Layout partials are inside `mustache/app/views/layouts/partials` folder.
  Some of partials are:
  - `mustache/app/views/layouts/partials/_shared/sidebar.mustache`
  - `mustache/app/views/layouts/partials/_shared/sidebar/item.mustache`
  - `mustache/app/views/layouts/partials/_shared/sidebar/shortcuts.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar/topmenu.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar/toggle_buttons.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar/messages.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar/notifications.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar/tasks.mustache`
  - `mustache/app/views/layouts/partials/_shared/navbar/tabbed_user_notifications.mustache`
  - `mustache/app/views/layouts/partials/default/navbar/user_menu.mustache`
  - `mustache/app/views/layouts/partials/empty/navbar/user_menu.mustache`
  - `mustache/app/views/layouts/partials/_shared/settings.mustache`
  - `mustache/app/views/layouts/partials/default/breadcrumbs.mustache`
  - `mustache/app/views/layouts/partials/default/footer.mustache`
  - `mustache/app/views/layouts/partials/_shared/_template/jquery.mustache`
  - `mustache/app/views/layouts/partials/_shared/_template/bootstrap.mustache`
  - `mustache/app/views/layouts/partials/_shared/_template/fonts.mustache`
  - `mustache/app/views/layouts/partials/_shared/_template/fontawesome.mustache`
  - `mustache/app/views/layouts/partials/_shared/_template/scripts.mustache`
  - `mustache/app/views/layouts/partials/_shared/_template/styles.mustache`
- Page files are inside `mustache/app/views/pages`.
  A few samples pages include:
  - Home (dashboard) page:
    `mustache/app/views/pages/index.mustache`
    And its partials are:
    - `mustache/app/views/pages/partials/index/conversations.mustache`
    - `mustache/app/views/pages/partials/index/comments.mustache`
    - `mustache/app/views/pages/partials/index/tasks.mustache`
    - `mustache/app/views/pages/partials/index/members.mustache`
    - `mustache/app/views/pages/partials/index/domains.mustache`
    - `mustache/app/views/pages/partials/index/infobox.mustache`
  - Login page:
    `mustache/app/views/pages/login.mustache`
    which is split into 3 partials:
    - `mustache/app/views/pages/partials/login/login_box.mustache`
    - `mustache/app/views/pages/partials/login/forgot_box.mustache`
    - `mustache/app/views/pages/partials/login/signup_box.mustache`
  - And other pages at `mustache/app/views/pages`.
- Page assets (inline scripts and styles) are inside `mustache/app/views/assets`.
  Putting them in separate files makes it easier to read and edit.
  In some (server side programming language) frameworks, this is usually done by registering files and snippets during application run and inserting them in the output at the right spot.
  - Script of each page is inside `mustache/app/views/assets/scripts`.
    A few samples are:
    `mustache/app/views/assets/scripts/index.js`
    `mustache/app/views/assets/scripts/tables.js`
    `mustache/app/views/assets/scripts/profile.js`
    These scripts are used in relevant pages and can server as a basic example for most plugins and functionality.
  - Some pages may have additional extra CSS rules that are used for demo pages only.
    Currently there is:
    `mustache/app/views/assets/styles/elements.css`
    and
    `mustache/app/views/assets/styles/grid.css`

### 4. Data Files

- In your application you are probably using a database engine to save/restore your data.
  For Ace admin, as there is not any dynamic functionality in demo pages, I have used simple text files with json and csv data format.
  They are located here: `mustache/app/data`
- In our case there are 3 types of data:
  1. Layout data inside `mustache/app/data/layouts` folder.
     For example:
     `mustache/app/data/layouts/partials/default/navbar_messages.json`
     `mustache/app/data/layouts/partials/default/navbar_notifications.json`
     `mustache/app/data/layouts/partials/default/navbar_tasks.json`
     `mustache/app/data/layouts/partials/default/sidebar_items.json`
     `mustache/app/data/layouts/partials/empty/sidebar_items.json`
  2. Page data and options inside `mustache/app/data/pages` folder.
     For example:
     `mustache/app/data/pages/index.json`
     `mustache/app/data/pages/top-menu.json`
     You can see that `top-menu.json` has `horizontal-menu` and `top-menu` options enabled.
     Also each page's partial data is inside `mustache/app/data/pages/partials` folder.
     For example dashboard's conversations or profile activities:
     `mustache/app/data/pages/partials/index/conversations.json`
     `mustache/app/data/pages/partials/profile/activities.json`
  3. Site data and options inside `mustache/app/data/common` folder.
     For example
     `mustache/app/data/common/site.json`
     contains some general site variables and options.
     When using Node.js to produce the output, it's possible to override these values using command line arguments. (There is more info on this in the following section)
     `mustache/app/data/common/script-mapping.json`
     `mustache/app/data/common/style-mapping.json`
     files contain a list of 3rd party names and their relevant Javascript or CSS file.
     This way a file name can be modified and the changes will be reflected on all pages using that script or style in future updates.

### 5. Compiling & Browsing

- Demo page's are generated using a Javascript Mustache compiler(both Hogan.js or Mustache.js are possible).
  You can go to `mustache/js` directory and rebuild HTML files using the following command: `node index.js`
  The output will be put inside `output` folder by default.
  There are also a few options you can use:
  - --engine=mustache|hogan
    Default is hogan
  - --output_folder="../some-folder"
    Default is output
  - And site variables & options of the following file can be overriden via command line arguments:
    `mustache/app/data/common/site.json`
    For example: --remote_jquery=true
- There is also a PHP version using PHP Mustache compiler which I use during development.
  If you have PHP installed, you can access it here: http://path_to_ace/mustache/php/
  And http://path_to_ace/mustache/php/ajax.php for ajax version.
- Also please note that I have overridden a function of Hogan.js and Mustache.js compiler to automatically load a partial template as needed without preloading them.
  They are located at `mustache/js/classes/autoload-hogan.js` and `mustache/js/classes/autoload-mustache.js`