<INCLURE> outros templates

Sintaxe de inclusão

Os utilizadores habituais de PHP conhecem a função. include, cujo princípio é similar a este que é apresentado aqui.

Pode-se chamar um template a partir de outro template, graças à tag <INCLURE> (pode-se igualmente usar <INCLUDE>, que é idêntica). A sintaxe geral é:

<INCLURE{fond=template, param}>
<INCLURE{fond=template, param1,param2}>
<INCLURE{fond=template, param1,param2}{param3=#LISTE{valA,valB}}>

O «template» é o nome do ficheiro (também chamado de snippet em inglês, ou noisette, em francês) que queremos integrar na página.

Por exemplo, imaginemos que todas as páginas do site exibem as mesmas informações no rodapé. Agrupa-se, então, o código SPIP e o HTML desse «rodapé» num ficheiro «rodape.html». Basta incluir a linha a seguir, na posição desejada, em cada um dos templates em que se queira exibir o rodapé:

<INCLURE{fond=rodape}>

Inclusões dependentes do contexto

Certas inclusões podem depender do contexto. Por exemplo, imaginemos um template «hierarquia», que exibe o caminho que leva a uma seção a partir da raiz do site; esta página seria chamada por um URL no formato: «spip.php?page=hierarquia&id_rubrique=xxx».

Nos templates em que se pretendesse exibir a hierarquia a partir da secão atual, seria preciso indicar que o parâmetro em questão é {id_rubrique}; se necessário, poder-se-ia criar um loop que permitisse recuperar o número da seção em questão, colocando-se o código a seguir no interior desse loop:

<INCLURE{fond=hierarquia, id_rubrique}>

Nota: neste caso, o template hierarquia.html começaria certamente por um loop RUBRIQUES com o critério{id_rubrique}...

Pode-se imaginar que, em certos templates, se deseje recuperar não a hierarquia com base numa seção "variável" (conforme o contexto, por exemplo, o parâmetro passado no URL), mas com base numa seção cujo número se conhece de antemão. Para isso, pode-se fixar o valor do parâmetro da seguinte forma:

<INCLURE{fond=hierarquia, id_rubrique=5}>

N.B. É possívell indicar vários parâmetros na tag <INCLURE>; no entanto este é um caso bastante raro, na prática. Evite incluir parâmetros inúteis, que tornarão o cache menos eficaz e o seu site mais lento.

N.B. O arquivo incluído é, ele mesmo, um template, e disporá do seu próprio valor de #CACHE [1]

Transmitir todo o contexto corrente

O parâmetro env permite transferir o contexto de compilação do template corrente ao template incluído.

<INCLURE{fond=squelette, env}>

Em contexto multilíngue

Se o multilinguísmo do SPIP estiver ativo, é possível definir o idioma do ambiente de um template incluído, utilizando o parâmetro {lang}.

-  Se não houver parâmetro de idioma utilizado, como no formato <INCLURE{fond=rodape}>, o template incluído será chamado no idioma padrão do site;

-  <INCLURE{fond=rodape, lang=es}> chama o template em espanhol. Você pode substituir «es» pelo código ISO do idioma desejado: en para inglês, fr para francês, vi para vietnamita etc. (ver: «article 6960»);

-  <INCLURE{fond=rodape, lang}> chama o template no idioma corrente do contexto de inclusão.

Convém notar que isso torna possível o uso dos códigos de ficheiros de idioma nos templates incluídos (ver: «article 6960»).

Os templates incluídos suportam os mesmo mecanismos de seleção por idioma que os templates de «primeiro nível». Noutros termos, os templates incluídos (aqui rodape.html) podemser determinados relativamente a um certo idioma (rodape.es.html, por exemplo) da mesma maneira que qualquer olutro template. Mais uma vêz, ver «article 6960» para mais detalhes.

#INCLURE estáticos

Com esta tag, torna-se possível aplicar filtros no templaate incluído:

[(#INCLURE{fond=carta, env}|version_texte)]

Adicionalmente, a inclusão é realizada no momento do processamento do template, e o seu resultado é armazenado no cache da página que o chamou. Com este sistema, deixa de ser possível gerir um período de validade (#CACHE{}) reduzido para um template incluído.

Atenção: o resultado da inclusão sendo armazenado em cache, é necessário que o #INCLURE não contenha elementos dinâmicos, particularmente a tag #FORMULAIRE_XYZ.

<INCLURE{fond=..}> e [(#INCLURE{fond=..})] têm portanto funcionamentos diferentes:

• com <INCLURE{fond=..}> cada template incluído tem uma entrada de cache independente. Em outros termos, esta sintaxe provoca a inclusão de páginas a cada acesso do visitante, exista ou não uma página já em cache.
• com [(#INCLURE{fond=..})], a página de chamada principal contém, em cache, todo o código gerado, e os ficheiros incluídos não possuem entrada de cache separada.

Observação: Por padrão, 3 variáveis de ambiente são transmitidas automaticamente à avaliação da inclusão:
lang, date e date_redac. Pode-se bloquear essa inclusão ao ambiente com o uso do asterísco: #INCLURE*. Torna-se assim possível usar os critérios condicionais nestas variáveis nos templates incluídos.

<INCLURE> e {doublons}

Existe um critério de loop {doublons}. Ao usar-se <INCLURE> num template, os doublons memorizados não são transmitidos ao template incluído.

Pode-se contornar este problema, bastando incluir o parâmetro {doublons}> à chamada do template a incluir. Por exemplo, <INCLURE{fond=minhapagina, doublons}>.

Note que, no entanto, os doublons selecionados no template incluído não "ascenderão" ao template principal.

<INCLURE> e ajax

Pode-se facilmente usar a tecnologia ajax, que permite clicar sobre um link e atualizar a página apenas na zona que mudaria se se exibisse toda a página com os novos parâmetros. Para mais detalhes, veja a matéria `ajax` para os `inclure`.

#INCLURE um arquivo que não é um template

A tag #INCLURE permite incluir um ficheiro que não é um template: para tal, basta indicar simplesmente o ficheiro como primeiro argumento, omitindo-se o "fond=" que se utiliza para incluir templates. O ficheiro será assim lido e o seu conteúdo será exibido no contexto da chamada sem ser processado pelo SPIP.

Exemplos de uso em diferentes ficheiros SPIP ou plugins :
-  em sedna.js.html: [(#INCLURE{javascript/sedna.js}|...]
-  em adminer.html: [<style type="text/css">(#INCLURE{adminer.css}|compacte{css})</style>]
-  em portfolio_document.html: [(#INCLURE{javascript/medias_edit.js}|compacte{js})]
-  em gis.js.html: [(#INCLURE{lib/leaflet/dist/leaflet-src.js})]

A maioria destes usos dizem respeito a ficheiros javascript ou CSS, mas é possível incluir outros tipos de ficheiros:
-  em favicon.ico.html: [(#INCLURE{favicon.ico}|sinon{#INCLURE{spip.ico}})]

Ver também

• `ajax` para os `inclure`
• Auxílios de depuração de templates e mais particularmente o chamado de « var_mode=inclure »

Em Programmer.spip.net

• Transmissão de parâmetros
• O ambiente #ENV