Module erstellen - ein Tutorial
Dieses Tutorial basiert auf Drupal 4.7, bitte in diesen Handbuchseiten schauen für Drupal 5/6.
Eine Übersetzung des Tutorials Creating modules - a tutorial von Christian Zwahlen
Eine weitere Anleitung zur Erstellung eines Moduls ist hier zu finden: http://www.preetzlug.de/tutor01
Die Übersetzung hält sich sehr nahe dem englischen Original (evt. etwas holprige Sätze). Verbesserungen, die auf der englischen Website als "Kommentare" angefügt wurden, sind speziell formatiert und hervorgehoben.
Letzte Aktualisierung: 5.11.2005
Dieser Tutorial beschreibt, wie man ein Modul für Drupal 4,5. herstellt *. Es ist ein Update zum Tutorial für Drupal Drupal 4.3 . Sehen Sie bitte auch die Anmerkungen dort.
Ein Modul ist eine Ansammlung von Funktionen, die in Drupal verbunden sind und stellt zusätzliche Funktionalitäten zu Ihrer Drupal Installation bereit. Nach dem Ablesen dieses Tutorial, sind Sie in der Lage, ein grundlegendes Blockmodul herzustellen und es als Vorlage für erweiterte Module und "node module" zu benutzen.
(...)Verwenden Sie diesen Tutorial als Ausgangspunkt, und wiederholen Sie andere Module und das Drupal handbook und Coding standards für mehr Information.
Dieser Tutorial nimmt das folgende über Sie an:
- Grundlegendes PHP-Wissen, einschließlich der Syntax und des Konzeptes der PHP-Gegenstände
- Grundlegendes Verständnis der Datenbanktabellen, der Felder, der Aufzeichnungen und der SQL-Aussagen
- Eine lauffähige Drupal Installation
- Administrations Zugang zu Drupal
- Zugang zu einem Webserver
Dieser Tutorial nimmt nicht an, daß Sie jedes mögliche Wissen über die inneren Funktionen eines Moduls Drupal haben. Dieser Tutorial hilft Ihnen nicht, Module für Versionen von Drupal 4,5 oder früher zu schreiben.
Beginnen wir
Um dieses Tutorial zu konkretisieren, wollen wir mit dem Erstellen eines Moduls beginnen, welches Links auflistet wie in einem Blogeintrag oder Forumsdiskussion, welches wir vor einer Woche kreierten. Das komplette Tutorial erklärt uns, wie man Blockinhalt erstellt, Verbindungen schreibt und Informationen von den Drupal "nodes" zurückholt.
Beginnen Sie Ihr Modul, indem Sie eine PHP Dokument erstellen und speichern Sie es als "onthisdate.module" im Modulverzeichnis Ihrer Drupal Installation.
<?php
?>
Wie aus den Coding standards, verwenden Sie die erweiterte Schreibweise <?php und nicht <? um ihren PHP-Code zu umschliessen.
Alle Funktionen in Ihrem Modul werden { modulename}_{hook } genannt, wo "hook" ein gut definierter Funktionsname ist. Drupal benennt diese Funktionen, um spezifische Daten zu erhalten, also sind diese gut definierten Namensmittel dazu da, Drupal wissen zu lassen, wo es danach schauen muss.
Drupal über die neue Funktion informieren
Wie oben erwähnt, ist die Funktion, die wir gerade schrieben, nicht ein "hook": es ist nicht ein Drupal anerkannter Name. Wir müssen Drupal erklären, wie man die Funktion zugänglich macht, wenn wir eine Seite anzeigen. Wir tun dies mit dem hook "menu()". Der hook menu() definiert die Verbindung zwischen einer URL und die Funktion, die den Inhalt für diese URL generiert. Der Hook prüft auch auch die Erlaubnis, wenn es gewünscht wird.
<?php
function onthisdate_menu() {
$items = array();
$items[] = array('path' => 'onthisdate',
'title' => t('on this date'),
'callback' => '_onthisdate_all',
'access' => user_access('access content'),
'type' => MENU_CALLBACK);
return $items;
}
?> Im Allgemeinen sagen wir, wenn der Benutzer "onthisdate" geht (entweder über?q=onthisdate oder http://.../onthisdate ), der Inhalt, der durch onthisdate_all erzeugt wurde, wird angezeigt. Der Titel der Seite ist "on this date".
Die Eingabe MENU_CALLBACK bei Drupal ist für ein Nichtanzeigen der Verbindung im Menü des Benutzers, verwenden sie diese Funktion gerade, wenn die URL erreichbar ist. Verwenden Sie MENU_LOCAL_TASK, wenn Sie den Benutzern die Verbindung im seitlichen Navigationsblock zeigen wollen.
Steuern Sie zu /onthisdate (oder ?q=onthisdate) und sehen Sie, was Sie erhalten.
Informieren Sie Drupal über ihr Modul
Die erste Funktion, die wir schreiben, wird Drupal Informationen über Ihr Modul nennen: sein Name und Beschreibung. Der "hook"-Name für diese Funktion ist "help", also Beginnen wir mit der onthisdate_help Funktion:
<?php
function onthisdate_help($section='') {
}
?> Die $$section Variable stellt den Kontext für die Hilfe zur Verfügung: wo in Drupal oder im Modul wir nach Hilfe suchen. Die empfohlene Weise, diese Variable zu verarbeiten ist mit einer "Switch"-Aussage. Sie werden dieses Codeschema auch in anderen Modulen sehen.
<?php
/**
* Display help and module information
* @param section which section of the site we're displaying help
* @return help text for section
*/
function onthisdate_help($section='') {
$output = '';
switch ($section) {
case "admin/modules#description":
$output = t("Displays links to nodes created on this date");
break;
}
return $output;
} // function onthisdate_help
?> Sie wünschen sich möglicherweise weitere Fälle zu dieser Switch Aussage hinzuzufügen, um dem Benutzer reale Hilfs-Meldungen zur Verfügung zu stellen. Insbesondere zeigt die Ausgabe für "admin/help#onthisdate" auf der Haupthilfenseite, die durch das admin/help URL für dieses Modul erreicht wird, (/admin/help oder?q=admin/help) an.
Sagen Sie Drupal wer Ihr Modul verwenden kann
Die nächste Funktion zum Schreiben ist die Erlaubnisfunktion. Die Erlaubnisfunktion bewilligt nicht Erlaubnis, es spezifiziert gerade welche Erlaubnis für dieses Modul vorhanden ist. Der Zugang, der auf dieser Erlaubnis basiert, ist weiter unten im {module}_access definiert. An dieser Stelle geben wir jedermann die Erlaubnis, der Zugang zum Site-Inhalt hat oder das Module administrieren kann.
<?php
/**
* Valid permissions for this module
* @return array An array of valid permissions for the onthisdate module
*/
function onthisdate_perm() {
return array('access content');
} // function onthisdate_perm()
?> Andererseits, wenn Sie ein Modul schreiben werden, das eine feinere Steuerung zur Erlaubnis haben muss, und Sie gehen zur Zugriffssteuerung, sollten Sie diese eingestellten Rechte erweitern. Sie können dies tun indem Sie Strings zu den Arrays hinzufügen, welche zurückgebracht wird. Zum Beispiel:
<?php
function onthisdate_perm() {
return array('access content', 'access onthisdate', 'administer onthisdate');
} // function onthisdate_perm
?> Für dieses Tutorial beginnen Sie mit dem Ersten. Wir werden später auf die zweite Version eingehen.
Sie werden dann die Einstellung vornemen müssen, wer Zugriff zur Ansicht ihres Modules auf der Administrations "accounts" Zugriffs-Seite hat. Wir werden die user_access Funktion verwenden, um die Berechtigung später zu überprüfen (whoa, so viele "später!")
Ihre Erlaubnis-Strings müssen innerhalb Ihres Moduls einmalig sein. Wenn sie es nicht sind, verzeichnet die Zugriffsseite die gleichen Berechtigungen auf eine längere Dauer. Sie sollten auch Ihren Modulnamen enthalten, um Namenskonflikte mit anderen Modulen zu vermeiden.
Stellen Sie ihren Blockinhalt dar
Es gibt einige Arten Module: Block-Module und Node-Module sind zwei. Blockmodule verursachen abgekürzten Inhalt, der gewöhnlich (aber nicht immer und sind nicht erforderlich nur so zu sein) entlang der linken oder rechten Seite einer Seite angezeigt wird. Node-Module erzeugen vollen Seiteninhalt (wie Blogs, Foren oder Buchseiten).
Zum Beginn werden wir einen Blockinhalt kreieren und besprechen später Node-Inhalt. Ein Modul kann Inhalt für Blöcke und auch für eine volle Seite erzeugen (das Blog module ist ein gutes Beispiel dafür). Der Hook für ein Blockmodul wird passend "block" genannt, also lassen Sie uns unsere folgende Funktion beginnen:
<?php
/**
* Generate HTML for the onthisdate block
* @param op the operation from the URL
* @param delta offset
* @returns block HTML
*/
function onthisdate_block($op='list', $delta=0) {
} // end function onthisdate_block
?> Die Blockfunktion nimmt zwei Parameter: die Operation und der Versatz (offset) oder Dreieck (delta). Wir sorgen uns gerade an diesem Punkt um die Operation. Insbesondere interessieren wir uns für den spezifischen Fall, in dem der Block in der Blockseite aufgelistet wird. In allen weiteren Situationen zeigen wir den Blockinhalt an.
Wenn das Modul auf der Blockseite angezeigt wird, entspricht $op dem Parameterinhalt "list":
<?php
/**
* Generate HTML for the onthisdate block
* @param op the operation from the URL
* @param delta offset
* @returns block HTML
*/
function onthisdate_block($op='list', $delta=0) {
// listing of blocks, such as on the admin/block page
if ($op == "list") {
$block[0]["info"] = t('On This Date');
return $block;
} else {
// our block content
}
} // end onthisdate_block
?> Erzeugen Sie Inhalt für einen Block
Jetzt müssen wir den "onthisdate"-Inhalt für den Block erzeugen. Hier demonstrieren wir eine grundlegende Weise, um auf die Datenbank zuzugreiffen.
Unser Ziel ist es, eine Liste des Inhalts zu erhalten (gespeichert als "nodes" in der Datenbank, die vor einer Woche erstellt wurde).
Speziell wünschen wir den Inhalt, der zwischen Mitternacht und 11:59pm am Tag vor einer Woche erstellt wurde. Wenn ein "node" als erster kreiert wird, wird die Zeit der Erstellung in der Datenbank gespeichert. Wir werden dieses Datenbankfeld benutzen, um unsere Daten zu finden.
Zuerst müssen wir die Zeit errechnen (in den Sekunden, da "epoch start", siehe http://www.php.net/manual/en/function.time.php für mehr Information über "Zeitformat"), für Mitternacht seit einer Woche und 11:59pm seit einer Woche. Dieses Teil des Codes ist Drupal unabhänig, sehen Sie dazu die PHP-website (http://php.net/) für mehr Details.
<?php
/**
* Generate HTML for the onthisdate block
* @param op the operation from the URL
* @param delta offset
* @returns block HTML
*/
function onthisdate_block($op='list', $delta=0) {
// listing of blocks, such as on the admin/block page
if ($op == "list") {
$block[0]["info"] = t('On This Date');
return $block;
} else {
// our block content
// Get today's date
$today = getdate();
// calculate midnight one week ago
$start_time = mktime(0, 0, 0,
$today['mon'], ($today['mday'] - 7), $today['year']);
// we want items that occur only on the day in question, so
// calculate 1 day
$end_time = $start_time + 86400;
// 60 * 60 * 24 = 86400 seconds in a day
...
}
}
?> Der folgende Schritt ist die SQL-Aussage, die den Inhalt zurückholt und wir von der Datenbank anzeigen möchten. Wir wählen Inhalt von der Node-Tabelle vor, welche die zentrale Tabelle für Drupal Inhalt ist. Wir erhalten alle Arten von Inhaltstypen mit diesen Abfragen: blog entries, forum posts, usw. Für dieses Tutorial ist das okay. Für ein reales Modul würden Sie die SQL-Aussage anpassen, um spezifische Arten von Inhalten auszuwählen (durch das Addieren der 'type' Spalte und einer WHERE Klausel, welche die 'type' Spalte überprüft).
Anmerkung: der Tabellenname wird in den geschweiften Klammern umgeben: {node}. Dies ist notwendig, damit Ihr Modul Namens-Präfixe der Datenbanktabellen unterstützt. Sie finden auf der Drupal Website unter "Handbook" mehr Informationen über Table Prefix (and sharing tables across instances).
<?php
$query = "SELECT nid, title, created FROM " .
"{node} WHERE created >= '" . $start_time .
"' AND created <= '". $end_time . "'";
?> Drupal verwendet Datenbankhelferfunktionen, um Datenbankfragen durchzuführen. Dies heisst, dass Sie, in den meisten Fällen, ihre SQL Datenbank Anweisungen schreiben können, ohne sich über die Anbindungen der Datenbanken kümmern zu müssen.
Wir benutzen db_query(), um die Datensätze (d.h. die Datenbankreihen) welche Ihre SQL Abrfrage verwaltet und db_fetch_object() um die individuellen Datensätze zu sehen:
<?php
// get the links
$queryResult = db_query($query);
// content variable that will be returned for display
$block_content = '';
while ($links = db_fetch_object($queryResult)) {
$block_content .= '<a href="' . url('node/' . $links->nid) . '">' .
$links->title . '</a><br />';
}
// check to see if there was any content before setting up
// the block
if ($block_content == '') {
/* No content from a week ago. If we return nothing, the block
* doesn't show, which is what we want. */
return;
}
// set up the block
$block['subject'] = 'On This Date';
$block['content'] = $block_content;
return $block;
}
?> Beachten Sie, daß die tatsächliche URL in der l()funktion umgeben wird. l erzeugt <a href="link "> Links, Stimmen Sie die URL auf die URL-Konfiguration Ihrer Drupal Installation auf saubere URL´s ein. Entweder: http://(sitename)/node/2 oder http://(sitename)/?q=node/2
Auch wir bringen ein Array zurück, die 'subject' und 'content' Elemente beinhaltet. Dies ist, was Drupal von einer Blockfunktion erwartet. Wenn Sie die Beiden Arrays nicht einsetzen, wird der Block nicht richtig wiedergegeben.
Sie können auch die schlechte Kodierungpraxis des Kombinierens des Inhalts mit dem Layout beachten. Wenn Sie ein Modul für andere zur Anwendung schreiben, solten Sie für andere (insbesondere, Nicht-Programmierer) eine einfache Möglichkeit das Layout des Inhalts anpassen zu können zur Verfügung stellen. Eine einfache Art dies zu erreichen, ist eine a Klass-Attribut in Ihrem Link zu setzten oder umgeben Sie das HTML mit einem <div> Tag mit einem modul-spezifischen CSS-Klasse und das <div> Tag ist am Ende nicht nötig mit einzuschließen. Lassen Sie uns dieses jetzt ignorieren, aber berücksichtigen diesen Issue, wenn andere die geschriebenen Module verwenden wollen.
Fügen Sie alles zusammen. Unsere Blockfunktion sieht an dieser Stelle folgendermassen aus:
<?php
function onthisdate_block($op='list', $delta=0) {
// listing of blocks, such as on the admin/block page
if ($op == "list") {
$block[0]["info"] = t("On This Date");
return $block;
} else {
// our block content
// content variable that will be returned for display
$block_content = '';
// Get today's date
$today = getdate();
// calculate midnight one week ago
$start_time = mktime(0, 0, 0,$today['mon'],
($today['mday'] - 7), $today['year']);
// we want items that occur only on the day in question, so
//calculate 1 day
$end_time = $start_time + 86400;
// 60 * 60 * 24 = 86400 seconds in a day
$query = "SELECT nid, title, created FROM " .
"{node} WHERE created >= '" . $start_time .
"' AND created <= '". $end_time . "'";
// get the links
$queryResult = db_query($query);
while ($links = db_fetch_object($queryResult)) {
$block_content .= '<a href="'.url('node/'.$links->nid).'">'.
$links->title . '</a><br />';
}
// check to see if there was any content before setting up the block
if ($block_content == '') {
// no content from a week ago, return nothing.
return;
}
// set up the block
$block['subject'] = 'On This Date';
$block['content'] = $block_content;
return $block;
}
}
?> Das Modul installieren, aktivieren und testen
An diesem Punkt können Sie Ihr Modul installieren und es wird funktionieren. Lassen Sie uns dies tun und sehen, wo wir das Modul verbessern müssen.
Um das Modul zu installieren, müssen Sie Ihre Datei onthisdate.module in das Modulverzeichnis Ihrer Drupal Installation kopieren. Die Datei muss in dieses Verzeichnis oder in ein Unterverzeichnis des Modulverzeichnisses installiert werden, und muss ebenfalls die die Dateiendung ".module" aufweisen.
Melden Sie sich als Administrator ein und navigieren zur Seite der Moduladministration, um eine alphabetische Liste der Module zu erhalten. Im Menü unter: "administer » modules", oder über URL via:
http://.../admin/modules oder
http://.../?q=admin/modules
Wenn Sie nach unten blättern, sehen Sie das onthisdate Module, mit der gleich danebenstehenden Beschreibung.
Aktivieren Sie das Modul, indem Sie die Checkbox auswählen und speichern Ihre Konfiguration.
Weil das Modul ein Block-Modul ist, müssen wir es auch im Block-Administrationsmenü aktivieren und eine Position zur Ansicht definieren. Node-Module benötigen oder benötigen keine weiteren Konfigurationen, je nach Modul.
Jedes mögliche Modul kann Einstellungen haben, die das functionality/display eines Moduls beeinflussen. Wir besprechen die Einstellungen später. Fürs Erste navigieren Sie zur Administrationsseite der Blöcke: admin/block oder über die Menüs: "administer » blocks".
Aktivieren Sie das Modul, indem Sie die verfügbare Checkbox für den 'On This Date' Block auswählen und speichern Ihre Blöcke. Vergewissern Sie sich, die Position (links/rechts) anzugeben, wenn Sie ein Theme mit?Rahmen verwenden, wo Blöcke angezeigt werden.
Nun, den Kopf zu einer anderen Seite, sagen wir das Modulmenü. In einigen Themen werden die Blöcke angezeigt, nachdem die Seite den Inhalt generiert hat, und sehen die Änderung nicht, bis Sie zur neuen Seite gehen.
Wenn Sie Inhalt haben, welcher vor einer Woche kreiert wurde, zeigt der Block mit Links zum Inhalt an. Wenn Sie keinen Inhalt haben, müssen Sie etwas Daten fälschen. Sie können dies tun, indem Sie ein Blog, ein Forumthema oder eine Buchseite erstellen, und gleichen das "Authored on:" (Geschrieben am:) Datum auf eine Woche vorher an.
Abwechslungsweise, wenn Ihre Site ungefähr eine Weile gelaufen ist, können Sie eine Menge Inhalt haben, kreiert am Tag vor einer Woche, und Sie werden eine grosse Zahl von Links im Block sehen.
Soweit vorerst die ersten wichtigsten Seiten.
- Anmelden oder Registrieren um Kommentare zu schreiben
Neue Kommentare
vor 3 Tagen 8 Stunden
vor 3 Tagen 10 Stunden
vor 3 Tagen 10 Stunden
vor 3 Tagen 10 Stunden
vor 4 Tagen 8 Stunden
vor 4 Tagen 10 Stunden
vor 5 Tagen 6 Stunden
vor 6 Tagen 11 Minuten
vor 6 Tagen 1 Stunde
vor 6 Tagen 4 Stunden