Los filtros de SPIP

En La sintaxis de las balizas SPIP vimos que es posible modificar el comportamiento y el resultado de las balizas SPIP aplicándoles filtros. Aquí se presentan los principales filtros que vienen con SPIP, y además se aprende como crear uno sus propios filtros.

El sintaxis general de los filtros que no llevan otros parámetros que la baliza (la gran mayoría) es el siguiente:

[ opción anterior (#BALIZA|filtro1|filtro2|...|filtron) opción posterior ]

Los filtros 1, 2, ..., n se aplican sucesivamente a la baliza #BALIZA.

Los filtros de paginación y formato

Ya no se aconseja utilizas los filtros de paginación siguientes (majuscules, justifier...). Se recomienda, en adelante, la utilización preferente de los estilos CSS correspondientes.

-  majuscules pasa el texto a mayúsculas. Comparado con la función equivalente en PHP, el filtro SPIP majuscules también se aplica a las letras acentuadas.

-  justifier pasa el texto a justificación total. Es decir que aplica a todos los párrafos el atributo justify: (<P align=justify>).

-  aligner_droite pasa el texto a justificación alineada a la derecha (atributo <P align=right>).

-  aligner_gauche pasa el texto a justificación alineada a la izquierda (atributo <P align=left>).

-  centrer centrar el texto en la página. (atributo <P align=center>).

Los filtros de fechas

Los filtros siguientes se aplican a las fechas ((#DATE por ejemplo). Los filtros de fecha utilizan el idioma del contexto.

-  affdate devuelve la fecha en forma de texto, por ejemplo, «13 de enero de 2001» si #DATE es el 13/1/2001.

[SPIP 1.8] extiende la notación de este filtro. Se le puede pasar un parámetro de presentación de la fecha, que corresponda a un formato SPIP («'saison'», etc.) o a un formato de la instrucción php date'Y-m-d'»). Por ejemplo:

  • [(#DATE|affdate{'Y-m'})] mostrará numéricamente el año y el mes que corresponden a la fecha filtrada, separados por un guión,
  • la notación [(#DATE|affdate{'saison'})] es totalmente equivalente a: [(#DATE|saison)].

-  También existen variantes de affdate que ofrecen atajos:

affdate_jourcourt muestra el nombre del mes y el valor numérico del día, e.g. «19 de Abril». Si la fecha no es del año en curso, también se muestra el año: «1 de Noviembre de 2004».

affdate_court muestra el nombre del mes y el número del día, e.g. «19 de Abril». Si la fecha no es del año en curso, entonces sólo se muestra el mes y el año: «Noviembre de 2004».

affdate_mois_annee muestra sólo el mes y el año: «Abril de 2005», «Noviembre de 2003».

-  jour devuelve el día (en números, del 1 al 31).

-  mois devuelve el mes (en números).

-  annee devuelve el año.

-  [SPIP 1.0.2] heures devuelve las horas de una «fecha» (los campos de fecha registradas automáticamente por SPIP en su base comprenden no sólo la fecha en sí, sino también la hora exacta).

-  [SPIP 1.0.2] minutes devuelve los minutos de una fecha.

-  [SPIP 1.0.2] secondes devuelve los segundos.

-  nom_jour devuelve el nombre del día de la semana (lunes, martes,... o lundi, mardi...).

-  nom_mois devuelve el nombre del mes (enero, febrero,... o janvier, février...).

-  saison devuelve la estación (invierno, verano,... o hiver, été...).

-  [SPIP 1.8] introduce el filtro unique que devuelve el valor del elemento filtrado sólo si es la primera vez que se lo encuentra. Este filtro no está limitado a las fechas pero es interesante, por ejemplo, para mostrar une serie de artículos por fecha:

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

esta baliza sólo mostrará la fecha a cada cambio de mes.

Veamos otro ejemplo:

<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>

devolverá una lista que se parece a esto:

   2005
        marzo
                artículo de marzo
                otro artículo de marzo
        febrero
                artículo de febrero
   2004
        diciembre
                un artículo

Se utiliza la notación affdate{'Y-m'} para mostrar el nombre del mes en cada año. Por cierto:

  • si sólo pusiéramos #DATE|nom_mois|unique, los nombres de mes sólo aparecerían el primer año.
  • si el filtrado fuera: #DATE|unique|nom_mois, se mostrarían todas las fechas. Efectivamente, recordemos que #DATE devuelve una fecha completa que también contiene la hora. Es decir que hay probabilidades muy elevadas que las fechas completas de dos artículos publicados el mismo día sean diferentes.

Por eso, guardamos sólo el mes y el año de la fecha antes de pasarla al filtro unique.

Se le puede pasar a este filtro un argumento opcional para diferenciar dos usos independientes del filtro. Por ejemplo: [(#DATE|affdate_mois_annee|unique{aqui})] no tendrá incidencia sobre [(#DATE|affdate_mois_annee|unique{aca})].

Filtros de texto

La mayoría de los filtros que siguen fueron introducidos en la versión [SPIP 1.4].

-  liens_ouvrants transforma todos los enlaces SPIP hacia sitios Web externos en enlaces de tipo «popup», que abren una nueva ventana ("enlaces abrientes"). Es el equivalente del atributo target=blank de la etiqueta <a> de HTML. Nota: los autores de SPIP estiman que tal comportamiento en una página Web es, en general, intrusivo y descortés. El internauta sabe si desea abrir otra ventana o no, y lo puede hacer fácilmente sin que el sistema se lo imponga. Pero la insistencia era demasiado fuerte, así que cedimos...;-)

-  supprimer_numero sirve para suprimir el número de un título, cuando, por ejemplo, uno quiere clasificar los artículos por número (criterio {par num titre}) pero no mostrar dichos números (los cuales así sirven sólo para ordenar los artículos). El formato de los prefijos numerados es « XX. título », siendo XX un número de n cifras (ilimitado). Atención, es necesario poner un punto y un espacio en blanco después del número.

-  PtoBR transforma los saltos de párrafo en simples retornos de línea, lo que permite «apretar» una paginación, por ejemplo en un sumario.

-  taille_en_octets permite transformar un número de bytes (por ejemplo 25678906) en una cadena de caracteres más explícita (en nuestro ejemplo: «24.4 Mb.»).

-  supprimer_tags es una supresión básica y brutal de todos los códigos entre <...>

-  textebrut se parece al filtro precedente supprimer_tags, pero actúa de manera algo más sutil, transformando en particular los párrafos y los <br> en cambios de línea y los espacios imborrables en espacios simples. Se puede utilizar, por ejemplo, para realizar un descriptivo META (de metadatos) a partir de la baliza #DESCRIPTIF: [<meta name='description' content='(#DESCRIPTIF|textebrut)'>]

-  texte_backend se puede utilizar para transformar un texto y hacerlo compatible con los flujos xml. Este filtro se utiliza, por ejemplo, en el esqueleto backend.html que genera el hilo rss del sitio.

-  couper corta un texto después de cierto número de caracteres Intenta no cortar las palabras y suprime el formato del texto. Si el texto es demasiado largo, entonces agrega «(...)» al final. La longitud por omisión es de 50 caracteres. Pero se puede especificar una longitud diferente pasándole un parámetro al filtro, por ejemplo: [(#TEXTE|couper{80})].

Filtros de comprobación

-  [SPIP 1.6] introduce el filtro |sinon, que indica lo que se debe mostrar si el elemento «filtrado» está vacío: es decir que [(#TEXTE|sinon{"no hay  texto"})] muestra el texto; salvo si éste está vacío en cuyo caso muestra «no hay texto».

-  [SPIP 1.8] introduce el filtro |?{afirmativo,negativo} que es una versión evolucionada de |sinon. Tiene uno o dos parámetros:

  • afirmativo es el valor que se devuelve en lugar del elemento filtrado si éste no está vacío.
  • negativo es opcional. Es el el valor que se devuelve si el elemento filtrado está vacío. [(#TEXTE|?{#TEXTE,"no hay texto"})] es equivalente al ejemplo dado en la documentación del filtro |sinon.

-  [SPIP 1.8] introduce un juego de filtros para hacer comparaciones con valores:

  • |=={valor} y |!={valor}permiten verificar, respectivamente, la igualdad o la desigualdad entre el elemento filtrado y un valor. Por ejemplo: <li [(#TITRE|=={editorial}|?{'id="edito"',''})]>#TITRE</li>
  • |>{valor}, |>={valor}, |<{valor} y |<={valor} compara el elemento filtrado (que debe ser numérico) con un valor numérico.
    Por ejemplo:
    [(#TOTAL_BOUCLE) [(#TOTAL_BOUCLE|>{1}|?{'artículos','artículo'})] en esta sección]

    .

    Nota: De manera general, todos los operadores de comparación de php pueden utilizarse como filtros en [SPIP 1.8].

Filtros de logos

Como vimos al presentar las balizas de logos (por ejemplo en el bucle ARTICLES, existe un manejo específico para los filtros de logos, que permite fácilmente determinar su posición y la dirección a la cual enlazan.

-  fichier [SPIP 1.4]. Aplicado a un logo, este filtro permite recuperar directamente el nombre del fichero que corresponde al logo (se trata del nombre relativo del fichero, que está situado en la carpeta IMG).

-  ||otros filtros Al contrario de las versiones anteriores, [SPIP 1.4] permite aplicar filtros «caseros» a los logos: la lógica es un poco rara, porque había que respetar la compatibilidad con SPIP 1.3. El análisis de los filtros se desarrolla así:

  • si el primer «filtro» no es una alineación, SPIP considera que se trata de una URL y enlaza el logo hacia esa dirección;
  • si el primer «filtro» es una alineación (gauche, droite), SPIP considera que el segundo filtro es una URL;
  • los filtros siguientes son «verdaderos» filtros, en el sentido habitual (incluidos los filtros «caseros» declarados en mes_fonctions.php3);
  • para aplicar un filtro cualquiera sin especificar un enlace hacia una URL, hay que poner dos barras. Por ejemplo : <?php $logo = '[(#LOGO_RUBRIQUE||texte_script)]'; ?> permite recuperar el logo en la variable php $logo, para un tratamiento ulterior (ver más abajo el significado de |texte_script).

-  [SPIP 1.8] introduce los filtros hauteur y largeur que devuelven las información sobre el tamaño (o sea, altura y longitud, respectivamente) del elemento filtrado si se trata de una imagen.

Estos filtros no tienen más que un interés medio para su aplicación directa en un logo de documento porque ya tenemos #HAUTEUR y #LARGEUR disponibles para los documentos. Por el contrario, se pueden aplicar tras el filtro reduire_image para saber el tamaño exacto de la imagen reducida.

Más en general, se pueden aplicar sobre cualquier baliza (o filtro) que devuelva una etiqueta HTML <img ...>.


-  SP<font color="yellow">IP 1.7.1 introduce el filtro |reduire_image (reducir_imagen), que permite forzar un tamaño máximo de visualización de un logo.

Este filtro se utiliza por ejemplo sobre un logo de artículo de la manera siguiente:

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

En este ejemplo, el logo del artículo aparece alineado a la derecha, con un tamaño máximo de 130 pixels.

Nota. Si la opción «creación de miniaturas» está activada en la configuración del sitio, estos logos reducidos serán archivos de imágenes específicos calculados automáticamente por el servidor (idealmente, con la extensión GD2 instalada en el servidor), para los formatos aceptados por éste (con GD2, habitualmente, los formatos JPG y PNG). Si no, lo que se muestra es una versión completa de la imagen; pero con el tamaño especificado directamente en HTML.

Otros filtros

-  traduire_nom_langue se aplica a la baliza #LANG y devuelve la traducción del código de idioma devuelto por la baliza (fr, en, it, etc.) en ese idioma.

Atención: Las traducciones de los códigos se hacen en el idioma representado por el código y siguen las convenciones de escritura de ese idioma.

Así «fr» se traducirá «français» en minúscula, mientras que «es» será traducido como «Español» con mayúscula.

-  alterner{a,b,c,...} [SPIP 1.8.2] se aplica a una baliza numérica (en general #COMPTEUR_BOUCLE o #TOTAL_BOUCLE) y muestra el argumento correspondiente al valor de esta baliza. Así se puede alternar la presentación en un bucle. Por ejemplo, [(#COMPTEUR_BOUCLE|alterner{'white','grey'})] mostrará «white» en la primera iteración del bucle, «grey» en la segunda, «white» en la tercera, «grey» en la cuarta, etc. Así, se puede hacer una lista de artículos que utilice un color diferente para las líneas pares e impares:

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

-  inserer_attribut{atributo,valor} [SPIP 1.8.2] permite añadir un atributo html en una baliza html generada por SPIP. Por ejemplo: [(#LOGO_DOCUMENT|inserer_attribut{'alt',#TITRE})] añadirá en la baliza «img» del logo un atributo «alt» con el título del documento.

-  extraire_attribut{atributo} [SPIP 1.8.2] es el inverso del filtro precedente. Permite recuperar un atributo desde una baliza html generada por SPIP. Por ejemplo, se puede hallar el camino de la miniatura generada por el filtro reduire_image: <div style="background: url([(#LOGO_ARTICLE||reduire_image{90}|extraire_attribut{src})]) left;"]>#TEXTE</div>

-  parametre_url{parámetro,valor} [SPIP 1.8.2] es un filtro que permite añadir parámetros en una url generada por una baliza SPIP. Si el valor vale '' el filtro suprime un parámetro que está actualmente en la url. Si el valor no se especifica, el filtro devuelve el valor actual del parámetro. Por ejemplo, la baliza #SELF devuelve la url de la página actual, por lo tanto:

  • [(#SELF|parametre_url{'id_article'})] recuperará el id_article presente en la url,
  • [(#SELF|parametre_url{'id_article','12'})] hará la variable id_article igual a 12 en la url,
  • [(#SELF|parametre_url{'id_article',''})] borrará el id_article que haya actualmente en la url.

Por ejemplo, se puede utilizar para crear botones para navegar entre los documentos de una página:

<BOUCLE_actual(DOCUMENTS) {id_document}>
  #LOGO_DOCUMENT
  <ul>
  <BOUCLE_precede(DOCUMENTS) {par date} {age_relatif <= 0} {0,1} {exclus}>
  <li>
    <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="anterior">
      [(#LOGO_DOCUMENT|reduire_image{70})]
    </a>
  </li>
  </BOUCLE_precede>
  <BOUCLE_sigui(DOCUMENTS) {par date} {age_relatif > 0} {0,1}>
  <li>
    <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="siguiente">
      [(#LOGO_DOCUMENT|reduire_image{70})]
    </a>
  </li>
  </BOUCLE_sigui>
  </ul>
</BOUCLE_actual>

Filtros técnicos

Estos filtros fueron introducidos por la versión [SPIP 1.4].

-  entites_html transforma un texto en entidades HTML, que se se pueden insertar en un formulario, por ejemplo: [<textarea>(#DESCRIPTIF|entites_html)</textarea>]

-  texte_script transforma cualquier baliza en una cadena de caracteres utilizable en PHP o en Javascript con total seguridad [1], por ejemplo : <?php $x = '[(#TEXTE|texte_script)]'; ?>. OjO: ten cuidado de utilizar el carácter ' y no " pues en el segundo caso, si tu texto contiene símbolos $, el resultado puede ser catastrófico (un resultado parcial, publicar otra cosa, colgar el php, etc.).

-  attribut_html devuelve una cadena utilizable sin peligro como atributo HTML; por ejemplo; si se quiere agregar un texto de sobrevuelo al enlace habitual a un artículo, se puede utilizar:

<a href="#URL_ARTICLE" [ title = "(#DESCRIPTIF|supprimer_tags|attribut_html)" ]>#TITRE</a>.

-  liens_absolus [SPIP 1.8.2] se aplica en una baliza de texto, y transforma todos los enlaces que esta contiene en enlaces absolutos (con la url completa del sitio). Este filtro es particularmente útil en los esqueletos del hilo rss, por ejemplo.

-  url_absolue [SPIP 1.8.2] funciona de la misma forma que el filtro precedente; pero se le aplica a una baliza que devuelve una url (por ejemplo #URL_ARTICLE).

-  abs_url [SPIP 1.8.2] combina las dos balizas precedentes, por lo que se puede aplicar a un texto o a una baliza de url.

Agregar funciones propias

Los filtros de SPIP son en realidad funciones PHP que reciben la baliza en la cual se aplican como primer parámetro y devuelven el texto que hay que mostrar. Puedes utilizar directamente las funciones habituales de PHP, pero también crear tus propias funciones siguiendo el modelo:

<?php
funcion mi_filtro($texto){
    $texto = (mi receta en PHP) ...;
    return $texto;
}
?>

Para no modificar ficheros de SPIP (que podrían ser reemplazados en una actualización posterior), puedes instalar tus funciones personales en un fichero mes_fonctions.php3: si SPIP encuentra un fichero con este nombre, lo incluye automáticamente.

Por ejemplo, ARNO* desarrolló el filtro enlettres, que no está incluido en la distribución estándar de SPIP. Este filtro escribe la denominación de un número en francés (si la fecha #DATE es en el año 2003, [(#DATE|annee|enlettres)] = « deux mille trois »). Puedes bajar este filtro de http://www.spip-contrib.net/25-000-...; basta con agregarlo a tu fichero mes_fonctions.php3 para utilizarlo.

Filtros con parámetros

Como se ha mencionado al principio, desde [SPIP 1.5], es posible pasar parámetros adicionales a los filtros. La sintaxis es:

[(#BALIZA|filtro{arg1, arg2}|...)]

El filtro debe ser definido en mes_fonctions.php3 de la manera siguiente :

function filtro($texto, $arg1='valor por omision1', $arg2='valor por omision2')
{
    ....cálculos....
    return (una cadena de caracteres);
}

Así, se puede llamar a cualquier función php, o apoyarse en funciones definidas en SPIP o en mes_fonctions.php3, con la única condición de respetar el orden de los argumentos (el texto que se debe tratar tiene que ser obligatoriamente el primer argumento). Por ejemplo, para quitar la puntuación al final de un texto, se podrá llamar: [(#TEXTE|rtrim{'.?!'})].

Desde [SPIP 1.8], los argumentos de los filtros pueden ser balizas (sin códigos opcionales ni filtros). Por ejemplo: [(#TOTAL_BOUCLE|=={#COMPTEUR_BOUCLE}|?{'Fin.',''})]

Desde [SPIP 1.8.2] se puede poner una baliza con notación extendida como parámetro. Por ejemplo: [(#DESCRIPTIF|sinon{[(#CHAPO|sinon{#TEXTE}|couper{300})]})]

Notas

[1en efecto, una vía de ataque contra un sitio Web puede consistir en insertar, donde sólo está previsto un texto, código ejecutable adecuadamente presentado. Al construir sitios complejos con SPIP que incluyen PHP es conveniente tener presente esto.

Autor o autora dani Publicado el: Actualizado: 26/10/12

Traducciones: عربي, català, Deutsch, English, Español, français, italiano, Nederlands