Artikel templates

Gewijzigd op Aug 28, 2024

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.

Vorige Artikel info.yml

Volgende Artikel ProDesign (ontwerpinstellingen)

Helpcenter

Artikel templates

Formulier definitie

Formulier secties

Zichtbaarheidscondities

Vertalingen

Elementen

Formulier element: één checkbox (checkbox)

Formulier element: radio buttons (radiogroup)

Formulier element: selectbox (select)

HTML editor (html-editor)

Kleurkiezer (color-chooser)

Link naar een interne pagina selecteren (single-node)

Eén of meerdere artikelen invoegen (articles)

Formulier (survey) invoegen

Sectie die elementen bevat (section)

Selecteren uit Documenten: één afbeelding (single-image)

Selecteren uit Documenten: meerdere afbeeldingen (multiple-images)

Selecteren uit Documenten: één document (single-document)

Tekst: één regel (single-text)

Tekst: meerdere regels (multi-text)

Video selecteren van externe dienst (video)

Lengte- en breedtegraden (Google Maps)

De template definitie

Artikel templates toevoegen aan een UI

1. Maak de nodige bestanden aan in de UI

2. Beschikbare functies

3. Toevoegen aan het info.yml bestand

4. Scan de UI's

CMS

Andere bronnen