Inspirado nos modelos da Wikipédia, o sistema de modelos oferece novas funcionalidades aos webmasters e aos redatores.
Os modelos são uma extensão dos atalhos clássicos <img1> e <doc1>. Estes correspondem aos modelos /plugins-dist/medias/modeles/img.html e /plugins-dist/medias/modeles/doc.html.
A sua sintaxe foi ampliada e é possível especificar, seja o alinhamento (<img1|left>, <img1|right> ou <img1|center>), uma classe mais genérica, que pode corresponder a um template específico, se existir, ou a uma classe CSS (<img1|classe> irá procurar o modelo modeles/img_classe.html, se o ficheiro existir, senão usará o modelo modeles/img.html, mas com o parâmetro class="classe").
Mas os modelos não se limitam apenas às imagens e documentos; é também possível criar novos atalhos no formato <modelo1>, incluindo simplesmente um template no diretório modeles/ do seu diretório de templates!
Deve-se ter o cuidado de nomear o ficheiro em letras minúsculas («caixa baixa»). Para evitar as diferenciações em alguns sistemas de servidor entre o_ficheiro01.html e O_Ficheiro01.html, o SPIP só procurará por ficheiros nomeados em minúsculas.
Na ausência de qualquer modelo correspondente ao atalho indicado (por exemplo,
<breve1>), o gestor de modelo do SPIP avalia se o objeto solicitado lhe é conhecido (aqui,breve), e se este último tem um URL.<breve1> Neste caso (verificado aqui, já que as notas (breves) são conhecidas do sistema e dispõem de uma função de URL), o SPIP substitui o atalho
<breve1>com uma pequena caixa flutuante com um link para a nota, e a exibição do seu título, como se tivesse sido indicado[->breve1].Se o objeto não for conhecido, o SPIP deixa o atalho intacto, para que ele seja tratado eventualmente em seguida (por um plugin ou um filtro adicional), ou simplesmente ignorado.
Também é possível passar parâmetros adicionais aos modelos. A sintaxe égeneralizada e aceita inclusive HTML, como no exemplo:
<som19|cor=#ff0000
|legenda=O grande <i>Count Basie</i>
|foto=12>
que poderá chamar um modelo modeles/som.html, o qual usará os parâmetros para exibir a foto número 12, numa caixa de cor #ff0000, com uma legenda que suporta palavras em itálico.
Usos mútiplos
- Alterar o aspeto dos atalhos de documentos. Basta recopiar plugins-dist/medias/modeles/img.html para um subdiretório modeles/ do seu diretório de templates, e de alterar este ficheiro. Idem para os atalhos <doc1> e <emb1>, embora este seja de uma complexidade que pode ser desanimadora...
Atenção: não se aventure na modificação de modelos para modificações menores da aparência desses atalhos — é muitas vezes mais fácil alterar os estilos spip_documents_xx a partir dos ficheiros CSS do seu site.
- Exibir uma tabela CSV (Excel). Basta carregar o ficheiro e, em seguida, chamá-lo com <emb12> para exibir os dados do ficheiro CSV na forma de uma tabela HTML!
- Associar um site a uma matéria. Ao incluir nos seus templates um modelo modeles/site_box.html, cria-se imediatamente um novo atalho <site1|box>. Escrevemos em seguida o modelo (com os loops clássicos) de modo a fazê-lo exibir o nome do site, seguido de links para as 3 matérias sindicadas mais recentes, numa caixa flutuante à direita, conseguindo-se assim uma infobox fácil de colocar numa matéria. Um parâmetro poderá indicar o número de matérias a serem exibidas, a presença ou não de resumos etc.
- Exibir uma imagem com marca d’água. Uma vez que se saiba criar um template que exiba uma foto em formato de selo (ver Un site dûment timbré), basta nomear modeles/selo.html para criar o atalho <selo12>. Com, porque não, parâmetros de tamanho, de cor, de escolha do carimbo etc [1].
Bemm entendido, pode-se imaginar do mesmo modo modelos que exibam as imagens em sépia, em versão reduzida etc. Apostamos que tudo isso estará rapidamente disponível como plugins.
- Criar uma matéria composta. Suponhamos que precisamos de uma matéria composta da introdução da matéria 1 e do texto da matéria 2. Nada mais simples: cria-se dois modelos, que recuperam, para um, a introdução da matéria especificada, para o outro, o seu texto e, na nossa matéria composta especifica-se no campo introdução: <article1|intro>, e no campo texto: <article2|texto>. Pode-se incluir filtros, tags e ajustes à vontade...
- Instalar uma matéria em diversas seções. Programando os modelos <article1|intro>, <article1|texto> etc, é possível incluir uma cópia de uma matéria dentro de outra matéria, sem duplicar os dados. Obtém-se assim uma matéria «fantasma» que pode ser instalada numa nova seção (com, ainda, a possibilidade de lhe dar um título diferente ou de incluir outros elementos).
- Fazer uma sondagem. O plugin Formidable, que permite criar formulários e usá-los dentro das matérias com o atalho <formulaire|formidable|id=34>, foi reescrito a partir de modelos.
- Mostrar uma citação aleatória. Se tivermos inserido citações na notas, um atalho <citacao|aleatoria> pode-se recuperar uma à sorte (critério {par hasard}{0,1} nu,m loop de notas), e exibí-la numa caixa flutuante ao lado do parágrafo atual.
- Inserir um documento em idioma diferente do da matéria. Como os modelos funcionam como inclusões, o parâmetro lang=xx também está disponível. Se um dos seus documentos é bilíngue (por exemplo, com um «bloc multi» na chamada), você pode exibir a chamada em esperanto, numa matéria em japonês, chamando <doc1|left|lang=eo>. Se o template do modelo contiver cadeias de idioma, elas serão interpretadas, caso contrário, no idioma passado como parâmetro.
- Exibir um gráfico. Uma tabela de dados é passada ao modelo que se encarrega então de criar um gráfico e inserí-lo no fluxo do texto.
- Um entretítulo na forma de imagem. Porque não imaginar um atalho <imagetypo|texto=Meu entretitulo>?
Na prática
Para evitar conflitos com as tags HTML, um modelo não pode ser chamado por um atalho como <modele>!
Para chamar um modelo simples sem parâmetro, é obrigatório:
- ou atribuir-lhe um identificador numérico :
<o_modelo1>; - ou segui o seu nome com um pipe
|:<le_modele|>)
No primeiro caso, o identificador passado será recuperável no interior do template o_modelo.html com #ENV{id} ou ainda #ENV{id_o_modelo} (que valerá «1» no nosso exemplo) ;
No segundo caso #ENV{id} como #ENV{id_o_modelo} valendo respectivamente «0» (zéro).
Parâmetros em abundância
A sintaxe dos atalhos de modelos tem o formato
-
<modelo12> -
<modelo|parâmetro1=valor|parâmetro2=valor> -
<modelo12|filtro|parâmetro1=valor>.
Os parâmetros podem ser compostos de HTML e de atalhos SPIP (na condição, á claro, que os modelos chamados tenham previsto tratá-los).
Os parâmetros podem estender-se por diversas linhas, permitindo uma escrita relativamente espaçada:
<modelo 10
|pais=Alemanha
|populacao=82000000
|superficie=357027
|classificacao=63
|hino=<i>Das Lied der Deutschen</i>
|url=http://fr.wikipedia.org/wiki/Allemagne
>
O template recupera todos esses parâmetros na tag #ENV, assim #ENV{populacao} vale 82000000. Como esta tag está protegida contra qualquer injeção de javascript, se quisermos permitir HTML num parâmetro, é conveniente usar a notação #ENV*{hino}; se se quiser aplicar o tratamento tipográfico do SPIP, pode-se empregar [(#ENV*{hino}|typo)] ou [(#ENV*{hino}|propre)].
O parâmetro principal (aqui, 10), é passado de duas formas: #ENV{id}=10, e #ENV{id_modele}=10. O que permite aceder, para um modelo chamado por <article3|intro>, à introdução da matéria 3 fazendo:
<BOUCLE_a(ARTICLES){id_article}>#CHAPO</BOUCLE_a>
ou às notas vinculadas à palavra-chave número 3, por;
<BOUCLE_b(BREVES){id_mot=#ENV{id}}>#TITRE</BOUCLE_b>
Como se vê, cada modelo deverá ter a sua própria documentação, já que o próprio atalho não indica nada sobre a utilização feita dos elementos passados pelo atalho.
Um possível emprego nos templates
Os modelos não são limitados aos atalhos dentro das matérias. É possível chamá-los a partir de um template, usando a tag #MODELE{modelo}.
Exemplo:
[(#MODELE{modelo, p1=coisa, p2=outra_coisa, p3=etc}|filtro...)]
Nota: é equivalente a uma inclusão (estática) de template igualmente permitido pela tag #INCLURE. Sendo esta inclusão estática (= armazenada em cache) é preciso atenção para não incluir elementos dinâmicos num modelo, particularmente nenhuma tag #FORMULAIRE_XYZ.
Os modelos padrão
O SPIP é disponibilizado com os modelos a seguir:
- img, doc, emb,
- article_mots e article_traductions, que fornecem respectivamente a lista de palavras-chave vinculadas a uma matéria, e de suas traduções (atalhos: <article1|mots> e <article1|traductions>, mas estes modelos são também chamados pelo template por dist/article.html);
- lesauteurs, que define o resultado da tag #LESAUTEURS, mas não pode ser chamado como um atalho;
- e uma série de modelos de paginação (ver O sistema de paginação).
Os formulários
É igualmente possível chamar os formulários como modelos inseridos num conteúdo editorial.
Exemplo:
<formulaire|login>
Conselhos para escrever um modelo
É rfecomendável começar por refletir a sintaxe que se quer adotar: este modelo estará ligado a uma matéria específica? Se sim, deve-se escolher <article1|xxx>.
Uma vez a sintaxe estabelecida, cria-se o ficheiro modeles/article_xxx.html, entrando-se simplesmente a tag #ENV. Então, numa matéria de teste, digita-se o nosso atalho <article1|xxx|param=x...>; verifica-se, então (numa forma um tanto críptica, trata-se de uma tabela serializada) o ambiente tal como passado ao modelo. pode-se, por exemplo, distinguir o nosso identificador da matéria (sob o nome #ENV{id} e #ENV{id_article}).
Em seguida, pode-se começar a escrever o template do nosso fragmento de página:
<BOUCLE_x(ARTICLES){id_article}>
ou
<BOUCLE_x(ARTICLES){id_article=#ENV{id}}>
. E aqui vamos nós...
Para que o nosso modelo esteja completo, falta testar as sintaxes <article1|xxx|left> e [<article1|xxx>->www.spip.net].
No primeiro caso, é o parâmetro align=left que é passado ao modelo (e é desejável que o modelo esteja alinha ao lado comandado).
No segundo caso, o link é passado num parâmetro lien=http://www.spip.net, e a classe do link em lien_class=spip_out. É recomendável levar em conta o URL solicitado, transformando-o em link, qualquer parte do modelo (por exemplo no título ouno ícone); neste caso, é preciso incluir na primeira tag HTML do modelo uma class="spip_lien_ok", que assinalará ao gestor de modelo que o link foi considerado (na falta do qual o gestor incluirá um <a href=...>...</a> à volta do modelo produzido.
No que diz respeito aos parâmetros, a tag #ENV{x} foi concebida de modo a evitar qualquer injeção de HTML ou de javascript indesejada. Num modelo, pode-se desejar autorizar o HTML nos parâmetros: é preciso então usar #ENV*{x} para recuperar os dados, e eventualmente filtrá-los com |propre ou |typo, de acordo com o tipo de dados (texto podendo comportar vários parágrafos, ou simples linha de texto).
No plano da programação, é recomendado conceber os seus modelos inteiramente em loops, sem nenhum código PHP nem tag dinâmica. Note sempre: num modelo contendo PHP, é o resultado do cálculo que é armazenado em cache, e não o script (como no caso dos templates).
Ver também
Após o lançamento do SPIP 4.0, foi realizado um intenso trabalho nos documentos e logos. Encontre as explicações detalhadas sobre as mudanças aqui: