<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 &amp; 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.html'//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">3. Options</h3>
		<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 to load</li>
					<li><code>loading_icon</code>: the icon to show when loading new content. Default is "fa-spinner fa-2x orange"</li>
					<li><code>loading_text</code>: the text to show when loading new content. Default is ""</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 -->
		
		
		<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);
</pre>
					</li>
				</ul>
			</li>
		 </ul><!-- /.info-list -->
		</div><!-- /.info-section -->


		<h3 class="info-title smaller">5. Loading JS &amp; 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: 
        $('#grid_selector').jqGrid('GridUnload');
        $('.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>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 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
 })
</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 -->
		

	</div><!-- /.help-content -->
	<!-- /section:basics/ajax -->

</section>