Drupal 8 -moduulin julkaisu

Drupal 8 -sivustoja laajennetaan erilaisilla moduuleilla. Moduuleita rakennetaan usein kertakäyttöisinä räätälöinteinä yksittäisen sivuston tarpeisiin, mutta joskus tarve on yleispätevä, eikä valmista työkalua tarpeeseen löydy. Tällöin paras ratkaisu on moduulin rakentaminen ja julkaisu drupal.org-sivustolla avoimen lähdekoodin hengessä. Tässä artikkelissa käymme tutoriaalinomaisesti läpi Drupal 8 -moduulin rakennuksen ja julkaisuprosessin.

Asiakkaamme halusi ja tarvitsi sivustolleen sivun oikeassa reunassa leijuvan valikon yhteystiedoille ja vastaaville pikalinkeille. Drupal 8:sta ei valmista moduulia tähän löytynyt, joten oli hyvä hetki ratkaista puute. Moduulin rakentaminen aloitetaan luomalla Drupal 8 -asennuksen juuresta löytyvään modules-kansioon alikansio moduulin nimellä. Drupal osaa hakea moduuleita kansiosta rekursiivisesti, ja yleisesti suositeltu tapa onkin jakaa yhteisön valmiit moduulit contrib-kansioon ja sivustolle räätälöidyt moduulit custom-kansion alle. Tässä tapauksessa siis on tavoitteena siirtää moduuli contrib-kansioon drupal.org-sivustolla julkaisun jälkeen, mutta tässä vaiheessa luodaan kansio polkuun modules/custom/floating_menu. Tällöin moduulin konenimeksi tulee floating_menu, jota tullaan käyttämään useammassa paikassa.

Ensimmäiseksi moduulin kansioon luodaan tekstitiedosto nimellä floating_menu.info.yml, johon tulee moduulin perustiedot yml-formaatissa. Floating Menu -moduulin tapauksessa tiedosto näyttää tältä:

name: 'Floating Menu'
description: 'Show a floating menu on your site.'
package: 'Site Navigation'
type: module
core: 8.x
dependencies:
  - drupal:block

Moduulin info-tiedosto on teoriassa ainoa pakollinen tiedosto, joten moduulin voisi jo tässä vaiheessa asentaa. Toki mitään toiminnallisuutta moduulissa ei vielä ole, joten jatketaan vielä.

Haluamme tulostaa sivulle valikon Drupalin lohkona. Luomme polkuun modules/custom/floating_menu/src/Plugin/Block tiedoston FloatingMenuBlock.php, joka sisältää lohkon ja sen asetukset käsittelevän luokan FloatingMenuBlock. Funktio build() palauttaa renderöintitaulukon, jossa määritetään lohkon käyttävän teemaa floating_menu_block ja kirjastoa floating_menu/floating-menu, sekä asetuksiin syötetyt muuttujat. Kirjasto määritetään moduulin juurikansioon sijoitettavassa floating_menu.libraries.yml-tiedostossa ja teema niinikään juurikansion floating_menu.module-tiedoston floating_menu_theme-funktiossa. Kirjastossa määritetään, että lohko käyttää Javascript- ja CSS-tiedostoja, jotka löytyvät omista /js ja /css -kansioistaan. Teemassa puolestaan määritetään käytössä olevat muuttujat, ja samalla nimellä luotu templaatti templates/floating-menu-block.html.twig sitten määrittää millaisen HTML-koodin lohko lopulta puskee ulos:

{% for menu_item in menu_items %}
  <div class="popup-item">
    <div class="item-text">
      <div class="menu-item-popup">{{ menu_item.popup_html }}</div>
    </div>
    <a href="{{ menu_item.url }}" class="item-icon">
      <img src="{{ menu_item.icon_url }}"></img>
    </a>
  </div>
{% endfor %}

Nyt alkaakin olla tarvittavat palikat kohdillaan ja moduulin perusrunko kunnossa. Moduuli asennetaan tavalliseen tapaan joko Drupalin käyttöliittymän Laajenna-toiminnallisuuden kautta, tai Drupalin komentorivityökalulla ajamalla drush en floating_menu -y. Tämän jälkeen suuntaamme Drupalin käyttöliittymässä Rakenne => Lohkojen sijoittelu ja sijoitamme lohkon jollekin alueelle kuten tavallisesti. Syötämme haluamamme valikkolinkkien tiedot lohkon asetuksiin, jotka on määritelty FloatingMenuBlock-luokan funktioissa blockForm ja blockSubmit.

Tämän jälkeen moduulia toki testataan mahdollisten ongelmien varalta ja normaalien ohjelmistokehityksen periaatteiden mukaisesti kollegat tarkastavat lähdekoodin (katselmointi). Kun näistä on selvitty, voidaan siirtyä moduulin julkaisuun. Drupalin viralliselta drupal.org-sivustolta löytyy Drupalin moduulikirjasto, johon kuuluu tuhansia ja tuhansia erilaisia moduuleita ja teemoja, joilla sivustoja voi laajentaa. Mutta kuten artikkelin alussa mainittiin, ei tähän tarkoitukseen löytynyt valmista moduulia, joten julkaisu on perusteltua. Näin se avoimen lähdekoodin järjestelmä kehittyy ihan tavallisten kehittäijen näppäimistöistä!

Moduulin julkaisuun tarvitsee luonnollisesti ensimmäiseksi rekisteröityä drupal.org-sivustolle, jos tunnusta ei entuudestaan jo löydy. Sisäänkirjautuneena suunnistamme uuden sisällön luontisivulle, josta pääsemme täyttämään moduulin perustietoja.

Lopuksi tarvitsee vain siirtää moduulin koodi drupal.orgin versionhallintaan, ja muutkin käyttäjät voivat ottaa moduulin käyttöönsä. Tämä onnistuu luonnollisesti Gitillä varsin mukavasti. Pistetään Drupalin nimeämiskäytännön mukainen tägi paikoilleen ja pusketaan koodi julkiseksi. Lopulta voidaan luodusta tägistä luoda  moduulille julkaisuversio, joka muiden käyttäjien on sitten helppo ladata esimerkiksi Composerin avulla Drupal 8 -projektissa composer require drupal/floating_menu:^1.0-beta.