What is modAjaxify

 

modAjaxify is mainly a jquery plugin which is strongly coupled with MODX Revolution. Nevertheless it can be used on its own as a plain jquery plugin.

 

It automatically parses any (or selected ones) content links and ajaxifies them without destroying them which makes the addon SEO friendly. That means that if the link is clicked the page will not be reloaded but the fetched content of the link will be placed on a specific container as configured by the developer. Although if you open the link in a new tab it will load normally.

 

The plugin has many options to control where and what to ajaxify and also events that signify the start/progress/end of loading which is very useful for creating loaders.

Another useful feature of the plugin is that is able to preload any content images before rendering the content in the target container.

 

This addon can be started with zero configuration just by placing the [ [ $ ajaxifyInit ] ] in the head of the template.

 

Dependencies

jquery

jquery.history.js

preloadjs-0.6.1.min.js

 

If you already loading these libraries then you should remove them from [ [ $ ajaxifyInit ] ]

 

modAjaxify Documentation

The configuration of the addon is controlled through the jquery plugin shadowUrls.

An initial configuration can be found in the chunk ajaxifyInit.

 

What it does:

• Any link within a designated container (default is body) will function as an ajax link.

• It can load the content of the links in different containers with simple html annotation (eg. any link with the property context will load the content in the container with id as provided through this property)

• It preloads images before rendering the content

• It provides callbacks for custom renderer

• Id provides callbacks for custom loaders

• Supports ajax submit for forms

• Supports different menus by placing the ‘active’ class in the clicked menu option

• Supports callbacks for handling preloading when a page url is called directly (not through ajax)

• Supports retina images preload for boosting performance

• Supports lazy image loading

• The MODX plugin make sures that will output only the necessary content of the page striping out everything else. This technique boosts the performance of the website.

 

Get Started

This addon can be started with zero configuration just by placing the [ [ $ ajaxifyInit ] ] in the head of the template.

API

shadowUrls properties

• linkSelector: The links that will be ajaxed can be restricted in a specific container. This property defines the container. Default value is body,

• targetSelectorId: The id of the container that the content will be rendered in. The default value is content. In case this id does not exists in the page then the body will be used as a container.

• menuSelector: The selector that identifies menu containers. Any links clicked in this container will be toggled with the activeClass. Default value menu

• activeClass: The class that will be used when a link is selected in the menu Default value active

• menuChildrenSelector:  In case the links of the menu are nested in wrappers this is how you select the wrapper. Default value span.

• noAjaxClass: In case you need some links not to be ajaxed just use this class in the link. Default value .noajax.

• preloadInitEnabled: If it is enabled then callbacks will be used whenever a page is called directly. Default value:false

• includeForms: If is true forms will be ajaxed. Default value:true

• googleAnalyticsId: (beta) If set then build in support of google analytics is enabled. The analytics id should be the one provided by google for the specific website.

shadowUrls callbacks

• beforeLoad(url): This method is triggered just before loading starts (very handy for starting loading animations).

Params:

• url:The url triggered the ajax

• this: It refers to the dom element of the target

• onSuccess(url, response) :This method is triggered when loading and rendering is finished. Very handy when you want to stop loaders.

Params:

• url:The url triggered the ajax

• response: The loaded content

• this: It refers to the dom element of the target

 

• onRender(url, response): This method is used for custom renderers. In case you provide one and you do want to ajaxify the loaded links then after you do your rendering you will to apply the method shadowlinks on the rendered content.For example example the default code of the method is:

          $(‘custom_container’).html(processed_responce).shadowlinks();

Params:

• url:The url triggered the ajax

• response: The loaded content

• this: It refers to the dom element of the target

 

• onProgress(url, progress): This method is used mainly for creating progressive loaders.

Params:

• • url:The url triggered the ajax

  • progress: float that indicates the progress of the downloaded data. Expected values 0 to 1.

  • this: It refers to the dom element of the target.

• onInitStart(url): This method is triggered just after the url is directly hit by the user.

Params:

• • url:The url triggered the ajax

• onInitProgress(url, progress): This method is used mainly for creating progressive loaders when a page is first loaded.

Params:

• • url:The url triggered the ajax

  • progress: float that indicates the progress of the downloaded data. Expected values 0 to 1.

• onInitSuccess(url, response) :This method is triggered when a page has been directly called and has been fully loaded including images. Very handy when you want to stop loaders.

Params:

• url:The url triggered the ajax

 

HTML properties

The plugin make use of 3 html properties.

• title: If the link includes this property then the plugin will place the value to the title of the page.

• context:The id of the container which will display the loaded content. If not specified the targetSelectorId will be used

  Eg.<a title=”Some title” context=”some_id” href=”som_url”>Test</a>

• lazy-image:If you want faster image loading, then you should provide as a source of your images really small images and set lazy-image with the real image

  Eg.<img src='small.jpg' lazy-image='big.jpg' />

 

Eg.<a title=”Some title” context=”some_id” href=”som_url”>Test</a>

 

The above example will load the content from some_url and will place it inside an element having this ID

 

Note: The MODX plugin will prune and transmit only the desired element (which has the context ID) from the content (as long as it exists) to boost performance.

• src-<min-window-width-in-pixels>: This property is applied on img elements. If is used then modAjaxify will load the picture that matches the window width.

 

Eg.<img src-2000=”big.jpg” src-1000=”medium.jpg” src=”small.jpg” />

 

This means that any device with screen higher than 1000px width will load medium.jpg, if higher than 2000 will load big.jpg and if is smaller than 1000 will load small small.jpg

 

Example of usage as provided in the ajaxifyInit chunk

 

$.shadowUrls({

          'targetSelectorId': 'content',

          'menuSelector': '.menu',

          'activeClass': 'active',

          'menuChildrenSelector': '.menuoption',

          'noAjaxClass': '.noajax',

          onSuccess: function (url, response) {

              $(this).fadeIn();

 

          },

          onRender: function (url, data) {

 

              $(this).html(data).shadowlinks();

 

          },

          onProgress: function (url, progress) {

              console.log("loading progress:" + progress);

 

          },

          beforeLoad: function (url) {

              $(this).fadeOut();

          }

      });