Grundstruktur eines Drupal-Moduls
Teil II des praktischen Leitfadens zur Erstellung einfacher Drupal 8-Module
Von .info zu Tests, nur die Grundlagen
Grundstruktur
loremipsum.info.yml
name: Lorem ipsum type: module description: 'Lorem ipsum Generator fĂŒr Drupal' package: Development core: 8.x configure: loremipsum.form
Info-Dateien sind jetzt im YML-Format formatiert, und es gibt einen Unterschied zwischen Modulen und Themes, der durch die Angabe des Typs klar wird. Die Angabe âconfigureâ verweist auf eine Route (mehr dazu spĂ€ter), sonst gibt es nichts weiter. TatsĂ€chlich ist dies die einzige Datei, die Sie fĂŒr Ihr Modul benötigen. Nach dem Speichern dieser Datei (im Ordner root/modules) können Sie Ihr Modul unter /admin/modules aktivieren, ohne Ihre Seite zu beschĂ€digen. Aber wie Sie weiter sehen werden, ist das nicht genug.
loremipsum.module
<?php
use Drupal\Core\Routing\RouteMatchInterface;
/**
* Implementiert hook_help().
*/
function loremipsum_help($route_name, RouteMatchInterface $route_match) {
switch ($route_name) {
case 'help.page.loremipsum':
return t('
<h2>Lorem ipsum Generator fĂŒr Drupal.</h2>
<h3>Anleitung</h3>
<p>Lorem ipsum dolor sit amet... <strong>Nur ein Scherz!</strong></p>
<p>Entpacken Sie es in den <em>modules</em>-Ordner (aktuell im Root Ihrer Drupal 8-Installation) und aktivieren Sie es unter <strong>/admin/modules</strong>.</p>
<p>Dann besuchen Sie <strong>/admin/config/development/loremipsum</strong> und geben Sie Ihre eigenen Phrasen ein, um zufÀllig generierten Text zu erstellen (oder verwenden Sie das Standard-Lorem ipsum).</p>
<p>Zum Schluss besuchen Sie <strong>www.example.com/loremipsum/generate/P/S</strong> wobei:</p>
<ul>
<li><em>P</em> ist die Anzahl der <em>AbsÀtze</em></li>
<li><em>S</em> ist die maximale Anzahl der <em>SĂ€tze</em></li>
</ul>
<p>Es gibt auch einen Generator-Block, in dem Sie wÀhlen können, wie viele AbsÀtze und SÀtze erzeugt werden sollen, und er erledigt den Rest.</p>
<p>Falls benötigt, gibt es auch eine spezielle Berechtigung <em>generate lorem ipsum</em>.</p>
<h3>Achtung</h3>
<p>Die meisten Fehler wurden behoben, Löcher gestopft und Funktionen ergÀnzt. Aber dieses Modul ist noch in Arbeit. Bitte melden Sie Fehler und VorschlÀge, okay?</p>
');
}
}
Es ist eine gute Praxis, hier zumindest den Aufruf von hook_help() zu platzieren. Beachten Sie auch die âuseâ-Anweisung, die auf die Klasse RouteMatchInterface verweist. Das liegt hauptsĂ€chlich daran, dass es kein hook_menu() mehr gibt.
... Und mit der Zeit werden Sie bemerken, dass die .module-Datei auch zur Speicherung von Themen-bezogenen Informationen verwendet wird. Also behalten Sie das im Kopf.
loremipsum.install
<?php
/**
* @file
* Installationsfunktionen fĂŒr das Lorem ipsum Modul.
*/
use Drupal\user\RoleInterface;
/**
* Implementiert hook_install().
*/
function loremipsum_install() {
user_role_change_permissions(RoleInterface::ANONYMOUS_ID, array(
'generate lorem ipsum' => TRUE,
));
}
Hier verwenden wir eine andere Klasse: RoleInterface. Im Wesentlichen sagt diese Datei Drupal: âSobald dieses Modul aktiviert ist, suche die Berechtigung 'generate lorem ipsum' und aktiviere sieâ.
Aber wo wird diese Berechtigung definiert?
loremipsum.permissions.yml
generate lorem ipsum: title: 'Generate Lorem ipsum'
Wie Sie sehen, ist das viel einfacher als der Aufruf von hook_permission(). Die vollstÀndige Syntax finden Sie in der PermissionHandler-Dokumentation.
loremipsum.routing.yml
loremipsum.generate:
path: '/loremipsum/generate/{paragraphs}/{phrases}'
defaults:
_controller: '\Drupal\loremipsum\Controller\LoremIpsumController::generate'
requirements:
_permission: 'generate lorem ipsum'
loremipsum.form:
path: '/admin/config/development/loremipsum'
defaults:
_form: '\Drupal\loremipsum\Form\LoremIpsumForm'
_title: 'Lorem ipsum Einstellungen'
requirements:
_permission: 'administer site configuration'
Die Routing-Datei ersetzt den Aufruf von hook_menu(). Jeder Eintrag (ohne EinrĂŒckung) definiert eine Route, mit nachfolgenden eingerĂŒckten Zeilen, die die Details angeben.
Die Route loremipsum.generate verweist auf eine Seite, die zwei Argumente in {} akzeptiert; sie verweist auf einen Controller (mehr dazu spÀter), im Gegensatz zu loremipsum.form, das auf ein Formular mit Titel verweist.
FĂŒr beide Routen sind Berechtigungen erforderlich, Sie können sie jedoch durch _access: 'TRUE' fĂŒr unbeschrĂ€nkten Zugriff ersetzen.
loremipsum.services.yml
Erlaubt die Deklaration eines eigenen Services.
loremipsum.links.menu.yml
loremipsum.form: title: 'Lorem Ipsum Einstellungen' description: 'Konfigurationseinstellungen fĂŒr das Lorem Ipsum Modul.' route_name: loremipsum.form parent: 'system.admin_config_development'
WĂ€hrend die Routing-Datei eine Seite unter /admin/config/development/loremipsum erzeugt, sind diese Definitionen nötig, um die Seite im Admin-MenĂŒ anzuzeigen.
loremipsum.links.task.yml
Definitionen zur Erstellung zusĂ€tzlicher lokaler Tasks (Tabs) fĂŒr eine bestimmte Route.
loremipsum.links.action.yml
Definitionen zur Erstellung zusĂ€tzlicher lokaler Aktionen (Buttons) fĂŒr eine bestimmte Route.
loremipsum.links.contextual.yml
Definitionen zur Erstellung zusĂ€tzlicher kontextbezogener Aktionen fĂŒr ein UI-Element.
loremipsum.libraries.yml
Wird verwendet, um AbhĂ€ngigkeiten fĂŒr CSS- und Javascript-Bibliotheken zu registrieren. Mehr dazu im entsprechenden Abschnitt.
README.md
Entpacken Sie in den Ordner *modules* (derzeit im Root Ihrer Drupal 8-Installation) und aktivieren Sie das Modul unter `/admin/modules`.
Gehen Sie dann zu `/admin/config/development/loremipsum` und geben Sie Ihre eigenen Phrasen ein, um zufÀllig generierten Text zu erzeugen (oder verwenden Sie das Standard-Lorem ipsum).
Besuchen Sie schlieĂlich `www.example.com/loremipsum/generate/P/S`, wobei:
- * P * die Anzahl der *AbsÀtze* ist
- * S * die maximale Anzahl der *SĂ€tze* ist
Es gibt auch einen Generator-Block, in dem Sie wÀhlen können, wie viele AbsÀtze und SÀtze erzeugt werden sollen, und der Rest wird automatisch erledigt.
Wenn Sie möchten, gibt es auch eine spezielle Berechtigung *generate lorem ipsum*.
Achtung
---------
Die meisten Fehler wurden behoben, Löcher gestopft, Funktionen hinzugefĂŒgt. Aber dieses Modul ist noch in Arbeit. Bitte melden Sie Fehler und VorschlĂ€ge, okay?
Ja, README-Dateien werden jetzt im Markdown-Format geschrieben. Ziemlich cool, wenn Sie mich fragen.
Nun wollen wir uns die Ordnerstruktur genauer ansehen, um die Details besser zu verstehen.
LICENSE.TXT
FĂŒgen Sie die Datei LICENSE.txt (oder Ă€hnliche) nicht hinzu. Das Verpackungsskript fĂŒgt diese automatisch hinzu.
/config/install/loremipsum.settings.yml
loremipsum:
page_title: 'Lorem ipsum'
source_text: "Lorem ipsum dolor sit amet, consitteur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua". In der Ansicht im Twist sagt es esse cillum dolore eu fugiat nulla pariatur. \nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
In dieser Datei werden die Standardwerte gespeichert, die den entsprechenden Feldern durch die folgende Datei zugewiesen werden:
loremipsum: page_title: 'Lorem ipsum' source_text: "Lorem ipsum dolor sit amet, consectetur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. \nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. \nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
In dieser Datei werden die Standardwerte gespeichert, die den entsprechenden Feldern durch die folgende Datei zugewiesen werden:
/config/schema/loremipsum.schema.yml
loremipsum.settings:
type: config_object
label: 'Lorem Ipsum Einstellungen'
mapping:
loremipsum:
type: mapping
mapping:
page_title:
type: text
label: 'Titel der Lorem Ipsum Generator-Seite:'
source_text:
type: text
label: 'Quelltext fĂŒr die Lorem Ipsum-Erzeugung:'
block.settings.loremipsum_block:
type: block_settings
label: 'Lorem ipsum Block'
mapping:
loremipsum_block_settings:
type: text
label: 'Einstellungen des Lorem ipsum Blocks'
Die Schema-Datei wird verwendet, auch wenn Sie keine eigene Tabelle fĂŒr Ihr Modul definieren â hier sehen Sie Standardwerte, die den Formularfeldern der Konfiguration zugewiesen werden.
WĂ€hrend der Entwicklung dieses Codes habe ich festgestellt, dass das âOut-of-the-boxâ-BefĂŒllen der Felder eine der schwierigsten Aufgaben war. Zum GlĂŒck gibt es dafĂŒr ein Modul: den Configuration Inspector fĂŒr Drupal 8, der Ihnen hilft, die Standardeinstellungen zu debuggen.
AuĂerdem ist die YML-Schema-Datei in vielerlei Hinsicht sehr nĂŒtzlich (mehr dazu).
/src/Controller/LoremIpsumController.php
<?php
namespace Drupal\loremipsum\Controller;
// Ănderung gemÀà https://www.drupal.org/node/2457593
// Siehe https://www.drupal.org/node/2549395 fĂŒr Informationen zu veralteten Methoden
// use Drupal\Component\Utility\SafeMarkup;
use Drupal\Component\Utility\Html;
// Benutze Html statt SafeMarkup
/**
* Controller-Routinen fĂŒr Lorem Ipsum Seiten.
*/
class LoremIpsumController {
/**
* Erzeugt Lorem Ipsum Text mit Parametern.
* Diese Callback-Methode ist der Route
* 'loremipsum/generate/{paragraphs}/{phrases}' zugeordnet.
*
* @param string $paragraphs
* Die Anzahl der zu generierenden AbsÀtze.
* @param string $phrases
* Die maximale Anzahl der SĂ€tze pro Absatz.
*/
public function generate($paragraphs, $phrases) {
Wir sind beim Kern dieses Moduls angekommen, einer Klasse mit einer einzigen Methode, die Platzhaltertext generiert. Wie Sie sehen, ist die Methode, die in der Klasse LoremIpsumController definiert ist, mit dem Eintrag in der YAML-Routing-Datei verknĂŒpft:
Im weiĂen Rahmen sehen Sie den Code der Datei loremipsum.routing.yml und den Hintergrund der Datei, mit der wir arbeiten.
Weiter gehtâs: Der nĂ€chste Codeabschnitt lĂ€dt die Moduleinstellungen und speichert sie zur spĂ€teren Verwendung:
// Standard-Einstellungen.
$config = \Drupal::config('loremipsum.settings');
// Seitentitel und Quelltext.
$page_title = $config->get('loremipsum.page_title');
$source_text = $config->get('loremipsum.source_text');
Die oben genannten Parameter (loremipsum.page_title und loremipsum.source_text) stammen aus der YAML-Einstellungsdatei:
Dann teilen wir die SĂ€tze aus $source_text in ein Array auf:
$repertory = explode(PHP_EOL, $source_text);
Und verwenden dieses Array, um TextabsÀtze zu generieren:
$element['#source_text'] = array();
// Erzeuge X AbsÀtze mit bis zu Y SÀtzen jeweils.
for ($i = 1; $i <= $paragraphs; $i++) {
$this_paragraph = '';
// âBis zu Y SĂ€tzeâ heiĂt nicht âvon 1 bis Yâ.
// Also gehen wir von der HÀlfte aufwÀrts.
$random_phrases = mt_rand(round($phrases / 2), $phrases);
// Wiederhole nicht den letzten Satz.
$last_number = 0;
$next_number = 0;
for ($j = 1; $j <= $random_phrases; $j++) {
do {
$next_number = floor(mt_rand(0, count($repertory) - 1));
} while ($next_number === $last_number && count($repertory) > 1);
$this_paragraph .= $repertory[$next_number] . ' ';
$last_number = $next_number;
}
//$element['#source_text'][] = SafeMarkup::checkPlain($this_paragraph);
$element['#source_text'][] = Html::escape($this_paragraph);
}
Beachten Sie, dass ['#source_text'] ein Render-Array ist, das an das Template ĂŒbergeben wird, und dass jeder Eintrag im Array mit Html::escape() aus SicherheitsgrĂŒnden behandelt wird.
Zum Schluss geben wir unserem Render-Array einen Titel, weisen eine Theme-Funktion zu und geben es zurĂŒck:
//$element['#title'] = SafeMarkup::checkPlain($page_title);
$element['#title'] = Html::escape($page_title);
// Theme-Funktion.
$element['#theme'] = 'loremipsum';
return $element;
}
}
Aber bevor wir diese Variablen an unser Template ĂŒbergeben, mĂŒssen wir sie schĂŒtzen.
Der nÀchste Schritt;
Theming Ihres Moduls.
Danach;
HinzufĂŒgen eines Einstellungsformulars.
Definition eines Blocks fĂŒr dieses Modul.
Schreiben von Tests fĂŒr dieses Modul.