De filters van SPIP

Filters voor pagina-indeling (achterhaald)

De filters voor de pagina-indeling (hoofdletters, uitlijnen, ...) worden niet langer aanbevolen. De voorkeur moet worden gegeven aan het gebruik van de overeenkomende CSS stijlen.

-  |majuscules zet de tekst in hoofdletters. In vergelijking met de overeenkomstige PHP functie, zet majuscules ook letters met een accent in hoofdletters.

-  |justifier past een volledige uitlijning toe (<P align=justify>).

-  |aligner_droite lijnt een teksts rechts uit (<P align=right>).

-  |aligner_gauche lijnt een tekst links uit (<P align=left>).

-  |centrer centreert de tekst (<P align=center>).

Datumfilters

De volgende filters kunnen op een datum worden toegepast (bijvoorbeeld [(#DATE|affdate)]).

-  |affdate geeft de datum in tekstvorm weer, bijvoorbeeld «13 januari 2001»;

Een extra parameter kan worden toegevoegd voor het formatteren van die datum, ofwel met een SPIP formaat (zoals «'saison'» voor het seizoen) of volgens dat van het PHP commando date («'Y-m-d'»). Bijvoorbeeld:

• [(#DATE|affdate{'Y-m'})] geeft het jaar en de maand numeriek weer gescheiden door een streepje,
• de notatie [(#DATE|affdate{'saison'})] komt volledig overeen met: [(#DATE|saison)] en resulteert in lente, zomer, herfst of winter.

-  Er bestaan ook varianten van affdate die als shortcut kunnen worden gebruikt:

|affdate_jourcourt resulteert in de naam van de maand en de numerieke dag, zoals «19 april». Valt de datum niet in het huidige jaar, dan wordt ook het jaar weergegeven: «1 november 2004».

|affdate_court resulteert in de naam van de maand en de numerieke dag, zoals «19 april». Valt de datum niet in het huidige jaar, dan worden alleen de maand en het jaar weergegeven: «November 2004».

|affdate_mois_annee geeft alleen de maand en het jaar weer: «April 2005», «November 2003».

|affdate_heure toont de datum, gevolgd door de tijd: «3 april 2005 om 20:00».

-  |jour toont alleen de dag (als getal).

-  |mois toont de maand (als getal).

-  |annee toont het jaar.

-  |heures geeft het tijdselement van een datum weer (de data in SPIP bevatten naast de datum zelf ook het tijdstip).

-  |minutes toont de minuten van een datum.

-  |secondes toont de seconden.

-  |nom_jour toont de naam van de dag (maandag, dinsdag...).

-  |nom_mois toont de naam van de maand (januari, februari...).

-  |saison toont het seizoen (lente, zomer...).

-  |unique geeft uitsluitend de waarde van het gefilterde element teruggeeft wanneer het voor de eerste keer verschijnt. Het filter kan niet alleen op een datum worden toegepast, maar is bijvoorbeeld ook interessant voor het op datum weergeven van een lijst van artikelen:

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

het baken toont de maand en het jaar alleen bij een verandering van maand.

Nog een voorbeeld:

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

Dit produceert een lijst die er zo uit zou kunnen zien:

   2005
        maart
                artikel uit maart
                nog een artikel uit maart
        februari
                artikel uit februari
   2004
        december
                een artikel

We gebruiken de notatie |affdate{'Y-m'} om ieder jaar de naam van de maand weer te geven, want:

• hadden we slechts #DATE|nom_mois|unique, dan zouden de namen van de maand alleen in het eerste jaar worden weergegeven.
• hadden we: #DATE|unique|nom_mois gebruikt, dan zagen we alle data. Feitelijk retourneert #DATE een complete datum, inclusief tijdstip. Er is dus een grote kans dat twee op dezelfde datum gepubliceerde artikelen in de database niet dezelfde data hebben.

Daarom nemen we alleen de maand en het jaar voordat we het filter unique toepassen.

We kunnen een optioneel argument aan het filter toevoegen om twee verschillende toepassingen te kunnen gebruiken. Bijvoorbeeld: [(#DATE|affdate_mois_annee|unique{hier})] heeft geen invloed op [(#DATE|affdate_mois_annee|unique{daar})].

Tekstfilters

-  |liens_ouvrants transformeert SPIP links die naar een externe site verwijzen in een «popup», die opent in een nieuw venster (of nieuw tabblad), wat overeenkomt met target=_blank in HTML.

-  |supprimer_numero dient voor het verwijderen van een numerieke prefix in bijvoorbeeld een titel, waar we door middel van deze prefix artikelen willen sorteren met {par num titre} maar dat niet aan de gebruikers willen laten zien. Het formaat van deze prefix moet zijn «XX. Titel», waarbij XX een (onbepaald) aantal cijfers kan zijn.

-  |PtoBR zet de sprong naar een nieuwe paragraaf om in een eenvoudige regelterugloop, wat bijvoorbeeld bij een overzichtspagina een rustiger beeld geeft.

-  |taille_en_octets zet een aantal bytes (25678906) om naar een meer expliciete weergave («24.4 Mb»).

-  |supprimer_tags veroorzaakt een verwijdering van alle bakens <...>

-  |textebrut heeft overeenkomsten met het filter supprimer_tags, maar gaat iets meer subtiel om met die verwijdering waarbij paragraafeinden en een <br> worden omgezet in een regelterugloop en ondeelbare spaties (&nbsp;</cite>) door gewone spaties worden vervangen. Eén van de toepassingen is bij het aanmaken van de omschrijving in de META data: <code>[<meta name="description" content="(#DESCRIPTIF|textebrut)">]

-  |texte_backend converteert een tekst in een foraat dat bruikbaar is in XML, zoals een RSS feed. Het is dan ook terug te vinden in het backend skelet dat de RSS feed van de site aanmaakt.

-  |couper breekt een tekst af na een bepaald aantal tekens. Daarbij probeert het een woord niet doormidden te breken maar wordt de formattering wel aangetast. Is de tekst te lang dan wordt «(...)» aan het eind toegevoegd. Standaard breekt het filter af op 50 tekens, maar je mag een andere lengte als parameter aangeven, bijvoorbeeld: [(#TEXTE|couper{80})].

-  |lignes_longues kort «te lange» woorden in (nuttig wanneer bijvoorbeeld een URL in een beperkte ruimte moet worden weergegeven). Standaard wordt tot 70 tekens ingekort, maar je kunt een andere lengte als parameter opgeven, bijvoorbeeld: [(#URL_SITE|lignes_longues{40})].

-  |match gebruikt een rationele uitdrukking (regexp) (vgl. preg_match()) om uit een tekst een motief te halen wanneer die aanwezig is. Wordt het motief niet gevonden dan is het resultaat leeg. Om bijvoorbeeld het eerste woord uit een titel te nemen, kunnen we schrijven [(#TITRE|match{^\w+?})]. Het kan ook een simpele tekst zijn en het resultaat zal "Nieuws" zijn als een artikel wordt gevonden met de opdracht [(#TITRE|match{Nieuws})].

-  |replace gebruikt ook een rationele uitdrukking (regexp) (vgl. preg_replace()) voor het verwijderen of vervangen van een bepaald gegeven in de tekst. Met één parameter, een relationele uitdrukking, zal het doel worden verwijderd. Om bijvoorbeeld alle "notaXX" uit een tekst te verwijderen geef je de opdracht [(#TEXTE|replace{nota\d*})].
Wanneer een tweede parameter wordt opgegeven, vraag je om een vervanging. Om bijvoorbeeld overal in de tekst 2005 en 2006 te vervangen door 2007 wordt het:[(#TEXTE|replace{200[56],2007})]. Ook kun je weer een simpele tekst gebruiken, zoals vervang overal "MijnSite" door "MijnNieuweSite": [(#TEXTE|replace{MijnSite,MijnNieuweSite})]

Testfilters

-  |sinon geeft aan wat moet worden weergegeven als het "gefilterde" element leeg is. Dus [(#TEXTE|sinon{"geen tekst"})] geeft de tekst weer, maar als het veld leeg is, wordt «geen tekst» weergegeven.

-   breidde het bovenstaande filter uit met |?{welwaar,nietwaar}. Je kunt het één of twee parameters meegeven:

• welwaar moet worden weergegeven in plaats van het gefilterde element wanneer het resultaat niet leeg is.
• nietwaar is optioneel. Het is wat moet worden weergegeven wanneer het resultaat leeg is.
  [(#TEXTE|?{#TEXTE,"geen tekst"})] is dus het equivalent van het filter dat we hierboven bij het filter |sinon als voorbeeld gebruikten.

-  SPIP 1.8 introduceerde een set filters om vergelijkingen met waardes te kunnen doen:

• |=={waarde} en |!={waarde} laten je verifiëren, of de onderlinge elementen respectievelijk wel of niet aan elkaar gelijk zijn.
  Bijvoorbeeld:
  <li [(#TITRE|=={Editoriaal}|?{'id="edito"',''})]>#TITRE</li>

• |>{waarde}, |>={waarde}, |<{waarde} en |<={waarde} vergelijken het gefilterde element (dat numeriek moet zijn) met een numerieke waarde.
  Bijvoorbeeld:
  [(#TOTAL_BOUCLE) [(#TOTAL_BOUCLE|>{1}|?{'artikel','artikelen'})] in deze rubriek.]

  Opmerking: In algemene zin mogen alle vergelijkingsoperators van PHP gebruikt worden als filter.

Logofilters

-  |fichier gekoppeld aan een logo resulteert in de naam van het bestand van dat logo.

-  ||overige filters In tegenstelling tot voorafgaande versies liet SPIP 1.4 toe zogenaamde "custom" filters op een logo toe te passen: tussen SPIP 1.4 en SPIP 2.1 was de logica een beetje krom omdat ze een compatibiliteit met SPIP 1.3 moest bieden. De analyse is als volgt:

• wanneer het eerste «filter» geen uitlijning is, neemt SPIP aan dat het een URL is en krijgt het logo een hotlink naar dit adres;
• is het eerste filter wel een uitlijning, dan neemt SPIP aan dat het tweede «filter» een URL is;
• de daarop volgende filters zijn worden als echte filters behandeld (waaronder custom filters die zijn gedeclareerd in mes_fonctions.php;
• om een filter toe te passen zonder URL, moet je twee verticale balken (pipes) plaatsen. Bijvoorbeeld:
  <?php $logo = '[(#LOGO_RUBRIQUE||texte_script)]'; ?> haalt het logo uit de PHP variabele $logo, om hem daarna te kunnen bewerken (zie hieronder de betekenis van |texte_script).

Vanaf SPIP 2.1 hebben de logofilters dezelfde syntax als alle andere. Een enkele pipe volstaat: [(#LOGO_XXX|filter)]

Maar:
-  #LOGO_XXX** stuurt het bestand
-  #LOGO_XXX{top/left/right/center/bottom} zorgt voor alineëring
-  #LOGO_XXX{url} maakt een logo met een hotlink naar een URL.

-  de filters |hauteur en |largeur geven informatie terug over de afmetingen (respectievelijk de hoogte en breedte) van het gefilterde element wanneer dat een afbeelding is.

Deze filters hebben maar weinig belang bij een logo, omdat er al een #HAUTEUR en #LARGEUR voor beschikbaar is. Maar je kunt ze toepassen na toepassing van het filter |image_reduire (wat een afbeelding verkleint) om de juiste afmetingen na die bewerking te weten te komen.

Je kunt ze toepassen op elk baken (of filter) dat een HTML-tag <img ...> weergeeft.

-  |image_reduire{breedte,hoogte} forceert een maximale breedte en/of hoogte van een afbeelding of logo door verkleining.

Je kunt dit filter bijvoorbeeld op de vogende wijze op het logo van een artikel toepassen:

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

In dit voorbeeld wordt het logo rechts gealiniëerd met een maximale grootte van 130 pixels.

Je kunt twee argumenten aan het filter toevoegen: breedte en hoogte. Wanneer één van beide argumenten 0 is, houdt SPIP alleen met het andere argument rekening. Je kunt dit filter ook toepassen op het baken #TEXTE wat ervoor kan zorgen dat alle afbeeldingen doe in de tekst zijn opgenomen met behulp van SPIP opmaakcodes worden gereduceerd als ze te hoog en/of breed zijn.

Zo zorgt bijvoorbeeld

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

dat in de tekst opgenomen afbeeldingen niet breder worden weergegeven dan 600 pixels, wat problemen met het uitlijnen van de layout van de site kan voorkomen.

NB. Wanneer de optie «aanmaken van miniatuurafbeeldingen» in de configuratie van de site is geactiveerd, worden deze gereduceerde logo’s specifieke, door de server bewerkte afbeeldingen (in het ideale gevallen met de op de server geïnstalleerde GD2 extensie) van door de server geaccepteerde formaten (met GD2 zijn dat meestal JPG en PNG). Anders is het de volledige afbeelding die door de browser via HTML parameters op het juiste formaat wordt weergegeven.

Mathematische filters

SPIP 1.9 introduceerde een serie filters met wiskundige bewerkingen.

-  |plus{xx}, |moins{xx} en |mult{xx} corresponderen respectievelijk met optellen, aftrekken en vermenigvuldigen.

-  |div{xx} correspondeert met de niet-euclidische deling ("na de komma").

-  |modulo{xx} komt overeen met de rest van een gewone deling van een getal door xx.

Bijvoorbeeld [(#COMPTEUR_BOUCLE|modulo{5})] telt van 0 tot 4 en wordt daarna weer 0 enz.

Ook alle mathematische PHP functies mogen als filter worden toegepast.

Overige filters

-  |traduire_nom_langue kan worden toegepast op het baken #LANG en geeft een vertaling van de teruggegeven taalcode (fr, en, nl, enz.) in die taal.

Let op: De vertaling van de codes wordt gedaan in de taal van die code en volgt de schrijfconventies van die taal.

Zo wordt «fr» vertaald in «français» in kleine letters, maar wordt «es» vertaald in «Español» met een hoofdletter.

-  |alterner{a,b,c,...} kan worden gebruikt bij een numeriek baken (meestal #COMPTEUR_BOUCLE of #TOTAL_BOUCLE) en geeft het argument dat overeenkomt met de waarde van het baken. Zo kan de weergave in een lus worden afgewisseld. Bijvoorbeeld [(#COMPTEUR_BOUCLE|alterner{'white','yellow'})] toont «white» bij de eerste iteratie van de lus, «yellow» bij de tweede, «white» bij de derde, «yellow» bij de vierde, enz. Zo kan een lijst van artikelen worden gemaakt waarvan de kleur afwisselt voor even en oneven regels:

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

-  |inserer_attribut{attribut,valeur} voegt een HTML attribuut toe aan een door SPIP in een baken gegenereerde HTML. Bijvoorbeeld: [(#LOGO_DOCUMENT||inserer_attribut{'alt',#TITRE})] gaat het attribuut «alt» met als waarde de titel van het document toevoegen aan de HTML tag «img» van het logo.

-  |extraire_attribut{attribut} doet (bijna) het omgekeerde van het hierboven omschreven filter. Het haalt een attribuut op uit een door SPIP gegenereerde HTML tag. Zo kun je bijvoorbeeld het adres terugvinden van een door het filter gegenereerd logo:
<div style="background: url([(#LOGO_ARTICLE||image_reduire{90}|extraire_attribut{src})]) left;"]>#TEXTE</div>

-  |vider_attribut{attribut} is een variant van inserer_attribut en zorgt voor de daadwerkelijke verwijdering van een HTML attribuut. Zo verwijdert [(#LOGO||vider_attribut{width})] het attribuut ’width’ uit de afbeelding van een logo (wat een idee!)

-  |parametre_url{parameter,waarde} is een filter dat parameters kan toevoegen aan een door een SPIP baken gegenereerde URL. Komt waarde overeen met '' dan haalt SPIP die parameter volledig uit de URL. Het baken #SELF retourneert de URL van de huidige pagina, dus:

• [(#SELF|parametre_url{'id_article','12'})] zet een variabele id_article met waarde 12 in de URL,
• [(#SELF|parametre_url{'id_article',''})] verwijdert de variabele id_article en zijn waarde uit de URL.

Met een enkele parameter reageert het filter afwijkend:
#URL...|parametre_url{x} retourneert de waarde van URL-parameter ’x’.

Je kunt dit bijvoorbeeld gebruiken om knoppen te maken om tussen de documenten op een pagina te navigeren:

<BOUCLE_huidige(DOCUMENTS) {id_document}>
  #LOGO_DOCUMENT
  <ul>
  <BOUCLE_vorige(DOCUMENTS) {par date} {age_relatif <= 0} {0,1} {exclus}>
  <li>
    <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="vorige">
      [(#LOGO_DOCUMENT||image_reduire{70})]
    </a>
  </li>
  </BOUCLE_vorige>
  <BOUCLE_volgende(DOCUMENTS) {par date} {age_relatif > 0} {0,1}>
  <li>
    <a href="[(#SELF|parametre_url{'id_document',#ID_DOCUMENT})]" title="volgende">
      [(#LOGO_DOCUMENT||image_reduire{70})]
    </a>
  </li>
  </BOUCLE_volgende>
  </ul>
</BOUCLE_huidige>

|ancre_url{anker} voegt een HTML anker toe (of wijzigt het). Bijvoorbeeld [(#URL_ARTICLE|ancre_url{anker})].

Technische filters

-  |entites_html verandert een tekst in een HTML entiteit die in een formulier kan worden toegevoegd: [<textarea>(#DESCRIPTIF|entites_html)</textarea>]

-  |texte_script zet ieder willekeurig veld om in een in PHP of Javascript veilig toepasbare tekenreeks, bijvoorbeeld: <?php $x = '[(#TEXTE|texte_script)]'; ?>. Let op: maak goed gebruik van het enkele aanhalingsteken ' en niet van "; anders zal, wanneer je tekst het symbool $ bevat, het resultaat katastrofische gevolgen kunnen hebben (gedeeltelijke weergave, onjuiste weergave, vastlopen van PHP, enz.).

-  |attribut_html geeft een als HTML attribuut leesbare reeks fie geen schade kan berokkenen. Als je bijvoorbeeld een tekst wilt weergeven wanneer de muis over een link wordt bewogen, gebruik je <a href="#URL_ARTICLE"[ title="(#DESCRIPTIF|attribut_html|couper{80})"]>#TITRE</a>.

-  |liens_absolus kan worden toegepast op een tekstbaken en zet alle eventuele links om in absolute links door toevoeging van het protocol (http of https) en de naam van de host. Dit filter is in het bijzonder interessant in skeletten voor het aanmaken van RSS feeds, maar ook voor nieuwsbrieven. Om een specifieke basis URL door te geven kan een extra argument worden toegevoegd, bijvoorbeeld #TEXTE|liens_absolus{#URL_SITE_SPIP}

-  |url_absolue werkt op dezelfde manier als de vorige filters, maar wordt toegepast op een baken dat in een URL resulteert (zoals #URL_ARTICLE). Net als liens_absolus Accepteert dit filter een basis URL als optionele parameter.

-  |abs_url combineert de twee voorafgaande filters en kan dus zowel op een tekst als op een URL worden toegepast, eventueel met dezelfde optionele parameter.

-  |form_hidden Wanneer in een formulier een actie uit een link met argumenten bestaat (bijvoorbeeld met het baken #SELF met het standaard type URL), moeten deze waarden hidden velden zijn. Deze functie berekent de velden in kwestie. Een toepassingsvoorbeeld:

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

-  Met het filter |compacte kan de grootte van een CSS of een JavaScript worden gereduceerd door alle commentaren te verwijderen. Het filter neemt de naam van het bestand als bron en creëert een nieuw bestand waarvan hij de naam doorgeeft in de vorm <link rel="stylesheet" href="[(#CHEMIN{spip_style.css}|compacte)]" type="text/css" media="all" />.

-  Een aantal ander technische filters wordt beschreven op deze pagina en op code.spip.net.

Je eigen functies toevoegen

De filters in SPIP zijn PHP functies die het baken waarop ze van toepassing zijn als eerste parameter ontvangen en de weer te geven tekst retourneren. Je kunt direct de gebruikelijke PHP filters toepassen, maar ook je persoonlijke filters maken volgens het model:

<?php
function mijn_filter($tekst){
    $tekst = (PHP knutselwerk) ...;
    return $tekst;
}
?>

Om de bestanden van SPIP niet aan te hoeven passen (en het risico te lopen dat je aanpassingen bij een volgende update van SPIP worden overschreven), kun je je privé functionaliteit installeren in een bestand mes_fonctions.php. SPIP zal automatisch naar een bestand met die naam zoeken en zijn inhoud meenemen.

Het bestand mag zich bevinden:

• in de map waar ook je skeletten staan
• in de site root
  Maar nooit tegelijk in beide.

Zo heeft ARNO* het filter |enlettres ontwikkeld, dat niet in de core van SPIP is opgenomen. Met dit filter kan een getal in Franse woorden worden geschreven ( [(#DATE|annee|enlettres)] = « deux mille deux »). Je kunt het filter downloaden op http://www.uzine.net/spip_contrib/a... en je hoeft het daarna alleen maar de inhoud toe te voegen aan je bestand mes_fonctions.php om het filter te kunnen gebruiken.

Je kunt ook een filter definiëren dat uitsluitend op één specifiek skelet van toepassing is.
Hiervoor schrijf je in bestand article_fonctions.php de filters die uitsluitend in een skelet article.html moeten worden toegepast.
Let op: dit bestand xxxx_fonctions.php moet zich op hetzelfde niveau (in dezelfde map) bevinden als het skelet xxxx.html.

Filters met parameters

Je kunt aan een filter parameters doorgeven. De syntax is:
[(#BAKEN|filter{arg1, arg2}|...)]
Het filter moet op de volgende wijze in mes_fonctions.php worden gedefinieerd:

function filter($tekst, $arg1='standaard waarde1', $arg2='standaard waarde2')
{
    ....bewerkingen....
    return (een reeks tekens);
}

Op deze manier kun je dus iedere willekeurige PHP functie gebruiken, of je beperken tot de (ruime hoeveelheid) in SPIP gedefinieerde functies of die in mes_fonctions.php en dat alles op voorwaarde dat ze de volgorde van argumenten respecteren (de te verwerken tekst moet beslist het eerste argument zijn). Om bijvoorbeeld het leesteken aan het einde van een tekst te verwijderen, kun je schrijven: [(#TEXTE|rtrim{'.?!'})].

De argumenten van een filter mogen ook bakens zijn (maar zonder optionele gegevens of filters). Bijvoorbeeld:
[(#TOTAL_BOUCLE|=={#COMPTEUR_BOUCLE}|?{'Einde.',''})]
Ook mogen bakens met een uitgebreide notatie als parameter worden gebruikt. Bijvoorbeeld:
[(#DESCRIPTIF|sinon{[(#CHAPO|sinon{#TEXTE}|couper{300})]})]