{ajax} pour les inclure

En pratique

Le principe est de rendre AJAX abordable car la complexité est cachée :

J’ai un morceau de page qui contient des liens vers cette même page et ne provoquent de changement que dans le morceau de page considéré :

1. je mets ce morceau de page dans un squelette séparé
2. je marque les liens concernés par la class ajax : <a href='monlien' class='ajax'>...</a>
3. j’inclus mon squelette dans la page principale avec <INCLURE{fond=monskel}{ajax}{env}> ou #INCLURE{fond=monskel}{ajax}{env}

Et c’est tout !

Quelques petites précisions tout de même :

• testez toujours d’abord votre squelette sans l’argument {ajax}
• {ajax} devrait toujours être accompagné de {env} afin d’éviter tout risque d’injection d’urls dans le cache de SPIP.
• par defaut, les liens a contenus dans une classe pagination sont aussi ajaxés
• il est possible de cibler d’autres liens en spécifiant le sélecteur jquery var ajaxbloc_selecteur = 'a.uneautreclasse';

En détail

Syntaxe d’appel :

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

Cet appel inclut le squelette mon_fond en « ajaxant » automatiquement tous les liens ciblés par la variable js ajaxbloc_selecteur.

Un bloc <div ..></div> est inséré automatiquement autour du contenu du squelette inclus, pour le mécanisme de gestion de l’ajax.

Par défaut celle-ci cible les ’.pagination a,a.ajax’. Autrement dit, il faut avoir dans le code source des squelettes :

• soit la gestion standard de la pagination par SPIP. A condition que le balise #PAGINATION soit inclue dans un élément de classe pagination. Ex : <p class="pagination">#PAGINATION</p>
• soit une classe ajax sur les liens (<a class="ajax" href=...>)

Le hit ajax relance automatiquement le calcul du squelette inclus seul en restaurant son #ENV, et en y ajoutant les paramètres passés dans l’url du lien

Le bloc rechargé passe en opacité 50 % et prend la class loading pendant le chargement ce qui permet de le styler à sa convenance.

Il est intéressant de noter que :

• les liens ajax sont mis en cache dans le navigateur lorsqu’ils sont cliqués une fois. Le bloc n’est donc chargé qu’une fois, même si l’internaute revient plusieurs fois sur le lien concerné
• certains liens peuvent être pré-chargés à l’avance en leur ajoutant la classe preload

Quelques Exemples

Utilisation de liens ajax

Soit le squelette inc-liens.html Il sera appelée dans le squelette incluant par

Et contiendra

Utilisation de la pagination

Pour la pagination, prenons un exemple tiré de squelettes-dist/sommaire.html.

Mettons dans un squelette inc-recents.html la boucle qui liste les articles récents :

Il suffit alors de mettre dans sommaire.html, à la place de cette boucle <INCLURE{fond=inc-recents}{env}{ajax}>

Limites et cas particuliers

Ce mécanisme automatisé d’ajaxisation des blocs repose sur une hypothèse : les liens ajax ne permettent de rafraichir que le bloc le contenant, en insérant la version modifiée au même endroit. Il n’est pas possible de cibler une autre région de la page

Par ailleurs, il est important de noter que le calcul du squelette inclus ne doit reposer exclusivement que sur les paramètres passés en #ENV.

En effet, lors du calcul du bloc ajax, celui-ci sera recalculé tout seul, en dehors du squelette appelant. Seules les variables contenues dans #ENV seront restaurées.

Ainsi, il n’est pas possible de faire référence à des variables php globales : celles-ci ne seront pas restaurées au moment du calcul du bloc ajax.

Si vous voulez vraiment utiliser des variables globales php, il faut les réinjecter dans le #ENV au moment de l’inclusion :

Un peu d’histoire

SPIP 1.9.2 avait entamé une tentative (non documentée car insatisfaisante) de considérer la boucle comme un morceau et de permettre une ajaxisation du contenu d’une boucle, sans avoir à faire de découpe du squelette.

Cela s’est avéré insatisfaisant car :

• l’entité boucle n’est pas forcément pertinente -> exemple d’une liste dont les li sont générés par plusieurs boucles
• cela obligeait à recalculer toute la page pour arriver à la boucle car on ne pouvait pas savoir son contexte d’entrée -> le serveur faisait presque un calcul de page complet pour en extraire le morceau, d’où un gain faible en rapidité

La nouvelle solution à l’avantage :

• d’obliger le concepteur du squelette à faire la découpe du morceau qui sera rafraichi en le mettant dans un squelette inclus
• de lui permettre de décider exactement ce qui forme un bloc fonctionnel indépendant du reste de la page
• d’expliciter son environnement en le passant en paramètre dans le inclure
• de permettre au serveur de ne recalculer effectivement que ce morceau de page