Los filtros de SPIP

Los filtros de fechas

Los filtros siguientes se aplican a las fechas ([(#DATE|affdate)] por ejemplo).

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

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

|affdate_heure muestra la fecha seguida de la hora: «3 Avril 2005 à 20h00min».

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

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

-  annee devuelve el año.

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

-  minutes devuelve los minutos de una fecha.

-  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é...).

-  el filtro unique 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

Véase también el artículo sobre filtros de texto.

-  |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})].

-  |match utiliza una expresión regular (cf. preg_match()) para extraer un patrón del texto si está presente, en caso contrario no devuelve nada. Por ejemplo, para recuperar la primera palabra del título [(#TITRE|match{^\w+?})]. Puede ser un simple texto, mostrando "toto" si está en el título: [(#TITRE|match{toto})]

-  |replace también utiliza una expresión regular (véase preg_replace()) para borrar o reemplazar todas las apariciones de un patrón en el texto. Con un único parámetro, una expresión regular, el patrón se sustituirá por una cadena, es decir, se eliminará.
Por ejemplo, para eliminar todos los "notaXX" del texto [(#TEXTE|replace{nota\d*})]. Cuando se introduce un segundo parámetro, las apariciones del patrón se sustituyen por este valor. Por ejemplo, para sustituir todas las apariciones de 2005 o 2006 en el texto por 2007 .[(#TEXTE|replace{200[56],2007})]. Pueden ser textos sencillos; sustituye todos los "au temps" por "autant": [(#TEXTE|replace{au temps,autant})]

Filtros de comprobación

-  |?{afirmativo,negativo} es una versión evolucionada de |sinon. Toma uno o dos parámetros:

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

-  |sinon 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».

-   |oui devuelve un espacio o nada. Equivale a |?’ ’,’’ ou |?’ ’ y se utiliza para devolver contenido no vacío (un espacio) para indicar que se deben mostrar las partes opcionales de las etiquetas.

-   |non es la inversa de |oui y equivale a |?’’,’ ’

-   |et permite comprobar la presencia de 2 elementos

-   |ou comprueba la presencia de uno de los dos elementos

-   |xou comprueba la presencia de uno solo de los dos elementos.

SPIP también comprenderá los equivalentes ingleses "yes", "not", "or", "and" y "xor".

// muestra el título si existe, en caso contrario el inicio del texto
[(#CHAPO|sinon{#TEXTE|couper{200}})]
 // muestra "Este título es largo" sólo si el título tiene más de 30 caracteres.
[(#TITRE|strlen|>{30}|oui) Este título es largo ]
 
[(#CHAPO|non) No hay ningún chapo ]
[(#CHAPO|et{#TEXTE}) Hay un chapo, y un texto ]
[(#CHAPO|et{#TEXTE}|non) No se pueden tener las dos cosas juntas ]
[(#CHAPO|ou{#TEXTE}) O hay un chapo o hay un texto, o las dos cosas. ]
[(#CHAPO|ou{#TEXTE}|non) No hay chapo ni texto ]
[(#CHAPO|xou{#TEXTE}) O hay chapo o hay texto (pero no las dos cosas, o ninguna) ]
[(#CHAPO|xou{#TEXTE}|non) No hay nada o todo, pero no uno de los dos ]

-   Filtros para hacer comparaciones con valores:

• |=={valor} et |!={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} et |<={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.

Filtros de logos

Los filtros de logos tienen la misma sintaxis que los demás:
[(#LOGO_XXX|filtro)]

Pero :
-  #LOGO_XXX** devuelve el archivo
-  #LOGO_XXX{top/left/right/center/bottom} genera una alineación
-  #LOGO_XXX{url} genera un logotipo apuntando a la url.

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

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

Filtros matemáticos

-  |plus{xx}, |moins{xx} y |mult{xx} corresponden a la suma, la resta y la multiplicación, respectivamente.

-  |div{xx} corresponde a la división no euclidiana ("después del punto decimal").

-  |modulo{xx} es el resto de la división euclídea de un número por xx.

Por ejemplo [(#COMPTEUR_BOUCLE|modulo{5})] cuenta de 0 a 4 y luego vuelve a 0, etc.

Además, todas las funciones matemáticas de PHP pueden utilizarse como filtros.

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,...} 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{attribut,valeur} 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{attribut} 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{parametre,valeur} 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

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

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.php: 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.php para utilizarlo.

Filtros con parámetros

Como se ha mencionado al principio es posible pasar parámetros adicionales a los filtros. La sintaxis es:

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

El filtro debe ser definido en mes_fonctions.php 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.php, 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{'.?!'})].

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

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