<section>
|
<h1 class="blue" data-id="#basics/ajax"><i class="ace-icon fa fa-desktop grey"></i> Ajax Content</h1>
|
<hr />
|
|
<div class="alert alert-danger">
|
<button class="close" data-dismiss="alert"><i class="ace-icon fa fa-times"></i></button>
|
<i class="ace-icon fa fa-exclamation-triangle"></i>
|
Ajax handling has been changed in v1.3.2
|
<br />
|
Please make sure to read through and apply the changes
|
</div>
|
|
<div class="hr hr-double hr32"></div>
|
|
|
<!-- #section:basics/ajax -->
|
<div class="help-content">
|
<h3 class="info-title smaller">1. Overview</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
Ajax loading is useful for updating an element's content without reloading the whole page.
|
</li>
|
|
<li>
|
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.
|
</li>
|
|
<li>
|
In demo ajax pages some pages are not included such as horizontal menu page and jQuery UI page.
|
<br />
|
This is because for horizontal menu, layout changes as well.
|
<br />
|
And for jQuery UI when loading jQuery UI library, tooltip and datepicker override Bootstrap's.
|
<br />
|
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.
|
</li>
|
|
<li>
|
To enable ajax on an element you should call the following function:
|
<pre data-language="javascript">
|
$('#some-content-area').ace_ajax({
|
//options
|
});
|
</pre>
|
</li>
|
|
<li>
|
In Ace demo there is a <code>.page-content-area[data-ajax-content=true]</code>
|
element inside <code>.page-content</code> and its content is updated via ajax because
|
the following code is available by default in Ace:
|
<pre data-language="javascript">
|
$('[data-ajax-content=true]').ace_ajax({
|
//options
|
});
|
</pre>
|
</li>
|
|
<li>
|
The new page's content sent from server is something like this:
|
<pre data-language="html">
|
<title>New Title</title>
|
|
<link rel="stylesheet" href="maybe_new_stylesheet.css" />
|
<style>
|
.new_ruels_maybe {
|
color: red;
|
}
|
</style>
|
|
<div cass="page-header">
|
<!-- optional page header -->
|
</div>
|
|
<div class="row">
|
<div class="col-xs-12">
|
<!-- new page content here -->
|
</div>
|
</div>
|
|
|
<script type="text/javascript">
|
/* Load new scripts here. See "Loading JS & CSS Files" for more info */
|
</script>
|
</pre>
|
</li>
|
|
<li>
|
Before loading content, you should have a basic empty layout.
|
<br />
|
For an example you can see <code>html/ajax/ajax.html</code> file.
|
<br />
|
And using <b>default_url</b> option as shown in next section you can load your default content after that.
|
</li>
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
|
|
|
<h3 class="info-title smaller">2. Setting up</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
By default any element which has <code>data-ajax-content="true"</code> attribute will have ajax enabled.
|
</li>
|
|
<li>
|
It's defined inside:
|
<br />
|
<code>assets/js/ace/ace.js</code> or <code>assets/js/ace.js</code> or <code>dist/js/ace.min.js</code>
|
<br />
|
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.
|
</li>
|
|
<li>
|
So for example you can have a <code>.page-content-area</code> element with <code>data-ajax-content="true"</code> attribute.
|
<br />
|
This way you should change "content_url" option in above mentioned files.
|
<br />
|
Or you can initiate ajax on your own element:
|
<pre data-language="javascript">
|
$('#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"
|
});
|
</pre>
|
</li>
|
|
<li>
|
Your links' <code>href</code> attribute should be like "#mypage1", "#mypage2" so that window hash changes and new ajax content is loaded.
|
</li>
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
|
|
|
|
<h3 class="info-title smaller" data-id="#basics/ajax.options">3. Options</h3>
|
<!-- #section:basics/ajax.options -->
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
The following options are available when enabling ajax content for an element:
|
<ul>
|
<li><code>content_url</code>: is the most important part.
|
A function that returns a url to retrieve.
|
<div class="alert alert-info">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.</div>
|
</li>
|
<li><code>default_url</code>: default url (hash) to load</li>
|
|
<li><code>loading_overlay</code>: specify the element to put the transparent layer over.</li>
|
<li><code>loading_icon</code>: the icon to show when loading new content. Default is "fa fa-spin fa-spinner fa-2x orange"</li>
|
<li><code>loading_text</code>: the text to show when loading new content. Default is "" (empty string)</li>
|
|
<li><code>update_active</code>: a function or boolean value indicating whether to update "active" state of newly selected link and its parents. Default is true</li>
|
<li><code>update_breadcrumbs</code> a function or boolean value indicating whether to update breadcrumbs. Default is true</li>
|
<li><code>update_title</code>: a function or boolean value indicating whether to update window title. Default is true</li>
|
|
<li><code>close_active</code>: whether to close submenu of previously active items or not. Default is false</li>
|
<li><code>max_load_wait</code>: time to wait in seconds before stopping ajax content retrieval if it takes too long for content to arrive. Default is false</li>
|
</ul>
|
</li>
|
<li>
|
If your new page content has <code>title</code> tag and <code>update_title</code> option is true (which is the default),
|
window title will be updated.
|
</li>
|
|
<li>
|
An example would be something like this:
|
<pre data-language="javascript">
|
$('#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"
|
});
|
</pre>
|
</li>
|
|
<li>
|
Please note that if you find your ajax content loading recursively for example when opening
|
homepage, you should modify <code>content_url</code> option to return
|
the correct url.
|
</li>
|
|
<li>
|
For <code>update_active:true</code> to work,
|
the sidebar link element should have <code>data-url</code> attribute equal to window hash:
|
<pre data-language="html">
|
<ul class="nav nav-list">
|
<li>
|
<a href="#somepage" data-url="somepage">Some Page</a>
|
</li>
|
</ul>
|
</pre>
|
</li>
|
|
<li>
|
You can use a function for <code>update_active</code> option, to mark the active item:
|
<pre data-language="javascript">
|
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;
|
}
|
</pre>
|
</li>
|
|
<li>
|
You can use a function for <code>update_breadcrumbs</code> option, to update breadcrumbs:
|
<pre data-language="javascript">
|
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;
|
}
|
</pre>
|
</li>
|
|
<li>
|
You can use a function for <code>update_title</code> option, to update window title:
|
<pre data-language="javascript">
|
update_title: function(hash, url, some_text) {
|
//do something and update title
|
}
|
</pre>
|
Or just insert a <code>title</code> tag inside your ajax content.
|
|
</li>
|
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
<!-- /section:basics/ajax.options -->
|
|
|
<h3 class="info-title smaller">4. Functions</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
The following functions are available:
|
<ul>
|
<li><code>stopLoading</code>: call this for ajax loader to stop
|
<pre data-language="javascript">
|
$('#some-content-area').ace_ajax('stopLoading', true);
|
</pre>
|
</li>
|
|
<li><code>startLoading</code> is called to start loader:
|
<pre data-language="javascript">
|
$('#some-content-area').ace_ajax('startLoading');
|
</pre>
|
</li>
|
|
<li>
|
<code>loadScripts</code> is used to load scripts for new ajax page and described in next section.
|
</li>
|
|
<li>
|
<code>loadUrl</code> is used to load a new url based on a hash:
|
<pre data-language="javascript">
|
$('#some-content-area').ace_ajax('loadUrl', hash, /* cache or not */);
|
</pre>
|
</li>
|
|
<li>
|
<code>loadAddr</code> is used to load a url:
|
<pre data-language="javascript">
|
$('#some-content-area').ace_ajax('loadAddr', 'path/to/file.html', null /* optional hash */, /* cache or not */);
|
</pre>
|
</li>
|
|
<li>
|
<code>post</code> is used to make a post request:
|
<pre data-language="javascript">
|
$('#some-content-area').ace_ajax('post', url, data, updateView, extraParams);
|
</pre>
|
<ul>
|
<li><code>data</code> is an object or string containing data that you want to post</li>
|
<li><code>updateView</code> specifies whether content area should be updated with new content received from server</li>
|
<li><code>extraParams</code> optional extra ajax parameters to send to jQuery ajax method</li>
|
</ul>
|
|
<div class="well">
|
There is also a <code>ajaxpostdone</code> event triggered right after <code>ajaxloaddone</code> is triggered.
|
<br />
|
You can use that to set <code>updateView</code> to <code>false</code> to prevent updating content area.
|
</div>
|
</li>
|
|
<li>
|
<code>reload</code> is used to reload current page
|
</li>
|
|
<li>
|
<code>working</code> returns whether ajax loading is in progress or not:
|
<pre data-language="javascript">
|
var is_working = $('#some-content-area').ace_ajax('working');
|
</pre>
|
</li>
|
</ul>
|
</li>
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
|
|
<h3 class="info-title smaller">5. Loading JS & CSS Files</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
To add new styles to a page, you can simply insert "link" and "style" tags:
|
<pre data-language="html">
|
<title>New Title</title>
|
|
<link rel="stylesheet" href="maybe_new_style.css" />
|
<style>
|
.new_ruels_maybe {
|
color: red;
|
}
|
</style>
|
</pre>
|
</li>
|
|
<li>
|
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:
|
<pre data-language="html">
|
<script type="text/javascript">
|
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
|
alert('hello!');
|
})
|
</script>
|
</pre>
|
|
</li>
|
|
<li>
|
Please note that, scripts loaded via "loadScripts" function, will be loaded and executed only once.
|
<br />
|
But sometimes, some scripts are related to a page and should be run everytime the page is loaded.
|
<br />
|
In that case you can load the script using jQuery's getScript function:
|
<pre data-language="html">
|
<script type="text/javascript">
|
var scripts = ['path/to/plugin1.js', 'path/to/other-plugin.js']
|
$('#some-content-area').ace_ajax('loadScripts', scripts, function() {
|
//for example put inline scripts related to this page here
|
jQuery.getScript('path/to/mypage-script.js', function() {
|
//this page's script is loaded
|
//now do domething else
|
});
|
})
|
</script>
|
</pre>
|
</li>
|
|
<li>
|
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:
|
<pre data-language="javascript">
|
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');
|
})
|
})
|
</pre>
|
|
Note that we need <code>ajaxloadstart</code> event only once, thus using "one" instead of "on".
|
<br />
|
|
See end of some of files at
|
<code>mustache/app/views/assets/scripts/</code>
|
for more examples.
|
</li>
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
|
|
<h3 class="info-title smaller">6. Events</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
There are some events triggered on ajax-enabled element (which can also be captured on document level) :
|
<ol>
|
<li><code>ajaxloadstart</code> triggered when new content is requested.
|
<br />
|
If you call "preventDefault()" on event object, loading will be cancelled</li>
|
<li><code>ajaxloaddone</code> is triggered when ajax content is loaded</li>
|
<li><code>ajaxpostdone</code> is triggered right after "ajaxloaddone" event in POST requests and you can use <code>e.preventDefault()</code> to prevent content area from being updated</li>
|
<li><code>ajaxloadcomplete</code> is triggered when ajax content is loaded and inserted into dom</li>
|
<li><code>ajaxloaderror</code> is triggered when loading ajax content has failed</li>
|
<li><code>ajaxloadlong</code> if <b>max_load_wait</b> is specified, this event is triggered when loading ajax has taken too long</li>
|
<li><code>ajaxscriptsloaded</code> is triggered when loading scripts is finished</li>
|
</ol>
|
</li>
|
|
<li>
|
<pre data-language="javascript">
|
$('#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
|
})
|
</pre>
|
</li>
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
|
|
|
<h3 class="info-title smaller">7. Notes</h3>
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
Please note that, inserting large pieces of content and running javascript code in ajax mode
|
may be somewhat slow on mobile devices.
|
</li>
|
|
<li>
|
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.
|
</li>
|
|
<li>
|
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.
|
</li>
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
|
|
|
|
<h3 class="info-title smaller" data-id="#basics/ajax.pace">8. PACE progressbar</h3>
|
<!-- #section:basics/ajax.pace -->
|
<div class="info-section">
|
<ul class="info-list list-unstyled">
|
<li>
|
You can use PACE plugin to add content loading progress bar in ajax mode.
|
</li>
|
|
<li>
|
You should include it in document's <code>head</code> along with its options:
|
<pre data-language="html">
|
<!--[if !IE]> -->
|
<link rel="stylesheet" href="path/to/css/pace.css" />
|
<script data-pace-options='{ "ajax": true, "document": true, "eventLag": false, "elements": false }' src="path/to/js/pace.js"></script>
|
<!-- <![endif]-->
|
</pre>
|
|
IE8 is a little slow in completing progress so we exclude it.
|
</li>
|
|
<li>
|
You can choose a different style for PACE progress bars from
|
<span class="text-info">http://github.hubspot.com/pace/docs/welcome/</span>
|
</li>z
|
|
<li>
|
In Ace's demo, when ajax is used and PACE is available we change <code>loading_overlay</code>
|
option to 'body', so that transparent overlay covers document body.
|
<br />
|
Also the spinning icon is an ace ajax option. You can hide it by setting <code>loading_icon</code> to null.
|
</li>
|
|
<li>
|
Please see <code>assets/js/ace/ace.js</code> and look for <code>enableDemoAjax</code> function
|
for an example
|
</li>
|
|
</ul><!-- /.info-list -->
|
</div><!-- /.info-section -->
|
<!-- /section:basics/ajax.pace -->
|
|
|
</div><!-- /.help-content -->
|
<!-- /section:basics/ajax -->
|
|
</section>
|
