Dit artikel beschrijft hoe je 'artikel templates' ontwikkelt. Dit zijn artikelen met een voorgedefinieerde structuur en een bepaalde opmaak die gebruikt kunnen worden door website beheerders om content op een voorgedefinieerde manier op een website te publiceren.
Formulier definitie
De formulieren worden gedefinieerd in XML. De XML moet voldoen aan een aantal richtlijnen om geldig te zijn:
- De root tag van de XML moet altijd 'form' zijn
- Een formulier heeft een 'id' tag
- Een formulier kan children hebben, Deze worden gedefinieerd in de children tag
Voorbeeld van een minimale implementatie (een leeg formulier met een tekst element):
<form>
<id>some_Form_Id</id>
<children>
<single-text>
<id>some_Element_Id</id>
<title>This is the element title</title>
</single-text>
</children>
</form>
Zoals je kan zien bevatten zowel het formulier als het 'single-text' element een ID. Deze ID's komen als ID in de output van de HTML elementen van het formulier en moeten dus de regels van de HTML specificatie volgen.
Formulier secties
Je kan secties toevoegen aan je formulier om de leesbaarheid en structuur te verbeteren.
Voorbeeld
<form>
<id>some_Form_Id</id>
<children>
<section>
<id>some_Section_Id</id>
<title>Section title</title>
<children>
<single-text>
<id>some_Element_Id</id>
<title>This is the element title</title>
</single-text>
</children>
</section>
</children>
</form>
Zichtbaarheidscondities
Zichtbaarheidscondities gebruik je om elementen afhankelijk te maken van de waarden die zijn geselecteerd bij andere velden.
Voorbeeld
Indien de waarde van 'button_urltype' gelijk is aan 'option1', toon dan het veld 'nodeId'. Indien de waarde van 'button_urltype' gelijk is aan 'option2', toon dan het veld 'url'.
<radiogroup>
<id>button_urltype</id>
<title>URL-type</title>
<isRequired>true</isRequired>
<elemInfo>
<option id="option1" title="Link naar een pagina binnen het CMS"/>
<option id="option2" title="Link naar een externe pagina"/>
</elemInfo>
</radiogroup>
<single-node>
<id>nodeId</id>
<title>Selecteer een pagina...</title>
<isRequired>true</isRequired>
</single-node>
<single-text>
<id>url</id>
<title>Vul een geldige URL in</title>
<isRequired>true</isRequired>
</single-text>
<conditions>
<visibility>
<target>nodeId</target>
<calculate>button_urltype</calculate>
<formula>button_urltype == 'option1'</formula>
</visibility>
<visibility>
<target>url</target>
<calculate>button_urltype</calculate>
<formula>button_urltype == 'option2'</formula>
</visibility>
</conditions>
Wil je de zichtbaarheid van meerdere velden tegelijk sturen, dus met één check/select meerdere velden tonen of verbergen, dan kun je meerdere targets binnen één conditie gebruiken. Dit werkt alleen met één zichtbaarheidsconditie.
<conditions>
<visibility>
<target>nodeId</target>
<target>url</target>
<calculate>button_urltype</calculate>
<formula>button_urltype == 'option1'</formula>
</visibility>
</conditions>
Wil je meerdere condities gebruiken, bijvoorbeeld als je 3, 4 of nog meer secties wilt schakelen, gebruik dan meerdere condities met ieder één target en de operator `>=`.
<select>
<id>contactPersonNumber</id>
<title>Aantal contactpersonen</title>
<elemInfo>
<option id="1" title="1" />
<option id="2" title="2" />
<option id="3" title="3" />
<option id="4" title="4" />
<option id="5" title="5" />
<option id="6" title="6" />
<option id="7" title="7" />
<option id="8" title="8" />
<option id="9" title="9" />
</elemInfo>
<defaultValue>3</defaultValue>
</select>
<visibility>
<target>contactPerson_3</target>
<calculate>contactPersonNumber</calculate>
<formula>contactPersonNumber >= 3</formula>
</visibility>
<visibility>
<target>contactPerson_4</target>
<calculate>contactPersonNumber</calculate>
<formula>contactPersonNumber >= 4</formula>
</visibility>
<visibility>
<target>contactPerson_5</target>
<calculate>contactPersonNumber</calculate>
<formula>contactPersonNumber >= 5</formula>
</visibility>
<visibility>....
Vertalingen
De titles, subTitles en options zijn meertalig te maken als dat nodig is. De syntax hiervoor is als volgt
XML voorbeeld voor title en subTitle
<title>
<string lang='nl'>Nederlandse titel</string>
<string lang='en'>English title</string>
</title>
<subTitle>
<string lang='nl'>Ondertitel</string>
<string lang='en'>Subtitle</string>
</subTitle>
XML voorbeeld options in elemInfo
<elemInfo>
<option id="opt1" title-nl="Optie 1" title-en="Option 1" />
<option id="opt2" title-nl="Optie 2" title-en="Option 2" />
<option id="opt3" title-nl="Optie 3" title-en="Option 3" />
</elemInfo>
Elementen
Elementen hebben verplichte en optionele tags. Deze tags bepalen hoe de formulier elementen worden gerenderd voor de gebruiker bij het bewerken van het artikel.
De title is het label dat voor het invoerveld verschijnt en is dus zichtbaar voor de gebruiker. Bij de optionele tags staan de standaard waarden tussen haakjes.
Formulier element: één checkbox (checkbox)
- Verplichte tags: id, title
- Optionele tagsdefaultValue (0), isRequired (false)
XML voorbeeld
<checkbox>
<id>checkbox_element</id>
<title>Title for element</title>
<isRequired>false</isRequired>
<defaultValue>1</defaultValue> // 1 => checked, 0 => unchecked
</checkbox>
Formulier element: radio buttons (radiogroup)
- Verplichte tags: id, title, elemInfo
- Optionele tags: isRequired (false)
XML voorbeeld
<radiogroup>
<id>radiogroup_element</id>
<title>Title for element</title>
<isRequired>false</isRequired>
<elemInfo>
<option id="option1" title="Option 1 title" />
<option id="option2" title="Option 2 title" />
<option id="option3" title="Option 3 title" />
</elemInfo>
</radiogroup>
Formulier element: selectbox (select)
- Verplichte tags: id, title, elemInfo
- Optionele tags: isRequired (false)
XML voorbeeld
<select>
<id>select_element</id>
<title>Title for element</title>
<isRequired>false</isRequired>
<elemInfo>
<option id="option1" title="Option 1 title" />
<option id="option2" title="Option 2 title" />
<option id="option3" title="Option 3 title" />
</elemInfo>
<defaultValue>option1</defaultValue>
</select>
HTML editor (html-editor)
- Verplichte tags: id, title
- Optionele tags: isRequired (false), mode (singleline, minimal, simple, basic, advanced)
-
Output: twig-filter 'raw' toevoegen
{{ html_editor|raw }}
XML voorbeeld
<html-editor>
<id>html_editor</id>
<title>Edit some html...</title>
<mode>minimal</mode>
</html-editor>
Kleurkiezer (color-chooser)
- Verplichte tags: id, title
- Optionele tags: isRequired (false), mode (hex, rgba)
XML voorbeeld
<color-chooser>
<id>color</id>
<title>Color for element</title>
<isRequired>false</isRequired>
<mode>rgba</mode>
<defaultValue>0,0,0,0.5</defaultValue>
</color-chooser>
Link naar een interne pagina selecteren (single-node)
- Verplichte tags: id, title
- Optionele tags: isRequired (false)
XML voorbeeld
<single-node>
<id>node_id</id>
<title>Select a page...</title>
</single-node>
Eén of meerdere artikelen invoegen (articles)
- Verplichte tags: id, title
- Optionele tags: isRequired (false), subTitle, maxAmount, minAmount
XML voorbeeld
<articles>
<id>article_list</id>
<title>Select articles...</title>
</articles>
Formulier (survey) invoegen
- Verplichte tags: id, title
- Optionele tags: isRequired (false), subTitle
XML voorbeeld
<snippet>
<id>survey</id>
<title>Select form...</title>
</snippet>
Sectie die elementen bevat (section)
- Verplichte tags: id, title
- Optionele tags: children
XML voorbeeld
<section>
<id>section-id</id>
<title>Section title</title>
<children>
<multi-text>
...
</multi-text>
</children>
</section>
Selecteren uit Documenten: één afbeelding (single-image)
- Verplichte tags: id, title
- Optionele tags: isRequired (false)
XML voorbeeld
<single-image>
<id>image_id</id>
<title>Select an image...</title>
<isRequired>true</isRequired>
</single-image>
Selecteren uit Documenten: meerdere afbeeldingen (multiple-images)
- Verplichte tags: id, title
- Optionele tags: isRequired (false), minAmount (0), maxAmount (0)
XML voorbeeld
<multiple-images>
<id>image_id</id>
<title>Select multiple images...</title>
<isRequired>true</isRequired>
<minAmount>2</minAmount>
<maxAmount>10</maxAmount>
</multiple-images>
Selecteren uit Documenten: één document (single-document)
- Verplichte tags: id, title
- Optionele tags: isRequired (false)
XML voorbeeld
<single-document>
<id>document_id</id>
<title>Select a document...</title>
<isRequired>true</isRequired>
</single-document>
Tekst: één regel (single-text)
- Verplichte tags: id, title
- Optionele tags: maxlength (0), isRequired (false)
XML voorbeeld
<single-text>
<id>text_element</id>
<title>Title for element</title>
<isRequired>false</isRequired>
<maxlength>123</maxlength>
</single-text>
Tekst: meerdere regels (multi-text)
- Verplichte tags: id, title
- Optionele tags: maxlength (0), isRequired (false)
XML voorbeeld
<multi-text>
<id>multi_text_element</id>
<title>Title for element</title>
<isRequired>true</isRequired>
<maxlength>1000</maxlength>
</multi-text>
Video selecteren van externe dienst (video)
- Verplichte tags: id, title, maxWidth, maxHeight
- Optionele tags: isRequired (false)
XML voorbeeld
<video>
<id>video_element</id>
<title>Select a video...</title>
<maxWidth>max_width (integer)</maxWidth>
<maxHeight>max_height (integer)</maxHeight>
</video>
Lengte- en breedtegraden (Google Maps)
- Verplichte tags: id, title
- Optionele tags: isRequired (false)
XML voorbeeld
<google-maps-point>
<id>googlemapspoint</id>
<title>Google maps point</title>
<defaultValue>{"lng":51.9,"lat":5.3}</defaultValue>
<isRequired>true</isRequired>
</google-maps-point>
De template definitie
De templates worden opgemaakt als Twig-templates. Binnen deze templates kan je de informatie gebruiken die is ingevoerd in het formulier. Je doet dit door te verwijzen naar het ID van het element zoals je het hebt gedefinieerd in de formulier definitie.
Voorbeeld
Formulier definitie (gedeeltelijk)
<single-node>
<id>contact-page</id>
<title>Select a page...</title>
</single-node>
Template
<div>
<a href="{{ contact-page }}">Contact!</a>
</div>
Artikel templates toevoegen aan een UI
Om je artikel templates toe te voegen aan de UI volg je onderstaande instructies.
1. Maak de nodige bestanden aan in de UI
Elke artikel template krijgt een afzonderlijke map in de UI. In de folder moeten twee bestanden staan. De CSS is optioneel:
- form.xml: de definitie van het formulier
- template.html.twig: de template
- style.css: de stylesheet die hoort bij dit artikel template
Voorbeeld
uidir/article-templates/testimonial/
form.xml
template.html.twig
testimonial.css
2. Beschikbare functies
In het .html.twig-bestand hebben we drie functies beschikbaar gemaakt om CSS, JS en afbeeldingen op de juiste manier in te laden
ArticleTemplate.loadCSS()
Met deze functie kan het CSS-bestand dat bij deze artikel template hoort ingeladen worden. Zonder deze functie wordt het CSS-bestand niet gebruikt. Het CSS-bestand moet dezelfde naam hebben als de subfolder waar deze in zit
Voorbeeld
{{ ArticleTemplate.loadCSS() }}
ArticleTemplate.loadJS()
Met deze functie kan het JS-bestand dat bij deze artikel template hoort ingeladen worden. Zonder deze functie wordt het JS-bestand niet gebruikt. Het JS-bestand moet dezelfde naam hebben als de subfolder waar deze in zit
Voorbeeld
{{ ArticleTemplate.loadJS() }}
getDocumentURL()
Velden waarin een afbeelding gekozen kan worden geven de ID van deze afbeelding terug in het twig-bestand. De url van de afbeelding die bij dit ID hoort kan getoond worden met onderstaande functie.
Voorbeeld
<img src="{{ getDocumentURL(image_id, {width: 1280, height: 395, zoom: true, public: true}) }}" />
Beschikbare opties tussen de accolades:
- width: de maximale breedte van de afbeelding
- height: de maximale hoogte van de afbeelding
- zoom: als de afbeelding groter is dan het aangegeven formaat, mag er dan bijgesneden worden
- color: als er niet bijgesneden mag worden, wordt de overgebleven ruimte opgevuld met deze kleur (voorbeeld: 'ffffff')
- public: is de afbeelding publiek beschikbaar
Afhankelijk van welke opties ingevuld worden wordt de afbeelding op een andere manier geschaald. Lees hier meer over op de pagina Afbeelding schaal-types.
3. Toevoegen aan het info.yml bestand
articleTemplates:
testimonial:
name: "Testimonial"
category: 5
Het 'testimonial' gedeelte moet overeenkomen met de naam van de subfolder van het artikel template. De 'category' bepaalt in welke artikel-categorie het artikel template verschijn in het CMS. De volgende opties kan je gebruiken:
- 1: media
- 2: relation
- 3: webshop
- 4: intranet
- 5: website
- 6: system
- 99: other
4. Scan de UI's
Zodra de structuur is aangemaakt ga je naar de artikel template beheer pagina (/article_template
). Klik hier op Scan Website Layouts/Update. Dit zorgt ervoor dat de het systeem wordt bijgewerkt met eventuele wijzigingen in artikel templates.
![](https://media.screensteps.com/image_assets/assets/008/281/105/original/db816af0-aa57-4500-83e9-3e377786fee2.png)