`{ajax}` para os `inclure`

Na prática

O objetivo é tornar o AJAX acessível, ocultando-se a complexidade do seu uso:

Temos um pedaço da página que contém links para esta mesma página, que só provocam alterações nesse pedaço:

1. colocamos esse pedaço num template separado
2. marcamos os links afetados com a classe ajax: <a href='meulink' class='ajax'>...</a>
3. incluímos o template adicional na página principal com <INCLURE{fond=meutemplate,ajax,env}> ou
   #INCLURE{fond=meutemplate,ajax,env}

E é tudo!

Alguns pequenos detalhes, ainda assim:

• teste sempre o seu template sem o argumento {ajax};
• {ajax} deverá ser sempre acompanhado de {env} para evitar qualquer risco de injeção de URLs no cache do SPIP;
• por padrão, os links a contidos numa classe pagination são também «ajaxados»;
• é possível afetar outros links especificando os seus seletores CSS jquery na variável javascript ajaxbloc_selecteur. Exemplo: var ajaxbloc_selecteur = 'a.ajax, a.umaoutraclasse';;
• obviamente, é preciso que #INSERT_HEAD conste no head do template da página, e que o javascript esteja ativo no navegador do visitante que a consulta.

Em detalhe

Sintaxe de chamada :

<INCLURE{fond=meu_encontrado,ajax,env}>

ou

[(#INCLURE{fond=meu_encontrado,ajax,env})]

Esta chamada inclui o template meu_encontrado «ajaxando» automaticamente todos os links afetados pela variável JS ajaxbloc_selecteur.

Um bloco <div ..></div> é inserido automaticamente em torno do conteúdo do template incluído, pelo mecanismo de gestão do ajax.

Por padrão, este afeta os seletores CSS .pagination a, a.ajax. Em outras palavras, é preciso ter no código fonte dos templates:

• seja a gestão padrão da paginação pelo SPIP. Na condição que a tag #PAGINATION seja incluída num elemento de classe pagination. Ex: <p>#PAGINATION</p>
• seja uma classe ajax nos links (<a class="ajax" href=...>)

O hit ajax reinicia automaticamente o cálculo do template incluído sozinho restaurando o seu #ENV, e incluindo os parâmetros passados no URL do link.

O bloco recarregado fica com opacidade 50% e assume a classe loading durante o carregamento, possibilitando estilizá-lo à vontade.

É interessante notar que:

• os links ajax são colocados em cache no navegador ao serem clicados uma vez. O bloco só será carregado uma vez, mesmo se o visitante retornar diversas vezes ao link em questão
• alguns links podem ser pré-carregados antecipadamente se se incluir a classe preload

Alguns exemplos

Utilização de links ajax
Sendo o template inc-links.html
Ele será chamado no template principal por

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

E conterá

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

Utilização da paginação
Para a paginação, tomemos um exemplo tirado de squelettes-dist/sommaire.html.

Coloquemos num template inc-recentes.html o loop que lista as matérias recentes:

[(#REM) Últimas matérias ]
<B_materias_recentes>
<div class="menu articles">
  [(#ANCRE_PAGINATION)]
  <h2><:derniers_articles:></h2>
  <ul>
  <BOUCLE_materias_recentes(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>
      <abbr class="published"[ title="(#DATE|date_iso)"]>[(#DATE|affdate_jourcourt)]</abbr>[, <:par_auteur:> (#LESAUTEURS)]
      [<div class="#EDIT{intro} introduction entry-content">(#INTRODUCTION)</div>]
    </li>
  </BOUCLE_materias_recentes>
  </ul>
  [<p class="pagination">(#PAGINATION)</p>]
</div>
</B_materias_recentes>

Agora, basta colocar no sommaire.html, no lugar deste loop

<INCLURE{fond=inc-recentes,ajax,env}>

Limites e casos particulares

Este mecanismo automatizado de «ajaxação» dos blocos baseia-se numa hipótese: por padrão, um link ajax só permite atualizar o bloco que o contém, inserindo a versão alterada no mesmo lugar. Note que é possível, a partir de um bloco, recarregar um outro bloco da página, usando a técnica descrita mais abaixo.

Além disso, é importante notar que o cálculo do template incluído deve se basear exclusivamente nos parâmetros passados em #ENV. Com efeito, no cálculo do bloco ajax, ele será recalculado sozinho, por trás do template que o chama. Apenas as variáveis contidas em #ENV serão restauradas.

Assim, não é possível fazer referência a variáveis globais do PHP: estas não serão restauradas no momento do cálculo do bloco ajax. Se realmente quiser usar as variáveis globais do PHP, será preciso re-injetá-las em #ENV no momento da inclusão:

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

Modalidades complementares

SPIP 3.0 melhorou o mecanismo:

Histórico de navegação

Os links .ajax não quebram o histórico de navegação nos navegadores que suportam a API HTML5 History (Firefox, Safari, Chrome à data desta matéria). Ou seja, quando se clica num link ajax do SPIP que recarrega uma parte da página, o URL é atualizado no navegador e o visitante pode clicar em Voltar para recuar.

Classes especiais nos links ajax

• .nohistory indica que o link não afetará o histórico de navegação ao ser clicado;
• .preload indica ao SPIP que o conteúdo do link ajax deve ser pré-carregado no momento em que a página é carregada. Assim o click sobre o link produzirá uma atualização imediata;
• .nocache indica ao SPIP que o conteúdo do link ajax não deve ser colocado em cache. Assim, vários cliques no mesmo link provocarão outros tantos carregamentos a partir do servidor (por padrão, apenas o primeiro carregamento ocorre para um dado URL e o conteúdo é, em seguida, memorizado pelo navegador).

#BOUTON_ACTION

Os #BOUTON_ACTION podem desencadear o carregamento do bloco incluído em ajax.

Recarregamento telecomandado de blocos ajax

Os links .ajax permitem, por padrão, o recarregamento do bloco ajax que os contém, mas é preciso, às vezes, provocar o recarregamento de um outro bloco ajax da página.

Para isso, é possível, no momento da sua inclusão, nomear os blocos ajax que dever poder ser recarregados:

<INCLURE{fond=...,ajax=nomedobloco} />

O bloco ajax assim nomeado pode, em seguida, ser recarregado pela chamada de ajaxReload('nomedobloco').

É possível passar como segundo argumento uma lista de opções contendo:

• callback: função callback que deve ser chamada após o carregamento ajax do bloco;

• args: lista de argumentos que serão passados ao URL durante o carregamento do bloco (permite modificar o #ENV do bloco atualizado);

• history: indica se o recarregamento afeta ou não o histórico de navegação (falso por padrão).

Exemplo

ajaxReload('nomedobloco', {
	callback:function(){alert('terminado');},
	args:{id_article:3},
	history:false
});

ajaxReload pode ser usado igalmente num seletor jQuery, caso em que provocará o recarregamento do menor bloco ajax que contém o elemento afetado. Ele só tem um argumento possível (a matriz de opções) :
$('#contenu').ajaxReload({args:{id_article:3}})

Ver também

• <INCLURE> outros templates
• Ajax num #BOUTON_ACTION
• Documentação "Blocs-ajax-et-ajaxReload" em programmer.spip.net
• AjaxReload em exemplos
  e Exemplo de bloco telecomandado em Ajax em contrib.spip.net