Tworzenie własnych modułów w Drupalu – krótki przewodnik

Pierwszym krokiem do stworzenia modułu jest wybór nazwy. Moduły niestandardowe można utworzyć na dwa sposoby:

• ręcznie, tworząc pliki odpowiedzialne za definicję modułu,
• za pomocą narzędzia Drush, służącego do zarządzania projektem Drupal z poziomu wiersza poleceń.

Przyjrzyjmy się wymogom dotyczącym nazewnictwa modułów w Drupalu. Krótka nazwa (inaczej nazwa maszynowa), musi:

• zaczynać się od litery,
• zawierać tylko małe litery, cyfry i znaki podkreślenia „_”,
• być unikalna,
• zawierać mniej niż 50 znaków.

Poza tym nie powinna zawierać spacji i być żadnym z zarezerwowanych terminów dla klasycznych drupalowych katalogów jak src, assets, templates itd.

W krótkiej nazwie nie należy korzystać z nazw istniejących modułów, nawet jeśli ich nie używasz, np. Views. Drupal może wtedy źle interpretować instalowane moduły.

Przyjmijmy, że w ramach nauki, nazwiemy nasz moduł „awesome_chat”. Aby zrobić to ręcznie, należy utworzyć katalog w ścieżce web/modules/custom:

W przypadku korzystania z narzędzia Drush możesz wykorzystać polecenie „./vendor/bin/drush gen module”, a następnie podać wszystkie wymagane informacje:

W tym przypadku podaliśmy:

• nazwę modułu – pojawia się w panelu administracyjnym,
• nazwę maszynową – jest równoznaczna z nazwą katalogu,
• opis modułu – wyświetla się w panelu administracyjnym,
• grupę paczek – w jakiej sekcji paczek/modułów w panelu administracyjnym ma się znaleźć Twój moduł - tutaj stworzyliśmy własną grupę „Awesome Package”,
• zależności – jeżeli korzystasz z innych modułów (niezależnie czy to core, contrib czy custom), powinieneś je tutaj zawrzeć,
• odpowiedzi na pytania, czy stworzyć konkretne pliki dotyczące modułu. Każda odpowiedź to „nie”, ponieważ na tym etapie ich nie potrzebujesz.

Aby zainstalować niestandardowy moduł w Drupal CMS, musi być on widoczny dla systemu. Jak możesz zauważyć, podczas generowania modułu za pomocą Drusha, został utworzony plik „awesome_chat.info.yml”. Dzięki niemu moduł jest widoczny, a jednocześnie definiuje jego niektóre właściwości. Zobacz, co się w nim pojawiło:

Do wartości name, description i package omówionych wcześniej, dołączyły dwie dodatkowe:

• type – definiuje typ dostarczanej funkcji. W naszym przypadku jest to „module”, ale gdyby była to customowa skórka do Drupala, wartość nazywałaby się „theme”,
• core_version_requirement – określa wersję Drupala, dla której moduł będzie dostępny. Zapis “^10”, wskazuje, że niestandardowy moduł Drupal CMS można zainstalować dla wersji 10 i wcześniejszych. Gdyby moduł był dostępny dla wersji 10 oraz 11 (pojawi się w 2024 r.), zapisałbyś go „^10 || ^11”.

W pliku możesz zdefiniować jeszcze precyzyjniejsze wartości, takie jak wersja PHP, cykl życia, testowe zależności oraz główny formularz konfiguracyjny. Więcej informacji znajdziesz na oficjalnej stronie Drupala.

Zakończyliśmy tworzenie modułu. Tyle wystarczy, aby stworzyć moduł dla Drupala. Jesteśmy jednak na początku drogi. Rozwój modułu wymaga jeszcze trochę pracy. Sprawdź, co możesz wykorzystać, aby napisać własną funkcję.

W module możesz stworzyć pliki wprowadzające funkcje do istniejących rozwiązań w Drupalu:

• awesome_chat.permissions.yml (*.permissions.yml) – możesz w nim określać uprawnienia do konkretnych operacji, które zawrzesz w kodzie modułu. Kluczami są nazwy uprawnień, natomiast tytuły są wyświetlane w panelu administracyjnym;

• awesome_chat.module (*.module) – jest odpowiedzialny za wykorzystywanie hooków, służących do podpinania się do innych funkcji. Możesz w nim znaleźć definicje szablonów oraz funkcje pomocnicze;
• awesome_chat.links.menu.yml (*.links.menu.yml) - za pomocą tego pliku jesteś w stanie dodać nową zakładkę do menu administracyjnego. Można to zrobić na kilka sposobów. Poniżej plik utworzony za pomocą Drusha:

• awesome_chat.install (*.install) – możesz tu zdefiniować hook odpowiedzialny za wymogi modułu (hook_requirements()) oraz hooki wykonujące aktualizacje lub operacje na bazie danych;
• awesome_chat.api.php (*.api.php) – definiujesz tutaj własne hooki, dzięki którym umożliwiasz wpięcie się w pisane nowe niestandardowe funkcje w Drupalu.

Aby stworzyć controller w module, możesz skorzystać z narzędzia Drush i wykonać polecenie „./vendor/bin/drush gen controller”. Po uzupełnieniu informacji w wierszu poleceń dotyczących nazwy controllera oraz danych ścieżki, otrzymasz dwa pliki:

• web/modules/custom/awesome_chat/awesome_chat.routing.yml

awesome_chat.first_route:
  path: '/awesome-chat'
  defaults:
    _controller: '\Drupal\awesome_chat\Controller\AwesomeChatController::chat
    _title: 'Awesome chat!!!'
  requirements:
    _permission: 'access content'

W pliku *.routing.yml definiujesz ścieżki do kontrolerów oraz ustawiasz odpowiednie parametry. W powyższym kodzie ustaliłeś, że ścieżka „awesome_chat.first_route” wskazuje na konkretną metodę „chat” z kontrolera oraz zawiera tytuł podany w parametrze _title. Dostęp do niej mają wszystkie role, które posiadają uprawnienie „access content”. Szczegółowy opis funkcjonowania routingu możesz znaleźć na oficjalnej stronie Drupala.

• web/modules/custom/awesome_chat/src/Controller/AwesomeChatController.php

<?php

namespace Drupal\awesome_chat\Controller;

use Drupal\Core\Controller\ControllerBase;

class AwesomeChatController extends ControllerBase {

  public function chat() {
    return [
      '#markup' => $this->t('Hello from Awesome Chat!!'),
    ];
  }
}

Jak możesz zauważyć, wchodząc teraz pod adres /awesome-chat, otwiera się strona z wyświetlanym tekstem z metody „chat”: “Hello from Awesome Chat!!”.

Kiedy utworzyłeś moduł oraz zdefiniowałeś określone funkcje, możesz go zainstalować. Sam proces instalacji można przeprowadzić z poziomu panelu administracyjnego, wchodząc pod /admin/modules, wybierając standardowy moduł i zaznaczając proces instalacji lub poprzez polecenie „./vendor/bin/drush en awesome_chat”.