De bouw van een Drupal 8 website | Deel 1: theme initiatie

21 Aug 2016

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

In deze blog serie leg ik uit hoe wij een nieuwe meertalige Drupal 8 site gebouwd hebben. In dit proces kregen we de benodigde HTML, CSS en Javascript statisch aangeleverd en bouwden we een custom Drupal 8 theme daarmee. We maakten dus geen gebruik van een Drupal core -of contrib theme.

Het gaat om deze website:

Deze Drupal 8 website bestaat uit pagina’s die opgebouwd zijn uit Drupal blocks, vandaar dat ik uitgebreid zal toelichten hoe wij deze blocks hebben opgebouwd. Verder is deze Drupal 8 website meertalig: Nederlands en Engels. Opgesomd ga ik uitleggen:

  1. Generieke structuur van een Drupal 8 theme
  2. Initiatie Drupal 8 theme en plaatsen aangeleverde assets: CSS, JS, fonts en afbeeldingen.
  3. Opknippen van aangeleverde HTML naar Twig template files (.html.twig files).
  4. Bepalen van de Drupal regions.
  5. Opbouwen homepage HTML middels blocks en Drupal en Twig template files.
  6. Opbouwen contact pagina middels blocks en Drupal 8 core contact formulier.
  7. Opbouwen overige pagina’s middels Drupal 8 blocks.

Basiskennis

Ik ga ervan uit dat je al enige ervaring hebt met Drupal:

  • Installatie en algemene configuratie van de Drupal 8 core, modules en themes.
  • Configureren van content types

Drupal 8 theme | De structuur

Wat is een Drupal 8 theme

Een theme is een verzameling bestanden die zorgen voor het uiterlijk van je Drupal website: wat de bezoeker ziet. Er is slechts één bestand vereist, de .info.yml, maar voor een compleet theme heb je meer bestanden nodig.

Drupal 8 maakt standaard gebruik van PHP templating engine Twig, onderdeel van het Symfony framework waar Drupal 8 op gebouwd is.

Waar plaats je het theme

Als je een custom theme aanmaakt, dan plaats je die in de /themes map. Let op dat de Drupal core themes onder de map /core/themes staat. Never ever plaats je je eigen theme daar, dat zou een core-hack zijn: een doodzonde.

Om je themes map georganiseerd te houden is het een best practice om deze onder te verdelen in de mappen:

  • /contrib: plaats hier alle themes die je download van Drupal.org
  • /custom: plaats hier alle theme die je zelf bouwt.

Elk individueel theme wordt geplaatst in een map met de naam van het betreffende theme. Die naam mag alleen kleine letters bevatten, moet starten met een letter en gebruik maken van underscores (_) in plaats van spaties.

De (gedeeltelijke) structuur voor onze installatie zal er zo uit komen te zien:

|-core
| |-modules
| |-themes
| | |-bartik
| | |-seven
..
|-modules
|-themes
| |-contrib
| |-custom
| | |-openlucius

Welke bestanden bevat een Drupal 8 theme

Zoals aangegeven zal een bruikbaar theme meer bestanden bevatten dan alleen de verplichte THEMENAAM.info.yml.

Over .yml files

Yaml (.yml) files zijn bestanden die bedoeld zijn voor data en niet voor markup. Dit zijn niet per sé Drupal 8 specifieke files: ze worden in andere programmeertalen ook gebruikt zoals C, Perl en Python. Binnen Drupal 8 worden ze voornamelijk gebruikt om definiëring en configuratie op te nemen; onderdeel van het Configuration Management Initiative

Een Drupal 8 theme houdt de volgende structuur aan:

|-THEMENAAM.breakpoints.yml
|-THEMENAAM.info.yml
|-THEMENAAM.libraries.yml
|-THEMENAAM.theme
|-config
| |-install
| | |-THEMENAAM.settings.yml
| |-schema
| | |-THEMENAAM.schema.yml
|-css
| |-style.css
|-js
| |-THEMENAAM.js
|-images
| |-background_frontpage_header.png
|-logo.png
|-screenshot.png
|-templates
| |-maintenance-page.html.twig
| |-node.html.twig

THEMENAAM.info.yml

Dit is de enige verplichte file van het theme, waarmee het theme wordt gedefinieerd en welke wordt herkend door Drupal 8. Extra ‘meta data’ wordt hier tevens in geplaatst, zoals:

  • description: korte omschrijving van het theme.
  • libraries: welke libraries staan waar.
  • block regions: gedefinieerde regions, meer info: zie verderop.
  • overrides: welke Drupal 8 core services wil je overriden en waar staan die overrides.

THEMENAAM.libraries.yml

Definieert de Javascript -en CSS libraries die het Drupal 8 theme gebruikt.

THEMENAAM.theme

Bevat PHP code waar voorbereidende logica geprogrammeerd kan worden: (pre)processing van de HTML output.

THEMENAAM.breakpoints.yml

Breakpoints zijn punten waarop een responsive webdesign moet veranderen om goed te tonen op verschillende apparaten. Hier worden deze breakpoints gedefinieerd.

/templates/

De template files implementeren de HTML code voor je Drupal 8 website. Drupal 8 template files hebben format THEMENAME.html.twig en moeten verplicht in deze submap geplaatst worden (in tegenstelling tot Drupal 7).

De Drupal 8 core levert een aantal template files mee. Als je bepaalde naming conventions aanhoudt voor template files in jouw eigen theme, dan zal Drupal automatisch zijn jouw templates gebruiken in plaats van de core templates. Waardoor je de HTML markup kunt overriden.

Plaats bijvoorbeeld het bestand node.html.twig in deze map en Drupal zal jouw versie gebruiken in plaats van de core versie: /core/modules/node/templates/node.html.twig

/css/

Het is een best practice om .css bestanden in de submap /css te plaatsen. Drupal 8 core themes structureren CSS bestanden conform de SMACCS style guide. CSS bestanden moeten gedefinieerd staan in de .libraries.yml file en kunnen overriden of uitgeschakeld worden in het .info.yml bestand.

/js/

Deze map bevat de Javascript bestanden voor het Drupal 8 theme. Om deze in te laden moeten ze tevens gedefinieerd zijn in de .libraries.yml file.

/images/

Het is een best practice om theme afbeeldingen in deze submap te plaatsen. Niet te verwarren met content afbeeldingen.

screenshot.png

Als je deze afbeelding plaatst, dan zal deze verschijnen op de Appearance backend pagina in Drupal 8. De locatie van screenshot.png zou je ergens anders kunnen plaatsen; die alternatieve locatie moet je dan definiëren in de .info.yml file.

logo.svg

Het logo van je website, welk meestal in de header aan je bezoekers getoond wordt. Dit logo kan ook geüpload worden in het Drupal 8 backend onder Appearance > Settings

Subthemes

Binnen Drupal 8 is het tevens mogelijk om met base-themes en sub-themes te werken. Subthemes zijn net als andere themes met het verschil dat zij resources van het base-theme overerven. Het is zelfs mogelijk om sub-sub-themes en sub-sub-sub-themes (en zo verder) te maken.

Ik zal in deze tutorial niet verder ingaan op sub-theming in Drupal 8.

Drupal 8 theme structuur | Regions

Zoals het woord al aangeeft: een region is een bepaalde regio in je Drupal 8 website, die gebruikt wordt om content in te plaatsen. Meer specifiek: deze content wordt opgenomen in blocks, die in regions geplaatst worden. Je kunt een block zien als een bouwsteen; regions geven je Drupal 8 website de layout waar je blocks (en dus content) in kan plaatsen.

Regions worden in het theme gedefinieerd in de .info.yml file

Drupal 8 core regions

Drupal 8 kent volgende standaard regions:

  • page.header: Items voor de header region.
  • page.primary_menu: Items voor primary menu region.
  • page.secondary_menu: Items voor de secondary menu region.
  • page.highlighted: Items voor de highlighted content region.
  • page.help: Dynamische help tekst, wordt voornamelijk gebruikt voor administratie-pagina’s.
  • page.content: De ‘main content’ van huidige pagina.
  • page.sidebar_first: Items voor de ‘first sidebar’.
  • page.sidebar_second: Items voor de ‘second sidebar’.
  • page.footer: Items voor de ‘footer region’.
  • page.breadcrumb: Items voor de ‘breadcrumb region’.

Als jouw custom theme geen regions definieert, dan heb je deze dus tot je beschikking.

Hidden regions

Als je dieper ingaat op Drupal 8 theming, dan zal je tevens volgende regions tegenkomen:

  • page_top
  • page_bottom

Dit zijn verborgen regions en zie je terug in html.html.twig, een template file die normaal gesproken niet wordt overridden in een custom theme. Deze regions worden gebruikt om HTML te plaatsen geheel aan het begin -of einde van de pagina, voor bijvoorbeeld:

Meer info over regions

Vind je hier.

Gratis Drupal site audit

Wij controleren uw Drupal website op meer dan 100 punten.

Krijg het rapport vrijblijvend in uw inbox!

Drupal 8 theme structuur | Template files

Template files bevatten de HTML die uiteindelijk naar de browser van je website bezoeker wordt gestuurd. Dit zijn alle files met extensie .html.twig. Als je de template files van het Drupal 8 core theme ‘Bartik ‘ bekijkt zie je dit:

Deze files volgen allemaal een door Drupal 8 bepaalde naming convention zodat Drupal weet welke template file hij waarvoor moet gebruiken. Dat kan variëren van een gehele pagina, tot het themen van een block, tot het themen van één klein select element. In feite kan je álle html die Drupal core genereert (of aanvullend nodig heeft) aanpassen naar custom HTML. Het maken van een theme met aangeleverde -dus 100% custom HTML- is hierdoor mogelijk.

De template files zijn opgedeeld in:

  • HTML voor de header
  • HTML voor de page
  • HTML voor regions
  • HTML voor blocks
  • HTML voor nodes
  • HTML voor taxonomy terms
  • HTML voor fields
  • HTML voor comments
  • HTML voor onderhoudspagina
  • HTML voor zoekresultaten

Als voorbeeld, dit zijn de naming conventions voor de node template files:

  1. node--nodeid--viewmode.html.twig
  2. node--nodeid.html.twig
  3. node--type--viewmode.html.twig
  4. node--type.html.twig
  5. node--viewmode.html.twig
  6. node.html.twig

Per pagina zal Drupal dit rijtje van boven naar beneden afgaan, de file die als eerste gedefinieerd is in het theme, die zal Drupal toepassen op betreffende item.

Zie hier een overzicht van alle template naming conventions.

Mocht dit wat abstract overkomen allemaal, don’t worry: in de daadwerkelijk implementatie die ik verderop in deze blog serie laat zien wordt alles duidelijker.

Implementatie custom Drupal 8 theme | Initiatie

Installatie Drupal 8

We startten met een nieuwe Drupal installatie. Download en installeer Drupal 8 vanaf deze pagina, of installeer middels de Drupal console met site:new.

Initiatie Drupal 8 theme

Ter initiatie maakten we de volgende theme structuur aan: de benodigde mappen en bestanden plaatsen we in drupal8 root/themes/custom/

openlucius
|-css
| |-base
| | |- css files
| |-components
| | |- css files
| |- mobile-overrides.css
| |- overrides.css
|-fonts
| |- font files
|-images
| |-backgrounds
| | |- images
| |-flags
| | |- images
| |-glyphicons
| | |- images
| |-gradients
| | |- images
|-js
| |-base
| | |- javascript-files
| |-components
| | |- javascript-files
|-templates
| |-block.html.twig
| |-block--system-branding.html.twig
| |-block--system-menu-block.html.twig
| |-node.html.twig
| |-page.html.twig
| |-page-title.html.twig
| |-region--header.html.twig
| |-status-messages.html.twig
|-logo.png
|-openlucius.info.yml
|-openlucius.libraries.yml
|-openlucius.theme

Aangeleverde Assets van het theme plaatsen

Alle aangeleverde assets van het theme hebben we onderverdeeld in de volgende mappen:

  • /css
  • /javascript
  • /images
  • /fonts

openlucius.libraries.yml

Alle CSS en JS files moet door Drupal herkend worden, dit doe je in openlucius.libraries.yml, bij ons ziet deze er als volgt uit:

<?php
global-styling:
 
version: VERSION
  css
:
   
base:
     
css/base/bootstrap.min.css: {}
     
css/base/vendor.css: {}
     
css/base/google-font.css: {}
   
component:
     
# General.
     
css/components/general/header.css: {}
     
css/components/general/base.css: {}
     
css/components/general/buttons.css: {}
     
# Homepage.
     
css/components/pages/page-home.css: {}
     
# Prices.
     
css/components/pages/page-prices.css: {}
     
# Tour.
     
css/components/pages/page-tour.css: {}
     
# Contact & Support
     
css/components/pages/page-contact.css: {}
     
# Footer
     
css/components/general/footer.css: {}
     
# Responsive
     
css/components/general/responsive.css: {}
     
# Overrides.
     
css/overrides.css: {}
     
css/mobile-overrides.css: {}
 
js:
   
js/base/jquery-migrate.min.js: {}
   
js/base/vendor.js: {}
   
js/components/headhesive.min.js: {}
   
js/components/vendor_footer.js: {}
   
js/contact.js: {}
   
js/custom.js: {}
 
dependencies:
   
# jQuery is not included by default, so we add it as a dependency
   
- core/jquery
?>

openlucius.theme

Extra logica die we nodig hebben voordat de HTML gerendeerd zullen we hier gaan plaatsen.

Niet geïmplementeerd: openlucius.breakpoints.yml

We hebben geen gebruik gemaakt van deze file, omdat benodigde breakpoints al aangeleverd zijn in de statische HTML/CSS die we implementeerde.

Schakel het Drupal theme in

Ga in het Drupal 8 backend naar ‘Appearence’ en klik op ‘install and set as default’ bij het nieuwe custom theme.

Theme initiatie done

We hebben het Drupal 8 theme nu geïnitieerd, maar er is slechts een ‘kale’ pagina zichtbaar momenteel. In vervolg blogs ga ik deze aankleden door het plaatsen van de HTML via blocks.

Comments

Nóg meer
kennis nodig?

Check ons ons blog archief >