`{ajax}` para las inclusiones

En la práctica

El principio consiste en hacer AJAX accesible, ocultando la complejidad:

Si tenemos un área de la página que contiene enlaces hacia esa misma página, los cuales no provocan cambios más que dentro de esa misma área de la página:

1. Ponemos esa parte de la página en un esqueleto aparte.
2. Marcamos los enlaces implicados con la clase ajax: <a href='mienlace' class='ajax'>...</a>.
3. Incluimos nuestro esqueleto en la página principal con <INCLURE{fond=miesqueleto}{ajax}{env}> o bien
   #INCLURE{fond=miesqueleto}{ajax}{env}

¡Y eso es todo!

Algunas pequeñas precisiones, sin embargo:

• Es conveniente comprobar al principio el esqueleto sin el argumento {ajax}
• {ajax} siempre debería estar acompañado de {env} con el fin de evitar todo riesgo de inyección de URLs en la caché de SPIP.
• Por defecto, los enlaces a contenidos dentro de una clase pagination son también mostrados con AJAX.
• Es posible determinar otros enlaces especificando el selector jQuery var ajaxbloc_selecteur = 'a.otraclase';

En detalle

Sintaxis de llamada:

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

Esta llamada include el esqueleto mi_fond, aplicando AJAX automáticamente a todos los enlaces especificados por la variable JavaScript ajaxbloc_selecteur.

Un bloque <div ..></div> es insertado automáticamente alrededor del contenido del esqueleto incluido, por el mecanismo de gestión de AJAX.

Por defecto, esto determina las propiedades ’pagination a,a.ajax’. Dicho de otro modo, es necesario tener en el código fuente de los esqueletos:

• Bien la gestión estándar de la paginación por SPIP. A condición de que la baliza #PAGINATION se incluya en un elemento de clase pagination. Por ejemplo: <p class="pagination">#PAGINATION</p>.
• O bien una clase ajax en los enlaces (<a class="ajax" href=...>).

Un clic en un enlace AJAX activa automáticamente el cálculo del esqueleto incluido, simplemente restaurando su #ENV y añadiendo los parámetros pasados en la URL del enlace.

El bloque recargado pasa a tener una opacidad del 50 % y a tener la clase loading durante la carga, lo cual permite cambiar el estilo a voluntad.

Es interesante tener en cuanta que:

• Los enlaces ajax son puestos en la caché del navegador cuando se hace clic en ellos una vez. El bloque, por tanto, sólo se carga una vez, incluso si el internauta vuelve a hacer clic más veces sobre el enlace.
• Algunos enlaces pueden ser precargados con antelación, añadiéndoles la clase preload

Algunos ejemplos

Utilización de enlaces AJAX

Supongamos que tenemos un esqueleto inc-enlaces.html. Se llamará dentro del esqueleto que lo incluya de la siguiente manera:

[(#INCLURE{fond=inc-enlaces}{ajax}{env})]

Y contendrá

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

Utilización de la paginación

Para la paginación, tomamos un ejemplo sacado de squelettes-dist/sommaire.html.

Ponemos en un esqueleto inc-recents.html el bucle que lista los artículos recientes:

[(#REM) Últimos artículos ]
<B_articles_recents>
<div class="menu articles">
	[(#ANCRE_PAGINATION)]
	<h2><:derniers_articles:></h2>
	<ul>
		<BOUCLE_articles_recents(ARTICLES) {par date}{inverse} {pagination 5}>
		<li class="hentry">
			[(#LOGO_ARTICLE_RUBRIQUE|#URL_ARTICLE|image_reduire{150,100})]
			<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>]
		</li>
		</BOUCLE_articles_recents>
	</ul>
	[<p class="pagination">(#PAGINATION)</p>]
</div>
</B_articles_recents>

Es suficiente por tanto poner en sommaire.html, en lugar de este bucle, <INCLURE{fond=inc-recents}{env}{ajax}>

Límites y casos especiales

Este mecanismo automatizado de aplicación de AJAX a los bloques descansa sobre una hipótesis: Los enlaces AJAX sólo permiten refrescar el bloque que los contiene, insertando la versión modificada en el mismo lugar. No es posible determinar otra región de la página.

Por otra parte, es importante tener en cuenta que el cálculo del esqueleto incluido debe basarse exclusivamente en los parámetros pasados en #ENV.

En efecto, en el momento de calcular el bloque AJAX, éste se recalculará solo, fuera del esqueleto que lo llame. Sólo las variables contenidas en #ENV serán restauradas.

De este modo, no es posible hacer referencia a variables globales PHP. Éstas no serán restauradas en el momento de calcular el bloque AJAX.

Si se quiere utilizar variables globales PHP, hace falta reinyectarlas en el #ENV en el momento de la inclusión:

<INCLURE{fond=miesqueleto}{ajax}{env}{parametre=#EVAL{$GLOBALS['toto']}}>