De modellen vormen een uitbreiding op de klassieke opmaakcodes <img1> en <doc1>. Toch corresponderen ook deze met de bestanden plugins-dist/medias/modeles/img.html en plugins-dist/medias/modeles/doc.html. [1]
Hun syntax werd uitgebreid waardoor het mogelijk werd om naast de alineëring (<img1|left>, <img1|right> of <img1|center>) een meer generieke klasse toe te voegen, die ofwel overeen komt met een bepaald skelet, of met een CSS class. Bijvoorbeeld: (<img1|klasse> zal eerst zoeken naar een model modeles/img_klasse.html en als dat niet bestaat wordt het model modeles/img.html gebruikt, maar met een parameter class="klasse").
Maar de modellen zijn niet beperkt tot afbeeldingen en documenten. Het is ook mogelijk een nieuwe "opmaakcode" te maken in de vorm <model1> door eenvoudig een skelet in de submap modeles/ van je map met skeletten toe te voegen!
Je moet de naam van het bestand gestructureerd opbouwen in kleine letters. Om het onderscheid dat sommige systemen maken tussen het_bestand01.html en Het_Bestand01.html, zoekt SPIP uitsluitend naar bestandsnamen in kleine letters.
Wanneer deze zoektocht geen model oplevert (bijvoorbeeld bij
<breve1>) gat het modelbeheer van SPIP kijken of het misschien in de naam een object herkent (hier:breve) en of daar een URL voor bestaat.<breve1> wordt niet in de modellen teruggevonden, maar SPIP herkent het object (een nieuwsbericht) en vindt er ook een URL voor. Daarom vervangt SPIP de opmaakcode
<breve1>door een opmaakcode naar de pagina voor nieuwsbericht 1 met de titel van dat nieuwsbericht als tekst, alsof we hadden aangeven:[->breve1]. Het verplichte getal is dus de identificatie van het object.Wordt het object niet herkend, dan laat SPIP het ongemoeid, want het zou mogelijk later door een andere analyse van de tekst (bijvoorbeeld van een plugin of een ander filter) kunnen worden verwerkt.
Het is ook mogelijk om extra parameters aan een model door te geven (zoals bij «embedded», documenten met opmaakcode <emb1|autostart=true>). De syntax accepteert zelfs HTML code, zoals in dit voorbeeld:
<geluid19|kleur=#ff0000
|subtitel=The great <i>Count Basie</i>
|foto=12>
wat een model modeles/geluid.html zou oproepen, dat de parameters zou kunnen gebruiken om foto nummer 12 weer te geven, met een kader in kleur #ff0000 en als subtitel de aangegeven tekst.
Let op: Om een eenvoudig model zonder parameters op te roepen moet je hem
- ofwel voorzien van een numerieke identificatie (bv.
bla <het_model1> bla) ; - ofwel laten volgen door een pipe
|(Bv.bla <het_model|> bla).
In het eerste geval wordt de doorgegeven identificatie opvraagbaar binnen het skelet het_model.html met #ENV{id} of #ENV{id_het_model} (wat dus 1 geeft in het voorbeeld);
in het tweede geval zal zowel #ENV{id} als #ENV{id_het_model} een waarde 0 hebben.
Toepassingen volop
Waarschijnlijk zijn alle mogelijke toepassingen voor modellen nog niet ontdekt. We geven er een paar waar wij aan gedacht hebben. Kom jij op een nieuw idee, deel het dan op SPIP Zone/SPIP Contrib’, waar je een rubriek over dit onderwerp vindt.
Probeer het maar met deze zoekopdracht!
- Het uiterlijk van de documentsnelkoppelingen aanpassen. Een veelgevraagde functionaliteit is de aanpassing van de ikonen die worden gebruikt voor een link naar een document. Dat was niet eenvoudig, omdat het een (PHP) wijziging in core van SPIP inhield. Tegenwoordig volstaat het om het bestand plugins-dist/medias/modeles/img.html te kopiëren naar de submap modeles/ in je map met skeletten en dit bestand aan te passen. En zo kun je dat ook doen voor de opmaakcodes <doc1> en <emb1>, hoewel deze laatste een zodanige complexiteit heeft, dat je ervoor zou kunnen terugdeinzen...
Let op: Begin niet aan het aanpassen van de modellen om kleine (cosmetische) aanpassingen te doen — het is vaak eenvoudiger de elementen van de stylesheets spip_documents_xx naar behoefte aan te passen.
- Geluid met een player weergeven. Een model modeles/son_player.html kan worden opgeroepen met <son12|player>.
- Een site aan een artikel koppelen. Door aan je skeletten een model modeles/site_box.html toe te voegen, maak je onmiddellijk een nieuwe opmaakcode <site1|box> beschikbaar. Het model maak je (met de klassieke lussen) zodanig dat het de naam van de site weergeeft, gevolgd door een link naar de laatste 3 gesyndiceerde artikelen in een kader rechts van het logo van de site. Zo heb je een infobox die ge gemakkelijk in een artikel kunt opnemen. Een parameter kan het aantal weer te geven artikelen aangeven, enz.
- Een afbeelding als afgestempelde postzegel weergeven. Zodra je weet hoe je een afbeelding weer kunt geven in de vorm van een afgestempelde postzegel (zoals De Gefrankeerde Site), volstaat het dit stukje programmeertaal op te nemen in modeles/zegel.html om de opmaakcode <zegel12> beschikbaar te maken. En daar kun je dan weer parameters voor zijn afmeting, de kleur of het type poststempel aan toevoegen [2].
- Een "composiet" artikel maken. Stel je voor dat je een artikel wilt maken dat is opgebouwd uit de «chapo» (de kop) van artikel 1 en de tekst van artikel 2. Supereenvoudig: je maakt twee modellen (modeles/article_tekst.html en modeles/article_kop.html) die respectievelijk de introductie (chapo en de texte van een gevraagd artikel retourneren. In het artikel zelf zet je in de kop: <article1|kop> en in het tekstveld: <article2|tekst>. En daar kunnen dan ook weer allerlei filters, bakens en andere bewerkingen op worden losgelaten...
Een praktische toepassing op een informatieve site is om op deze manier dynamische gegevens in meerdere artikelen weer te geven (denk bijvoorbeeld aan een tabel van belastingschijven, of het minimum loon). Bij een verandering hoef je slechts de inhoud van één artikel aan te passen om overal de nieuwe waardes te tonen.
- Eén artikel in meerdere rubrieken weergeven. Bij het maken van de modellen <article1|kop>, <article1|tekst> enz, wordt het mogelijk een «fantoom » artikel te maken in een andere rubriek (met als extraatje de mogelijkheid het bijvoorbeeld een andere titel te geven).
- Een enquete uitvoeren. De plugin Forms die het maken van formulieren mogelijk maakt die vervolgens met een opmaakcode <form1> aan een artikel toe te voegen, is ook herschreven in de vorm van modellen.
- Een wisselend citaat weergeven. Wanneer je citaten aan je nieuwsberichten wilt toevoegen, kan een opmaakcode <citaat|willekeurig> met behulp van de voorwaarde {par hasard}{0,1} in het model modeles/citaat_willekeurig.html worden opgenomen.
- Een document toevoegen in een andere taal dan de taal van het artikel. De modellen werken zoals insluitingen (INCLURE...), wat betekent dat de parameter lang=xx altijd beschikbaar is. Wanneer één van je documenten meertalig is (bijvoorbeeld met een «bloc multi» in de omschrijving), kun je die omschrijving in een andere taal dan die van het artikel weergeven met <doc1|left|lang=en>. Wanneer het skelet van het model meertalige tekstreeksen bevat, zullen die worden verwerkt in de taal die als parameter werd meegegeven.
- Een grafiek weergeven. Je geeft een tabel van gegevens door aan het model dat de grafiek zal aanmaken en in de tekst zal opnemen.
- Een tussentitel als afbeelding. Waarom geen opmaakcode <tekstbeeld|texte=Mijn tussentitel>?
Parameters in overvloed
De syntax van de opmaakcode voor modellen is <model12>, <model|parameter1=dit|parameter2=dat> of <model12|alineëring|parameter1=enz.>. De parameters mogen bestaan uit HTML en uit SPIP opmaakcodes (op voorwaarde natuurlijk dat de modellen zodanig zijn ontworpen dat ze die parameters kunnen verwerken).
Om conflicten met HTML tags te voorkomen, mag een model niet worden opgeroepen in de vorm <model>, die geen cijfers of het symbool | bevat.
De parameters mogen over verschillende regels worden verspreid wat de schrijfwijze verduidelijkt:
<model 10
|land=Duitsland
|bevolking=82000000
|oppervlakte=357027
|klassement=63
|volkslied=<i>Das Lied der Deutschen</i>
|url=http://nl.wikipedia.org/wiki/Duitsland
>Het skelet ontvangt alle parameters in het baken #ENV, dus #ENV{bevolking} geeft 82000000. Dit baken is beveiligd tegen het (opzettelijk) injecteren van javascript. Wil je HTML in een parameter toestaan, dan volstaat het om de notatie #ENV*{volkslied} te gebruiken; en wil je vervolgens de typografie van SPIP toepassen, dan kun je gebruikmaken van [(#ENV*{volkslied}|typo)] of [(#ENV*{volkslied}|propre)].
De hoofdparameter (hier: 10) wordt op twee manieren doorgegeven: #ENV{id}=10 en #ENV{id_model}=10. Wil je hem dus gebruiken in een model dat wordt opgeroepen met <article3|kop>, dan schrijf je in het model:
<BOUCLE_a(ARTICLES){id_article}>#CHAPO</BOUCLE_a>
maar wil je de hoofdparameter bijvoorbeeld gebruiken om een bepaald trefwoord weer te geven, dan schrijf je: <BOUCLE_b(BREVES){id_mot=#ENV{id}}>#TITRE</BOUCLE_b>
Je kunt de modellen zo ingewikkeld maken als je wilt, maar denk erom: je moet het ook aan de gebruikers (de redacteurs van je site) uitleggen hoe ze werken!
Toepassing in skeletten
De modellen kunnen niet alleen worden gebruikt voor het gebruik als opmaakcodes in teksten van artikelen. Je kunt ze ook vanuit een skelet oproepen met behulp van het baken #MODELE{model} of [(#MODELE{model}{parameter1=dit,parameter2=dat}{p3=enz}|filter...)], wat overeenkomt met de (statische) invoeging van een skelet (wat ook kan met het baken #INCLURE).
De standaardmodellen
SPIP wordt geleverd met de volgende modellen:
- img, doc en emb,
- article_mots en article_traductions. De geven respectievelijk de lijst van de trefwoorden die aan een artikel zijn gekoppeld, et de vertalingen van een artikel (opmaakcode: <article1|mots> en <article1|traductions>, maar deze modellen worden ook gebruikt in de skeletten in dist/article.html);
- lesauteurs , wat het resultaat van het baken #LESAUTEURS weergeeft, maar niet als opmaakcode kan worden aangeroepen;
- en een serie modellen voor pagina-navigatie (zie De indeling in meerdere pagina’s).
Enkele tips voor het schrijven van een model
Denk eerst na over de syntax die je wilt gaan aanpassen: is het model aan één specifiek artikel gekoppeld? Zo ja, dan begin je met een <article1|xxx>.
Wanneer je dit hebt bepaald, maak je het bestand modeles/article_xxx.html en je plaatst daarin simpelweg het baken: #ENV. In een testartikel neem je nu de shortcut <article1|xxx|param=x...> en wanneer je dit bekijkt zie je (op een wat cryptische wijze) de context die aan het model werd doorgegeven. Je vindt er onder andere de identificatie van het artikel (met de naam #ENV{id} en #ENV{id_article}) in terug.
Vervolgens kun je beginnen met de opbouw van het skelet voor het pagina-fragment: <BOUCLE_x(ARTICLES){id_article}> of <BOUCLE_x(ARTICLES){id_article=#ENV{id}}>. En ga zo maar door...
Om het model volledig te testen, probeer je de volgende syntax versies uit: <article1|xxx|left> en [<article1|xxx>->www.spip.net].
In het eerste geval moet de parameter align=left ervoor zorgen dat het model op de juiste wijze wordt uitgelijnd.
In het tweede geval wordt de link in een parameter doorgegeven lien=http://www.spip.net, alsmede de class van die link lien_class=spip_out. Het wordt aanbevolen de URL ergens in het model om te zetten in een hotlink (bijvoorbeeld met zijn titel of met een ikoon). In dat geval moet je aan de eerste HTML tag vanhet model een class="spip_lien_ok" toevoegen die de modellenbeheerder van SPIP vertelt dat de link moet worden gebruikt (anders zal de modellenbeheerder een <a href=...>...</a> toevoegen rond het resultaat van het model).
Voor wat betreft de parameters gaven we al aan dat het baken #ENV{x} standaard de injectie van ongewenste HTML of Javascript tegengaat. Wanneer in een model wel HTML in de parameters moet worden toegelaten, moet je dus gebruik maken van #ENV*{x} om deze gegevens in te lezen en ze vervolgens eventueel te filteren met |propre of |typo, afhankelijk van het soort gegevens (een tekst bestaande uit meerdere paragrafen, of een eenvoudige regel met "platte" tekst).
Voor wat betreft de programmering wordt aanbevolen altijd van de SPIP bakens gebruik te maken, zonder toevoeging van PHP of dynamische bakens. In een model waarin PHP wordt gebruikt, wordt het resultaat van de berekening in de cache geplaatst en niet het script zelf (zoals bij skeletten).
Lees ook het artikel article 3715