# Ajax Content

Ajax handling has been changed in v1.3.2
Please make sure to read through and apply the changes

### 1. Overview

- Ajax loading is useful for updating an element's content without reloading the whole page.
- If your application data and sections depend a lot on dynamic loading via ajax, you may need more advanced solutions such as AngularJS which requires some work to integrate with the template.
- In demo ajax pages some pages are not included such as horizontal menu page and jQuery UI page.
  This is because for horizontal menu, layout changes as well.
  And for jQuery UI when loading jQuery UI library, tooltip and datepicker override Bootstrap's.
  This wouldn't be a problem, since in your app you either use jQuery UI datepicker or Bootstrap datepicker, but not both at the same time. Same is true for tooltips.
- To enable ajax on an element you should call the following function:

       $('#some-content-area').ace_ajax({
          //options
       });

- In Ace demo there is a `.page-content-area[data-ajax-content=true]` element inside `.page-content` and its content is updated via ajax because the following code is available by default in Ace:

       $('[data-ajax-content=true]').ace_ajax({
          //options
       });

- The new page's content sent from server is something like this:

- Before loading content, you should have a basic empty layout.
  For an example you can see `html/ajax/ajax.html` file.
  And using default_url option as shown in next section you can load your default content after that.

### 2. Setting up

- By default any element which has `data-ajax-content="true"` attribute will have ajax enabled.
- It's defined inside:
  `assets/js/ace/ace.js` or `assets/js/ace.js` or `dist/js/ace.min.js`
  The "content_url" option which retrieves remote content based on window hash is the most important part and you should change this to return the URL to your content based on the hash tag.
- So for example you can have a `.page-content-area` element with `data-ajax-content="true"` attribute.
  This way you should change "content_url" option in above mentioned files.
  Or you can initiate ajax on your own element:

      $('#some-content-area').ace_ajax({
        content_url: function(hash) {
          //hash is the value from document url hash

          //take "url" param and return the relevant url to load
          return "path/to/content/"+hash+".html";
        },
        default_url: 'homepage.html'//default url
        ,
        loading_icon: "fa-cog fa-2x blue"
      });

- Your links' `href` attribute should be like "#mypage1", "#mypage2" so that window hash changes and new ajax content is loaded.

### 3. Options

- The following options are available when enabling ajax content for an element:
  - `content_url`: is the most important part. A function that returns a url to retrieve.
    Please note that if your ajax content is loaded recursively you need to fix this function and return a valid url based on functions value.
  - `default_url`: default url (hash) to load
  - `loading_overlay`: specify the element to put the transparent layer over.
  - `loading_icon`: the icon to show when loading new content. Default is "fa fa-spin fa-spinner fa-2x orange"
  - `loading_text`: the text to show when loading new content. Default is "" (empty string)
  - `update_active`: a function or boolean value indicating whether to update "active" state of newly selected link and its parents. Default is true
  - `update_breadcrumbs` a function or boolean value indicating whether to update breadcrumbs. Default is true
  - `update_title`: a function or boolean value indicating whether to update window title. Default is true
  - `close_active`: whether to close submenu of previously active items or not. Default is false
  - `max_load_wait`: time to wait in seconds before stopping ajax content retrieval if it takes too long for content to arrive. Default is false
- If your new page content has `title` tag and `update_title` option is true (which is the default), window title will be updated.
- An example would be something like this:

      $('#some-content-area').ace_ajax({
        content_url: function(hash) {
          //hash is the value from document url hash

          //take "hash" param and return the relevant url to load
          return "content/"+hash+".html";
        },
        default_url: 'homepage.html'//default url
        ,
        loading_icon: "fa-cog fa-2x blue"
      });

- Please note that if you find your ajax content loading recursively for example when opening homepage, you should modify `content_url` option to return the correct url.
- For `update_active:true` to work, the sidebar link element should have `data-url` attribute equal to window hash:

- You can use a function for `update_active` option, to mark the active item:

       update_active: function(hash, url) {
          //do something for example mark selected elements as active

          //and return the active element to be used in updating breadcrumbs
          //return active_link_element;
       }

- You can use a function for `update_breadcrumbs` option, to update breadcrumbs:

       update_breadcrumbs: function(hash, url, active_link_element) {
          //do something and update breadcrumbs

          //and return some text to be used in updating window title
          //return some_text;
       }

- You can use a function for `update_title` option, to update window title:

       update_title: function(hash, url, some_text) {
          //do something and update title
       }

  Or just insert a `title` tag inside your ajax content.

### 4. Functions

- The following functions are available:
  - `stopLoading`: call this for ajax loader to stop

        $('#some-content-area').ace_ajax('stopLoading', true);

  - `startLoading` is called to start loader:

        $('#some-content-area').ace_ajax('startLoading');

  - `loadScripts` is used to load scripts for new ajax page and described in next section.
  - `loadUrl` is used to load a new url based on a hash:

        $('#some-content-area').ace_ajax('loadUrl', hash, /* cache or not */);

  - `loadAddr` is used to load a url:

        $('#some-content-area').ace_ajax('loadAddr', 'path/to/file.html', null /* optional hash */, /* cache or not */);

  - `working` returns whether ajax loading is in progress or not:

        var is_working = $('#some-content-area').ace_ajax('working');

### 5. Loading JS & CSS Files

- To add new styles to a page, you can simply insert "link" and "style" tags:

       New Title

- To add new scripts to a page, you can insert "script" tags or use "loadScripts" function which loads and runs scripts and caches them. It prevents scripts from running more than once:

- Please note that, scripts loaded via "loadScripts" function, will be loaded and executed only once.
  But sometimes, some scripts are related to a page and should be run everytime the page is loaded.
  In that case you can load the script using jQuery's getScript function:

- Also when you initiate a plugin on a page and then leave to another page, it may leave elements that need to be cleaned up manually before loading new page:

       var scripts = ['path/to/plugin1.js', 'path/to/other-plugin.js']
       $('#some-content-area').ace_ajax('loadScripts', scripts, function() {
           //put inline scripts related to this page here

           //and clean up some plugin remainings before leaving to another page
           $('#some-content-area').one('ajaxloadstart', function(e, params) {
              //cleanup plugin1
              //for example for jqGrid:
              $('#grid_selector').jqGrid('GridUnload');
              $('.ui-jqdialog').remove();

              //or for some datepicker, etc elements:
              $('.daterangepicker.dropdown-menu').remove();

              //or inline editable
              $('.editable').editable('destroy');
           })
       })

  Note that we need `ajaxloadstart` event only once, thus using "one" instead of "on".
  See end of some of files at `mustache/app/views/assets/scripts/` for more examples.

### 6. Events

- There are some events triggered on ajax-enabled element (which can also be captured on document level) :
  1. `ajaxloadstart` triggered when new content is requested.
     If you call "preventDefault()" on event object, loading will be cancelled
  2. `ajaxloaddone` is triggered when ajax content is loaded
  3. `ajaxloadcomplete` is triggered when ajax content is loaded and inserted into dom
  4. `ajaxloaderror` is triggered when loading ajax content has failed
  5. `ajaxloadlong` if max_load_wait is specified, this event is triggered when loading ajax has taken too long
  6. `ajaxscriptsloaded` is triggered when loading scripts is finished

-      $('#some-content-area')
       //or
       //$(document)
       .on('ajaxloadstart', function(e, params) {
          //params.url and params.hash are available
          if(params.url == 'something') e.preventDefault();
          if(params.hash == 'something') e.preventDefault();
          //you can also return "false" from "content_url" function to prevent loading
       })

### 7. Notes

- Please note that, inserting large pieces of content and running javascript code in ajax mode may be somewhat slow on mobile devices.
- For better results, you should make sure you don't insert many scripts that contain long pieces of code when new ajax content is loaded.
- It would also be faster to keep most of your application logic inside one file and inserted into document once and later used by different ajax pages or sections of your app.

### 8. PACE progressbar

- You can use PACE plugin to add content loading progress bar in ajax mode.
- You should include it in document's `head` along with its options:

  IE8 is a little slow in completing progress so we exclude it.
- You can choose a different style for PACE progress bars from http://github.hubspot.com/pace/docs/welcome/
- In Ace's demo, when ajax is used and PACE is available we change `loading_overlay` option to 'body', so that opaque overlay covers document body
- Please see `assets/js/ace/ace.js` and look for `enableDemoAjax` function for an example