Drupal 8 development: non-content | Deel 1/3: backend configuratie formulier

22 Apr 2017

Joris Snoek - Business Dev
+31 (0)20 - 261 14 99

Binnen een Drupal 8 website zijn meestal een aantal teksten die de content manager moet kunnen administreren, maar die geen echte content items zijn.

Wij lossen dit op door een gebruiksvriendelijk configuratie formulier te maken in het backend van Drupal 8, die toegankelijk is voor content managers. Hiermee kunnen we ervoor zorgen dat alle ‘non-content’ makkelijk te administreren is, waardoor content beheerders niet door allerlei schermen in een technisch backend hoeven te graven om juiste instellingen te vinden.

Een voorbeeld zijn de teksten (en afbeelding) in dit Frontpage header block:

Een voorbeeld van het bijbehorende Drupal 8 backend configuratie formulier:

Deze blog serie bestaat uit drie delen:

  1. Bouw van het Drupal 8 backend configuratie formulier en definiëren van een Twig template file.
  2. Implementatie van een Drupal 8 Block, waarin ingevoerde teksten uit het configuratie formulier opgehaald worden; ge-rendered in een custom Twig template file.
  3. Het beheerbaar maken van de achtergrond afbeelding, via het reeds gedefinieerde backend configuratie formulier.

In dit deel 1:

  1. Aanmaken nieuwe module met behulp van Drupal Console.
  2. Implementatie Drupal 8 backend configuratie formulier.
  3. Definiëring Twig template file -en variables, voor faciliteren van dynamische html in frontend.

1. Nieuwe module met behulp van Drupal Console

Drupal Console is een CLI tool om boilerplate code te genereren (ook wel skeleton code genoemd). Tevens biedt Console functies om acties binnen Drupal 8 uit te voeren -en te debuggen.

Drupal Console biedt tevens functies om Drupal forms te genereren, dat wil zeggen: boilerplate code dus. Hiervoor moeten we starten met het aanmaken van een nieuwe module waarin het form daarna geïmplementeerd wordt.

Genereer een nieuwe module mbv Drupal Console:

  1. Enter commando drupal generate:module in een terminal.
  2. Voer een naam in voor de nieuwe module. Wij gaan deze module alleen gebruiken voor configuratie doeleinden, dus ik noem hem ‘OpenLucius Configuration’.
  3. De gele tekst is de default die Console invoert als je enter intoetst zonder iets in te voeren. Deze default module machine name is prima, geef dus een enter.
  4. Hetzelfde geldt voor het module path. Het is een best practice in Drupal om de /modules map onder te verdelen in /contrib, /custom en /devel.
  5. Voer een omschrijving in, deze verschijnt in het Drupal 8 backend op het globale /config scherm.
  6. Ja, ik wil een .module file genereren. We hebben deze later nodig om hook_theme te implementeren, waar we een Twig template file in kenbaar maken aan Drupal. Daarin zal de dynamische html gaan leven.
  7. We hebben inderdaad een themeable template file nodig, zoals vermeld in (6). Deze zal standaard niet de juiste benaming genereren, maar het is handig als voorbeeld code.

2. Genereren Drupal 8 backend configuratie formulier

Volgende velden moeten door de content managers te beheren zijn:

  1. Frontpage header title
  2. Frontpage header subtitle
  3. Frontpage header intro text
  4. Frontpage header read more link
  5. Frontpage header background image

Nu zijn bijvoorbeeld Site name en Slogan velden die standaard in Drupal 8 core al aanwezig zijn en wellicht gebruikt kunnen worden als Frontpage header title en Frontpage header subtitle.

Maar voor het gemak van de content managers gebruiken we die Drupal core velden niet en maken we één overzichtelijk, gebruiksvriendelijk formulier waar alle non-content velden beheerbaar zijn. Dus geen versplintering van functies over allerlei technische admin-schermen, wat afschrikt voor een content manager.

Definiëring van velden en veldnamen doen we altijd engels, gezien het Drupal 8 backend altijd engels is en taal van development (code, comments, etc) ook. We houden het backend altijd engels voor consistentie in onder andere debugging en helpdesk issues van klanten.

Genereren van de velden

We starten met het aanmaken van de text fields, het image field behandelen we in deel 3 van deze blog serie.

Ik genereer het benodigde backend formulier in de nieuw aangemaakte module zoals hierboven beschreven. We maken het formulier en de tekst velden aan met behulp van de Drupal Console:

  1. Vanuit de webroot van je Drupal 8 installatie: enter drupal generate:form:config in een terminal.
  2. Geef aan in welke module je het formulier wilt plaatsen, je moet hem dus genereren in een bestaande module; daarom hebben we eerst de Drupal 8 module aangemaakt hierboven.
  3. Wil je services inladen? Lees meer over Services and dependency injection in Drupal 8. Voor dit voorbeeld niet nodig, geef een enter.
  4. Start met opbouwen van de formulier-velden door definiëren van het eerste veld, in dit voorbeeld start ik met genereren van het textfield ‘Frontpage Header Title’.
  5. Geef je veld een Label, deze tekst komt boven het veld te staan. Geef hier een heldere naam zodat Drupal content managers weten wat ze hier moeten invoeren.
  6. Configureer optionele waardes voor elementen behorende bij dit veld.
  7. Je kunt zo veel velden toevoegen als je wilt, totdat je bij “New field type (press to stop adding fields) [ ]:” dus een enter geeft zonder tekst in te voeren. Dan zullen nog enkele laatste vragen gesteld worden, waarna het formulier in de aangegeven module wordt gegenereerd:

  1. Zodra je alle elementen hebt ingevoerd, laat dit leeg en hit enter.
  2. Geef het gewenste path (route) in, deze default is prima. Meer over Drupal 8’s routing system hier
  3. De default Yes is goed, we willen graag dat hij verschijnt in het backend menu zodat content managers er makkelijk naar toe kunnen navigeren.
  4. Voer de titel in van dit gewenste menu item en plaats hem in dit default parent menu: hierdoor verschijnt hij in het backend menu van Drupal.
  5. Geef een omschrijving, welke verschijnt op de config overview page:

Drupal 8 Form API

Drupal 8 kent een uitgebreide Form API, waarin je kunt zien welke elementen en opties beschikbaar zijn. Voor meer info zie:

De map -en file structuur van de gegenereerde module ziet er zo uit:

De gegenereerde code voor het formulier:

Installeren module en Drupal 8 backend formulier

Installeer de module, zodat het gegenereerde formulier actief wordt. Dit kan met Drupal Console’s commando module:install :

Een link wordt aangemaakt in het configuratie scherm:

En de formulier detail pagina werkt:

Het formulier is direct bruikbaar, het opslaan van de waardes in de database werkt meteen:

3. Definiëring Twig template file en template variables, voor faciliteren van dynamische html in frontend.

Drupal Console heeft netjes een template file aangemaakt en deze gedefinieerd middels hook_theme(), zodat Drupal 8 deze herkend en we hem in modules kunnen aanroepen middels de Render API én/of deze in een Drupal 8 theme kunnen overriden.

Maar zoals Drupal Console hem gedefinieerd heeft is voor ons te generiek, ik wil hem graag specifieker hebben omdat er straks meerdere Twig template files bij gaan komen. Tevens wil ik Twig template variables toevoegen, om de html dynamisch te maken. Die variabelen zullen de ingevoerde teksten van de content managers gaan faciliteren waardoor het geheel dynamisch beheerbaar wordt via het backend formulier.

Ter initiatie hiervan doe ik twee aanpassingen:

  1. Ik wijzig de template file van naam, zodat deze minder generiek is en we aan de naam al kunnen afleiden waar hij voor gebruikt wordt.
  2. Ik wijzig de Twig template definiëring in hook_theme(), zodat Drupal op de hoogte is van de 'nieuwe' Twig template file. Tevens heb ik hier template variables gedefinieerd, zodat Drupal weet welke variabelen beschikbaar zijn. Deze Twig variables zal ik in het volgende deel van dit blog verder implementeren en toelichten.

Twig en Drupal 8

Meer weten over Twig templating in Drupal 8? Hier klikken.

Plaatsen HTML in Twig template file

Als laatste actie in dit deel van deze blog serie plaats ik de (reeds ontwikkelde) HTML in de Twig template file:

Zoals je ziet heb ik meteen de Twig variabelen geplaatst, welke we het volgende deel zullen gaan ‘vullen’ met teksten die door de content manager ingevoerd zijn in het backend formulier.

Wrap up deel 1

Alrighty, we hebben nu een module aangemaakt en daarin een Drupal 8 backend formulier gegenereerd. Verder hebben we een Twig template file -en variables gedefinieerd, waardoor Drupal 8 weet dat onze template file bestaat en welke variabelen daarin gebruikt worden.

Maar we zien deze HTML nog nergens terug in het frontend én de teksten worden nog niet dynamisch geladen uit het configuratie formulier.

Hoe we dat gaan doen? Dat beschrijf ik in Deel 2, so stay tuned!

Comments

Nóg meer
kennis nodig?

Check ons ons blog archief >