Os filtros do SPIP

Filtros de datas

Os filtros a seguir aplicam-se às datas ([(#DATE|affdate)], por exemplo).

-  |affdate exibe a data na forma de texto, por exemplo «13 janeiro 2001».

Pode-se passar um parâmetro de formatação da data, correspondente a um formato SPIP («'saison'» etc.) ou a um formato do comando PHP date («'Y-m-d'»).
Por exemplo:

• [(#DATE|affdate{'Y-m'})] exibirá numericamente o ano e o mês da data filtrada separados por um traço,
• a notação [(#DATE|affdate{'saison'})] é totalmente equivalente a: [(#DATE|saison)].

-  Existem também variantes de affdate que fornecem atalhos:

|affdate_jourcourt exibe o nome do mês e o valor numérico do dia, por exemplo «19 Abril». Se a data não pertencer ao ano atual, o ano correspondente é exibido: «1 Novembro 2004».

|affdate_court exibe o nome do mês e o número do dia, por exemplo. «19 Abril». Se a data não pertencer ao ano atual, serão exibidos apenas o mês e ano, sem os números do dia: «Novembro 2004».

|affdate_mois_annee exibe apenas o mês e o ano: «Abril 2005», «Novembro 2003».

|affdate_heure exibe a data seguida da hora: «3 Abril 2005 às 20h00min».

-  |jour exibe o dia (numérico).

-  |mois exibe o mês (textual).

-  |annee exibe o ano.

-  |heures exibe as horas de uma data (as data fornecidas pelo SPIP contêm não apenas o dia, mas também os horários).

-  |minutes exibe os minutos de uma data.

-  |secondes exibe os segundos.

-  |nom_jour exibe o nome do dia (segunda-feira, terça-feira...).

-  |nom_mois exibe o nome do mês (janeiro, fevereiro...).

-  |saison exibe a estação (inverno, verão...).

-  |unique devolve o valor do elementofiltrado apenas se for a primeira vêz que ele for encontrado. Este filtro não é limitado às datas mas é interessante para, por exemplo, exibir uma lista de matérias por data:

<BOUCLE_blog(ARTICLES){par date}{inverse}{"<br>"}>
[<hr><h1>(#DATE|affdate_mois_annee|unique)</h1>]
#TITRE ...
</BOUCLE_blog>

esta tag só exibirá a data a cada mudança de mês.

Eis outro exemplo:

<BOUCLE_blog2(ARTICLES){par date}{inverse}>
    [<hr><h1>(#DATE|annee|unique)</h1>]
        [<h2>(#DATE|affdate{'Y-m'}|unique|nom_mois)</h2>]
             <a href="#URL_ARTICLE">#TITRE</a><br />
</BOUCLE_blog2>

exibirá uma lista que se assemelhará a:

   2005
        março
                matéria de março
                outra matéria de março
        fevereiro
                matéria de fevereiro
   2004
        dezembro
                uma matéria

Usa-se a notação |affdate{'Y-m'} para exibir o nome do mês a cada ano. Com efeito:

• se definissemos apenas #DATE|nom_mois|unique, os nomes de mês só seriam exibidos para o primeiro ano.
• se a filtragem fosse: #DATE|unique|nom_mois, topdas as datas seriam exibidas. Com efeito, #DATE devolve uma data completa que contém também a hora. Há uma grande chance de que as datas completas de duas matérias publicadas no mesmo dia sejam diferentes.

Por essa razão só guardamos o mês e ano da data, antes de passá-la pelo filtro unique.

Pode-se passar um argumento opcional a esse filtro para diferenciar duas utilizações independentes do filtro. Por exemplo: [(#DATE|affdate_mois_annee|unique{ici})] não terá influência sobre [(#DATE|affdate_mois_annee|unique{la})].

Filtros de texto

Ver também a matéria dedicada aos filtros de texto.

-  |liens_ouvrants transforma os links do SPIP que apontam para sites externos em links do tipo «popup», que abrem numa nova janela; é equivalente ao target=blank do HTML.
Nota: os desenvolvedores do SPIP consideram este comportamento geralmente indelicado, já que os visitantes sabem bem se querem ou não abrir uma nova janela - que, desta maneira lhes é imposto. Mas a demanda foi muito forte, e acabamos cedendo ;-)

-  |supprimer_numero serve para ocultar o número de um título se, por exemplo, quisermos ordenar as matérias {par num titre} (pelo número do título) sem exibir os números (já que eles só servem para ordenar as matérias). O formato dos prefixos numerados é «XX. título», XX sendo um número de n algarismos (illimitado).

-  |PtoBR transforma as quebras de parágrafo em simples quebras de linha, permitindo «apertar» um layout, por exemplo no interior de um sumário.

-  |taille_en_octets permite transformar um número de bites (25678906) em algo mais explícito («24.4 KB»).

-  |supprimer_tags é uma supressão básica e brutal de todos os <...>

-  |textebrut é parecido com o filtro supprimer_tags, mas age de um modo mais sutil, transformando os parábrafos e <br> em quebras de linha, e os espaços não separáveis em espaços simples. Pode ser usado, por exemplo, para fazer uma descrição META: [<meta name="description" content="(#DESCRIPTIF|textebrut)">]

-  |texte_backend pode ser usado para tornar um texto compatível com fluxos XML. Este filtro é usado, por exemplo, no template backend.html que gera o feed RSS do site.

-  |couper corta um texto após um certo número de caracteres. Ele tenta não hifenizar as palavras e remove a formatação do texto. Se o texto for muito longo, «(...)» é incluído ao final. Este filtro corta por padrão em 50 caracteres, mas pode-se especificar outro comprimento, passando um parâmetro ao filtro, por exemplo: [(#TEXTE|couper{80})].

-  |match usa uma expressão regular (ver preg_match()) para extrair um padrão no texto, se estiver presente ou, caso contrário, não devolve nada. Por exemplo, para recuperar a primeira palavra do tírulo [(#TITRE|match{^\w+?})]. Pode ser um texto simples, exibir "toto" se no título: [(#TITRE|match{toto})]

-  |replace usa também uma expressão regular (ver preg_replace()) para suprimir ou substituir todas as ocorrências de um padrão no texto. Com um único parâmetro, uma expressão regular, o padrão será substituído por uma string, ou suprimido.
Por exemplo, para suprimir todos os "notaXX" do texto [(#TEXTE|replace{nota\d*})]. Se um segundo parâmetro é fornecido, as ocorrências do padrão serão substituídas por esse valor. Por exemplo, para trocar todos os 2005 ou 2006 do texto por 2007 [(#TEXTE|replace{200[56],2007})]. Podem ser textos simples, trocar todos os "em vez de" por "ao invés de": [(#TEXTE|replace{em vez de,ao invés de})]

Filtros de teste

-  |?{vrai,faux} é uma versão evoluída de |sinon. Ele aceita um ou dois parâmetros:

• vrai é o valor a exibir no lugar do elemento filtrado se este não estiver vazio.
• faux é opcional. E o valor a exibir se o elemento filtrado estiver vazio.
  [(#TEXTE|?{#TEXTE,"sem texto"})] é equivalente ao exemplo apresentado no filtro |sinon.

-  |sinon indica que o que deve ser exibido se o elemento «filtrado» estiver vazio: assim [(#TEXTE|sinon{"sem texto"})] exibe o texto; se estiver vazio, exibe «sem texto».

-  |oui devolve um espaço ou nada. É equivalente a |?{' ',''} ou |?{' '} e permite devolver um conteúdo não vazio (um espaço) para sinalizar que as partes opcionais das tags devem ser exibidas.

-  |non é o inverso de |oui e é equivalente a |?{'',' '}

-  |et permite verificar a presença de 2 elementos

-  |ou verifica a presença de um de dois elementos

- |xou verifica a presença de um único de dois elementos.

Adicionalmente, o SPIP entenderá os equivalentes em inglês «yes», «not», «or», «and» e «xor»

// exibe o cabeçalho se existir, senão, o início do texto
[(#CHAPO|sinon{#TEXTE|couper{200}})]
 // exibe "Este título é longo" apenas se o título tiver mais de 30 caracteres
[(#TITRE|strlen|>{30}|oui) Este título é longo ]
 
[(#CHAPO|non) Não há cabeçalho ]
[(#CHAPO|et{#TEXTE}) Há um cabeçalho e um texto ]
[(#CHAPO|et{#TEXTE}|non) Ambos não existem ]
[(#CHAPO|ou{#TEXTE}) Há ou um cabeçalho, ou um texto, ou ambos ]
[(#CHAPO|ou{#TEXTE}|non) Não há cabeçalho nem texto ]
[(#CHAPO|xou{#TEXTE}) Há ou um cabeçalho, ou um texto (mas não ambos, ou nenhum) ]
[(#CHAPO|xou{#TEXTE}|non) Não há nada, ou há tudo, mas não um dos dois ]

-   Filtros para comparações com valores:

• |=={valeur} e |!={valeur} permitem verificar, respectivamente, a igualdade ou inigualdade entre o elemento filtrado e valor.
  Por exemplo:

  <li [(#TITRE|=={édito}|?{'id="edito"',''})]>#TITRE</li>
  

• |>{valeur}, |>={valeur}, |<{valeur} e |<={valeur} comparam o elemento filtrado (que deve ser numérico) com um valor numérico.
  Por exemplo:

  [(#TOTAL_BOUCLE) [(#TOTAL_BOUCLE|>{1}|?{'matérias','matéria'})] nesta seção.]
  

Atenção De modo geral, todos os operadores de comparação do php podem ser usados como filtros.

Filtros de logos

Os filtros de logos têm a mesma sintaxe de todos os outros:
[(#LOGO_XXX|filtro)]

Mas:
-  #LOGO_XXX** devolve o ficheiro
-  #LOGO_XXX{top/left/right/center/bottom} dera um alinhamento
-  #LOGO_XXX{url} gera um logo que aponta para um URL.

-   Os filtros |hauteur (altura) e |largeur (largura) devolvem as informações sobre o tamanho (i.e. Altura e Largura) do elementofiltrado, se for uma imagem.

Estes filtros têm um interesse moderado para serem aplicados diretamente ao logo de um documento, visto já haver #HAUTEUR e #LARGEUR à disposição para os documentos. Ao contrário, podem ser aplicados após o filtro |image_reduire para conhecer o tamanho exato da imagem reduzida.

Mais geralmente, podem ser aplicados em quaisquer tags (ou filtros) devolvendo uma tag HTML <img ...>.

-  |image_reduire{largeur,hauteur} permite forçar um tamanho máximo de exibição das imagens e logos.

Este filtro usa-se, por exemplo, num logo de matéria, do modo a seguir:

[(#LOGO_ARTICLE|right|image_reduire{130})]

Neste exemplo, o logo da matéria aparecerá alinhado à direita, com um tamanho máximo de 130 pixels.

Este filtro pode aceitar dois argumentos: largeur e hauteur. Se um destes argumentos for igual a 0, o SPIP só considerará o outro e calculará essa dimensão conservando a proporção da imagem. Adicionalmente, este filtro também se aplica à tag #TEXTE e assim, serão todas as imagens que o redator introduzir no texto graças aos atalhos do SPIP que serão reduzidas.

Por exemplo,

[(#TEXTE|image_reduire{600,0})]

exibe todas as imagens inseridas no encadeamento do texto com uma largura máxima de 600 pixels. Isso permite preservar o layout mesmo sem que o redator tenha que se preocupar com o tamanho das imagens que ele instalar no site.

Nota Se a opção «criação de vinhetas» estiver ativada na configuração do site, esses logos reduzidos serão ficheiros de imagens específicos, calculados automaticamente pelo servidor (com GD2, normalmente, nos formatos JPG e PNG). Senão, será uma versão completa da imagem que será exibida, mas com um tamanho de exibição fixado diretamente em HTML.

Filtros matemáticos

-  |plus{xx}, |moins{xx} e |mult{xx} correspondem respectivamente à adição, subtração e multiplicação.

-  |div{xx} corresponde à divisão não-euclidiana ("após a vírgula").

-  |modulo{xx} corresponde ao resto da divisão euclidiana por xx de um número.

Por exemplo [(#COMPTEUR_BOUCLE|modulo{5})] conta de 0 a 4 depois volta a 0 etc.

Além disso, o conjunto de funções matemáticas do PHP pode ser usado como filtros.

Outros Filtros

-  |traduire_nom_langue aplica-se à tag #LANG e devolve uma tradução do código de idioma que ela devolve (pt, fr, en, it etc.) nesse idioma.

Atenção: As traduções dos códigos são feitas no idioma que representa esse código e seguem as convenções de escrita desse idioma.

Assim, «fr» será traduzido como «français» em minúsculas, bem como «es» será traduzido como «Español» com a inicial maiúscula.

-  |alterner{a,b,c,...} aplica-se a uma tag numérica (em geral #COMPTEUR_BOUCLE ou #TOTAL_BOUCLE) e exibe o argumento correspondente ao valor dessa tag.
Pode-se assim alternar uma exibição num loop. Por exemplo, [(#COMPTEUR_BOUCLE|alterner{'white','yellow'})] exibirá «white» na primeira iteração do loop, «yellow» na segunda, «white» na terceira, «yellow» na quarta etc. Assim, pode-se fazer uma lista de matérias que usa cores diferentes para as linhas pares e impares:

<B_asmaterias>
   <ul>
<BOUCLE_asmaterias(ARTICLES) {par titre}>
   <li style="background: [(#COMPTEUR_BOUCLE|alterner{'white','yellow'})]">#TITRE</li>
</BOUCLE_asmaterias>
   </ul>
</B_asmaterias>

-  |inserer_attribut{attribut,valeur} permite incluir um atributo HRML numa tag HTML gerada pelo SPIP. Por exemplo: [(#LOGO_DOCUMENT||inserer_attribut{'alt',#TITRE})] insere um atributo «alt» contendo o título do documento na tag «img» do logo.

-  |extraire_attribut{attribut} é o inverso do filtro precedente. Permite recuperar um atributo de uma tag HTML gerada pelo SPIP. Por exemplo, pode-se encontrar o caminho da miniatura gerada pelo filtro:
<div style="background: url([(#LOGO_ARTICLE||image_reduire{90}|extraire_attribut{src})]) left;"]>#TEXTE</div>

-  |vider_attribut{attribut} é uma variante de inserer_attribut. Permite remover os atributos HTML. Por exemplo, [(#LOGO||vider_attribut{width})] remove o atributo ’width’ da imagem de um logo (que ideia!)

-  |parametre_url{parametre,valeur} é um filtro que permite adicionar parâmetros num URL gerado por uma tag SPIP. Se valeur for '' o filtro remove um parâmetro correntemente no URL. Por exemplo, a tag #SELF devolve o URL da página atual, então:

• [(#SELF|parametre_url{'id_article','12'})] inserirá uma variável id_article igual a 12 no URL,
• [(#SELF|parametre_url{'id_article',''})] apagará o id_article atualmente no URL.

Empregado com um único parâmetro, o filtro age diferentemente:
#URL...|parametre_url{x} extrai o parâmetro ’x’ do URL e devolve o valor.

Pode-se, por exemplo, utilizá-lo para criar botões para navegar pelos documentos de uma página:

<BOUCLE_actual(DOCUMENTS) {id_document}>
  #LOGO_DOCUMENT
  <ul>
  <BOUCLE_anterior(DOCUMENTS) {par date} {age_relatif <= 0} {0,1} {exclus}>
  <li>
    <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="précédent">
      [(#LOGO_DOCUMENT||image_reduire{70})]
    </a>
  </li>
  </BOUCLE_anterior>
  <BOUCLE_seguinte(DOCUMENTS) {par date} {age_relatif > 0} {0,1}>
  <li>
    <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="suivant">
      [(#LOGO_DOCUMENT||image_reduire{70})]
    </a>
  </li>
  </BOUCLE_seguinte>
  </ul>
</BOUCLE_actual>

|ancre_url{ancre} Por exemplo [(#URL_ARTICLE|ancre_url{ancre})].

Filtros técnicos

-  |entites_html transforma um texto em entidades HTML, que se pode implantar num formulário, por exemplo: [<textarea>(#DESCRIPTIF|entites_html)</textarea>]

-  |texte_script transforma qualquer campo numa string usável pelo PHP ou Javascript com toda a segurança, por exemplo: <?php $x = '[(#TEXTE|texte_script)]'; ?>. Atenção: use corretamente o caracter ' e não ": com efeito, no segundo caso, se o seu texto contém o símbolo $, o resultado pode ser catastrófico (exibição parcial, exibição de outra coisa, travamento do PHP etc.).

-  |attribut_html torna uma string usável sem perigo como atributo HTML; por exemplo, se deseja incluir um texto flutuante ao link normal para uma matéria, use <a href="#URL_ARTICLE"[ title="(#DESCRIPTIF|attribut_html|couper{80})"]>#TITRE</a>.

-  |liens_absolus aplica-se a uma tag de texto para transformar todos os links que ela contém em links absolutos, prefixando o protocolo (http ou https) e o nome de domínio correntes. Este filtro é particularmente útil nos templates de feed RSS, por exemplo. Para forçar um determinado URL de base, é possível passá-lo como argumento, por exemplo #TEXTE|liens_absolus{#URL_SITE_SPIP}

-  |url_absolue funciona da mesma maneira que o filtro precedente, mas aplica-se a uma tag que devolva um URL (por exemplo, #URL_ARTICLE). Assim como o filtro liens_absolus, este filtro aceita um URL de base como parâmetro opcional.

-  |abs_url combina os dois filtros precedentes, podendo-se aplicar a um texto ou a uma tag de URL. Aceita o mesmo parâmetro opcional.

-  |form_hidden Se fizermos um formulário que usa como ação um link contendo argumentos (por exemplo, quando se usa a tag #SELF com o tipo de URL padrão), é preciso inserir esses valores em campos hidden; esta função calcula os campos em questão. Por exemplo:

<form action="#SELF">
[(#SELF|form_hidden)]
...
</form>

-  O filtro |compacte permite reduzir o tamanho de um CSS ou Javascript, removendo todos os comentários. O filtro recebe como entrada o nome do ficheiro e produz um novo ficheiro cujo nome ele devolve <link rel="stylesheet" href="[(#CHEMIN{spip_style.css}|compacte)]" type="text/css" media="all" />.

-  Outros filtros técnicos são apresentados nesta página e em code.spip.net.

Incluir os seus próprios filtros

Os filtros do SPIP são funções PHP que recebem a tag na qual eles são aplicados como primeiro parâmetro e devolvem o texto a ser exibido. Você pode usar diretamente as funções habituais do PHP, mas igualmente criar as suas, no modelo:

function me_filtro($texte) {
    $texte = (truques em PHP) ...;
    return $texte;
}

Para não modificar os ficheiros do SPIP (o que corre o risco de serem sobrepostos numa próxima atualização), você pode instalar as suas funções pessoais num ficheiro mes_fonctions.php: se o SPIP encontra um ficheiro com esse nome, ele o inclui automaticaemente.

O ficheiro pode ser gravado:

• no diretório onde estão armazenados os seus templates
• na raiz do site
  Mas jamais em ambos simultaneamente.

É possível definir filtros aplicáveis unicamente a um template particular.
Para tal, cria-se num ficheiro article_fonctions.php, os filtros que só serão efetivos no template article.html.
Atenção: este ficheiro xxxx_fonctions.php deverá encontrar-se no mesmo diretório do template xxxx.html.

Filtros com parâmetros

É possível passar parâmetros aos filtros. A sintaxe é:
[(#BALISE|filtro{arg1, arg2}|...)]
O filtro deve ser definido da seguinte maneira, em mes_fonctions.php:

function filtro($texto, $arg1='valor padrão 1', $arg2='valor padrão 2') {
    ....cálculos....
    return (uma string);
}

Pode-se assim chamar qualquer função PHP, ou apoiar-se em funções definidas no SPIP ou em mes_fonctions.php, por menos que elas respeitem a ordem dos argumentos (o texto a processar deve ser imperativamente o primeiro argumento). Por exemplo, para remover os pontos ao final de um texto, pode-se fazer: [(#TEXTE|rtrim{'.?!'})].

Os argumentos dos filtros podem ser tags (sem códigos opcionais nem filtros). Por exemplo:
[(#TOTAL_BOUCLE|=={#COMPTEUR_BOUCLE}|?{'Fim.',''})]
Pode-se usar uma tag com cotação extendida como parâmentro. Por exemplo:
[(#DESCRIPTIF|sinon{[(#CHAPO|sinon{#TEXTE}|couper{300})]})]