{ajax} for inclusions

The criterion {ajax} allows you to have a clickable link which refreshes just a part of the whole page.

In practice

The idea is to make AJAX easy and to hide its complex workings.

Suppose that on a page there are links to that same page, and clicking on them causes a change only in a certain zone of the page. For this to be possible:

  1. place the part of the page in question in a separate template
  2. mark the links which call that template with the class ajax e.g. <a href='mylink' class='ajax'>...</a>
  3. include the template in the main page with: <INCLURE{fond=mytemplate}{ajax}{env}> or #INCLURE{fond=mytemplate}{ajax}{env}

And that’s all!

Just a few additional words of advice:

  • Always start by testing your template without the {ajax} criterion.
  • To avoid any risk of URLs being injected into SPIP’s cache, the {ajax} criterion should always be accompanied by {env}.
  • Hyperlinks contained within a pagination class are automatically ajaxed by default.
  • It is possible to apply the ajax criterion to other classes by specifying the jQuery selector var ajaxbloc_selecteur = 'a.anotherclass';

In detail

Calling syntax:

  • <INCLURE{fond=my_template}{ajax}{env}>
  • [(#INCLURE{fond=my_template}{ajax}{env})]

This call includes my_template while automatically "ajaxing" all the links targeted by the javascript variable ajaxbloc_selecteur.

The ajax managing process automatically inserts a <div ..></div> block around the content of the included template.

By default, ajax is applied to the classes .pagination a and a.ajax. In other words, in the template you need to have either:

  • the standard SPIP pagination with the #PAGINATION tag within an element with the class pagination. For example, <p class="pagination">#PAGINATION</p>.
  • or an ajax class on hyperlinks (<a class="ajax" href=...>).

A click on the ajax link recalculates just the included template, restoring its #ENV and adding the parameters which have been passed in the URL of the link.

The reloaded block takes an opacity of 50 % and adopts the class loading as it is being loaded, which enables you to give it the style you wish.

It is good to note that:

  • ajax links are cached by the browser when they are first clicked. Thus the block is only loaded once, even if the visitor clicks several times on the link;
  • blocks may be preloaded by placing the class preload on the link.

Some examples

A inclusion in the containing template such as [(#INCLURE{fond=inc-links}{ajax}{env})] would call the template inc-links.html, which could contain the following code:

        <a class="ajax" href="[(#SELF|parametre_url{id_auteur,#ID_AUTEUR})]">
            #NOM #ID_AUTEUR

Using pagination

For pagination, let’s take an example from squelettes-dist/sommaire.html.

Put in a template inc-recents.html the loop which lists recent articles:

[(#REM) Derniers articles ]
<div class="menu articles">
		<BOUCLE_articles_recents(ARTICLES) {par date}{inverse} {pagination 5}>
		<li class="hentry">
			<h3 class="entry-title"><a href="#URL_ARTICLE" rel="bookmark">#TITRE</a></h3>
			<small><abbr class="published"[ title="(#DATE|date_iso)"]>[(#DATE|affdate_jourcourt)]</abbr>[, <:par_auteur:> (#LESAUTEURS)]</small>
			[<div class="#EDIT{intro} introduction entry-content">(#INTRODUCTION)</div>]
	[<p class="pagination">(#PAGINATION)</p>]

Now in sommaire.html, in place of this code, you can put: <INCLURE{fond=inc-recents}{env}{ajax}>

Limits and particular cases

This "ajaxing" mechanism only allows you to reload the block which contains the link in question, inserting the new block in the same place. You cannot target another area of the page.

It is also important to realise that the calculation of the template relies exclusively on the parameters passed through #ENV. For, when the ajax block is calculated, this is done outside of the calling template. Only the variables passed by #ENV are available.

This means that global PHP variables cannot be referenced either: they are not available when the ajax block is being calculated. If you must use PHP global variables, then you need to re-inject them into #ENV when you make the inclusion:


A little history

With SPIP 1.9.2 an attempt was made (it was never documented, because it was unsatisfactory) to consider a loop as a block and to allow its contents to be "ajaxed" without requiring any separation into different templates.

But this was unsatisfactory because:

  • the entity of a loop did not necessarily correspond to a separate block — think of a list whose li elements are generated by several loops;
  • it was necessary to recalculate the whole page in order to get to the loop with its context in place; in other words the server practically needed to do a complete page recalculation, much diminishing any gain in speed.

The new solution has the advantages of:

  • allowing the template author to define the reloadable block exactly by separating it in an included template;
  • allowing the template author to choose its environment by placing the parameters in the INCLURE.
  • making the server really only recalculate that block of the page.

Author Paolo Published : Updated : 26/10/12

Translations : català, English, Español, français, Nederlands, Türkçe