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:

 New Title

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'//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
- close_mobile_menu: determines whether to automatically collapse(hide) mobile menu after browsing to a new url
- close_dropdowns: determines whether to automatically hide dropdowns after browsing to a new url
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:
```
  
    
       Some Page
    
  
```

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 */);
```
- post is used to make a post request:
```
$('#some-content-area').ace_ajax('post', url, data, updateView, extraParams);
```
  - data is an object or string containing data that you want to post
  - updateView specifies whether content area should be updated with new content received from server
  - extraParams optional extra ajax parameters to send to jQuery ajax method
  There is also a ajaxpostdone event triggered right after ajaxloaddone is triggered.
  You can use that to set updateView to false to prevent updating content area.
- reload is used to reload current page
- 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: 
		$.jgrid.gridDestroy('#grid_selector');
        $('.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. ajaxpostdone is triggered right after "ajaxloaddone" event in POST requests and you can use e.preventDefault() to prevent content area from being updated
4. ajaxloadcomplete is triggered when ajax content is loaded and inserted into dom
5. ajaxloaderror is triggered when loading ajax content has failed
6. ajaxloadlong if max_load_wait is specified, this event is triggered when loading ajax has taken too long
7. ajaxscriptsloaded is triggered when loading scripts is finished

 $('#some-content-area')
 //or
 //$(document)
 .on('ajaxloadstart', function(e, params) {
    //params.url, params.hash, params.method, params.data are available
	//for "ajaxpostdone" event params.result is also available which is the response received from making the post request
	
    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 transparent overlay covers document body.
Also the spinning icon is an ace ajax option. You can hide it by setting loading_icon to null.
Please see assets/js/ace/ace.js and look for enableDemoAjax function for an example