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