Modul
Aus Contenido Wiki
Inhaltsverzeichnis |
Grundsätzliches
Ein Modul ist ein Programmbaustein von Contenido und besteht im Wesentlichen aus normalem PHP. Im Template kann man für jeden Container im Layout ein Modul bezeichnen, welches an dieser Stelle ausgeführt werden soll. Ein Modul kann, aber muss nicht notwendigerweise eine Ausgabe vornehmen.
Es gibt globale Variablen, die nicht überschrieben werden dürfen (siehe auch Systemvariablen):
- $username
- $cfg
- $sess
- ...
Aufbau
Ein Modul besteht unter anderem aus einem Input- und einem Outputbereich.
Der Inputbereich (Eingabe) wird für die Konfiguration eines Modules im Backend benötigt und auch nur dort ausgeführt. Die Konfiguration eines Modules erfolgt entweder über Content -> Artikel -> Konfiguration order über Content -> Kategorie -> Kategorie Bearbeitet (blauer Stift!) -> Kategorie Konfigurieren. Man muss dafür nur ein Template auswählen welches ein solches Modul benutzt. Style -> Templates -> Vorkonfiguration bietet auch eine Möglichkeit der Konfiguration eines Modules.
Der Outputbereich (Ausgabe) wird ausgeführt wenn im Frontend der Artikel angefordert wird.
Input
Im Input-Bereich stehen folgende zwei Platzhalter zur Verfügung:
- CMS_VAR[0]: dieser Platzhalter wird bei der Ausführung durch den Namen der Variablen ersetzt werden.
- CMS_VALUE[0]: dieser Platzhalter wird im Rahmen der Ausführung durch den Wert ersetzt werden.
Die Indizes (im vorliegenden Fall die 0) können durch einen beliebigen Integer-Wert ersetzt werden. Wichtig ist jedoch, dass die Inidzes korrespondieren. Zu jedem CMS_VAR[n] (Feldname) gehört ein CMS_VALUE[n] (Feldwert).
Im einfachsten Fall haben wir dann einen Input-Bereich, der wie folgt aussieht:
?> <input type="text" name="CMS_VAR[0]" value="CMS_VALUE[0]" /> <?php
Die Umkehrung der PHP-Eingangs- und Ausgangstags ist nicht etwa ein Fehler. Im Inputbereich geht Contenido davon aus, ausschliesslich PHP-Code vorzufinden. Escaped man aus dem PHP-Bereich, kann anschliessend auch normales HTML verwendet werden. Folgender Input-Bereich wird die gleiche Funktion aufweisen:
echo '<input type="text" name="CMS_VAR[0]" value="CMS_VALUE[0]" />';
Output
Beim Outputbereich geht Contenido davon aus, dass einfaches HTML ausgegeben wird. Die PHP-Eingangs- und -Ausgangstags müssen selber gesetzt werden, sollten diese erforderlich sein. Soll in unserem Beispiel nur der in der Konfiguration bezeichnete Text ausgegeben werden, reicht dafür im Output folgender Code bereits aus:
CMS_VALUE[0]
Die Verwendung von PHP bleibt dem Anwender natürlich unbenommen. Die Werte der Konfiguration können beliebig im Modul verwendet werden. Z.B. in der Ausgabe mit einem echo oder durch Zuweisung zu einer Variablen, wie im folgenden Beispiel aufgezeigt:
Einfach:
<?php // direkte Ausgabe echo "CMS_VALUE[0]"; ?>
Aufwendig:
// Zuweisung - zu einer Variable
$myVar = "CMS_VALUE[0]";
// Verarbeitung - der Variable
if( empty($myVar) )
$myVar = "- leer -";
// Ausgabe - der Variable
echo $myVar;
?>
Komplex:
$myVar = array();
// Zuweisung - zu einem Array
for( $i=0; $i<=10; $i++ ) {
$myVar[] = "CMS_VALUE[$i]";
}
// Verarbeitung - des Arrays
$myVar = implode(", ", $myVar);
// Ausgabe - der Variablen (0-10)
echo $myVar;
?>
Die Notation mit Anführungszeichen ist deshalb erforderlich, da Contenido zunächst den Modulcode nach Auftreten von CMS_VALUE[n] untersucht und die betroffenen Stellen direkt durch den Wert des entsprechenden Platzhalters ersetzt. Fehlen die Anführungszeichen, wird dies zu einem Laufzeitfehler von Contenido führen.
Ist n kein numerischer Wert so wird CMS_VALUE[n] nicht durch den Wert ersetzt sondern durch einen Variablen-Namen. So wird im komplexen Beispiel "CMS_VALUE[$i]" z.B. zu "$C1_CMS_VALUE[$i]". C1 steht für Container und die ID des Containers in dem sich das Modul befindet (s. Layout). Die Variablen werden von Contenido vor dem Modul im Code ergänzt.
Für den Modul-Output stehen noch sogenannte CMS_TYP's zur Verfügung. Diese Typen ermöglichen es auf bestimmte Editoren die von Contenido bereitgestellt werden zuzugreifen.
Tipps
- Übergeben Sie ihre Konfiguration immer in lokalen Variablen:
z.B. $foo = "CMS_VALUE[1]";
Dieser Vorgang erleichtert die Verarbeitung der Werte und auch das spätere Erweitern des Moduls. - Benutzen Sie immer Anführungszeichen ("CMS_VALUE[1]") für die Platzhalter.
- Behandeln Sie CMS_VALUE wie Text, nicht wie eine Variable die geändert werden können.
- Benutzen Sie CMS_VAR wie einen Variablen-Name, aber nicht wie eine Variable selbst.
Modul-Beschreibung
In der Beschreibung des Modul solten foldende Angaben gemacht werden:
Beispiel-Beschreibung:
Version: 2.0 Modulname: <Modulname> Author(s): <Autorname> Copyright: <Firmenname> Created: 12-12-2000 Modified: 12-12-2000, <Autorname>, <Firmenname>
Modul-Historie
Die Modul-Historie erlaubt es, Änderungen an einem Modul zu verfolgen. Dies ist insbesondere hilfreich, wenn Änderungen an einem Modul gemacht wurden und das Modul dadurch nicht mehr funktionsfähig ist. Wählen Sie in der Auswahlbox die gewünschte Änderungszeit aus und klicken Sie auf "OK". Danach wird der Zustand des Moduls zum gewählten Zeitpunkt angezeigt.
Modul-Übersetzung
In mehrsprachigen Auftritten kann es erforderlich sein, Texte, die vom Modul ausgegeben werden, in die Ausgabesprachen zu übersetzen. Contenido bringt mit Bordmitteln einen Übersetzungsmechanismus mit. Die Funktion mi18n erwartet einen Parameter vom Typ Text. Es kann sich dabei sowohl um den Text handeln, der in der Hauptsprache ausgegeben werden soll oder um eine Zeichenfolge, die als Platzhalter dient.
<?php
$myText = mi18n("mein zu übersetzender Text");
?>
Findet Contenido im Modulcode diesen Funktionsaufruf, wird der übertragene Parameter isoliert und im Tab Übersetzung von Contenido zur Übersetzung in die aktuell gewählte Sprache vorgeschlagen.
Auch hier gilt die Einschränkung, dass Contenido ausschliesslich im Modulcode nach dieser Funktion sucht. In includierten Klassen wird die Funktion zwar ausgeführt, aber die Übersetzung mit Contenido ist nicht möglich. Soll eine includierte Klasse übersetzten Text verwenden, bestehen zwei Möglichkeiten:
- Die Texte werden bei der Klasseninstanzierung in den Konstruktor übertragen oder
- die Texte werden in der Klasse mit dem Funktionsaufruf ausgegeben. Für die Übersetzung werden sie im Modulcode lediglich aufgeführt.
Weitere Details zur Modul-Übersetzung.
Modul-Package (Import/Export)
Diese Funktion ist ab Contenido 4.6.18 verfügbar.
Bei einem Modul-Package handelt es sich um ein Packet aus den standart Eigenschaften des Moduls (Name, Typ, Beschreibung, Eingabe, Ausgabe). Desweiteren können Übersetzungen aller eingepflegten Sprachen, Javascript-Dateien, Template-Dateien, Style-Dateien, Layouts und GUID ergänzt werden.
Nach der Auswahl eines Modules kann man auf Package klicken, die gewünschten/benötigten Dateien auswählen und speichern. So werden alle ausgewählten Dateien bei einem Package-Export in das Package übertragen.
Package-Inhalt:
- Name
- GUID
- Beschreibung
- Modul-Input
- Modul-Output
- Javascript-Dateien (*.js)
- Modul-Template-Dateien (*.html)
- Style-Dateien (*.css)
- Layouts
- Übersetzungen
Anwendungsbeispiele:
- Ein Package kann man z.B. aus einem Testsystem exportieren und auf dem Livesystem importieren.
Hilfestellung für Programmierer
Variablen für In- & Output
Input
Variablen $cnumber = aktuelle Container-ID
Output
CMS_VALUE
Alle CMS_VALUE-Werte werden auch in einem Array bereitgestellt.
$C2CMS_VALUE[]
Hier ein Beispiel für Container 2.
Dynamisch kann man mit folgendem Code auf die Container eigenen Variablen zugreifen:
${ "C" . $cCurrentContainer . "CMS_VALUE" }[ ''n'' ]
- Variablen
$cCurrentModule = aktuelle Modul-ID
$cCurrentContainer = aktuelle Container-ID
Generierung von URLs
In Contenido werden interne URLs mit der Classe "Contenido_Url" generiert. An die Methode "buildRedirect" wird ein Array übergeben das alle wichtigen Parameter enthält.
Beispiel:
$aParams = array ( 'client' => $client, 'idcat' => $idcat, 'idart' => $idart, 'lang' => $lang, 'myParameter'=> '1' ); $url = Contenido_Url::getInstance()->buildRedirect($aParams);
Includierung von Klassen oder sonstigem PHP-Code
Für die Includierung von Klassen oder von sonstigem PHP-Code hat Contenido die Funktion cInclude vorgesehen. Diese Funktion ist die Standardfunktion jedoch ein Alias von contenido_include()
Diese Funktion erwartet min. zwei von drei Parametern:
cInclude( $where ,$what [,$force] )
- Bereich/Verzeichnis: Es handelt sich hierbei um ein kürzel für verschiedene Verzeichnisse.
- frontend = Das aktuelle Mandanten-Verzeichnis unter /cms/
- classes = Das Klassenverzeichnis von Contenido unter /contenido/classes/
- includes = Das Includesverzeichnis von Contenido unter /contenido/includes/
- X = Es können auch die aus '$cfg['path']' verwendet werden. Aufbauschema: $cfg['path']['contenido'].$cfg['path'][ X ]
- Dateipfad: Die relative Pfadangabe zur Datei, die includiert werden soll (relative Angabe zum gewählten Verzeichnis).
- Force: ist ein boolean-Wert (true/false) der wenn er auf true gesetzt wird das System zwingt das File zu includen
- true = include();
- false = include_once();
Bitte beachte, dass sowohl die Modulübersetzung als auch die Ersetzung von Konfigurationsplatzhaltern nur im Modulcode erfolgt. Includierter Code wird normal ausgeführt, ohne zuvor von Contenido untersucht und ggf. ersetzt worden zu sein.
Ausgabe von Header aus Modulen
In der Standardimplementierung führt Contenido keine Ausgabenpufferung aus. Der Versuch, aus einem Modul einen Header zu senden, wird deshalb immer fehlschlagen. Ist ein solches Verhalten gefragt, muss die Datei front_content.php im Mandantenverzeichnis (typischerweise /cms) um die Ausgabepufferung ergänzt werden.
<?php ob_start(); // dann folgt PHP-Code von Contenido // ziemlich am Ende der Datei findet sich dann folgende Zeile: page_close(); // unmittelbar danach kann die Ausgabenpufferung wieder ausgeschaltet werden ob_end_flush(); // dann folgt nochmal PHP-Code von Contenido ?>
Ist die Ausgabepufferung ausgeschaltet, kann das Modul wahlweise bereits gepufferten Code speichern (ob_get_contents), die Pufferung ausschalten (ob_end_clean oder ob_end_flush) und anschliessend einen Header senden. Je nach gewünschtem Verhalten kann das Modul dann den bisher gepufferte Inhalt wieder ausgeben. Wenn ausschliesslich headers zu senden sind (z.B. Relocation-Header), dann braucht die Ausgabepufferung nicht unterbrochen zu werden. In einem solchen Fall empfiehlt es sich allerdings, die Ausführung der ganzen Ausgabe mit exit() zu unterbinden.
Dynamisches erzeugen von Contenido-Platzhaltern
Wer bei der erstellung von Modulen Contenido-Platzhalter (wie z.B. CMS_IMG[1]) dynamisch erzeugen möchte, um das Modul dynamisch änderbar zu halten, wird schnell merken, dass es nicht möglich ist den Zahlenwert für den Platzhalter via PHP zu übergeben (z.B. CMS_IMG[$i]).
Dies resultiert daraus, dass der Programmcode der Module erst geparst wird, sobald die Platzhalter ersetzt sind. Die Platzhalter haben jedoch keine gültigen Werte, da PHP (und somit $i) noch nicht ausgeführt wurden.
Die Lösung des Problems wurde im Forum gepostet. Mit Hilfe einer Funktion muss der jeweilige Platzhalter während der Laufzeit des Scripts erstellt werden.
Hier die entsprechende Funktion:
<?php
/**
* make_cms_type()
*
* Erstellung von CMS_TYPEs mit dynamischer Type-ID
*
* @param string $sCmsType Type-Name (Example: "CMS_IMG")
* @param int $iCmsTypeId Type-Id
* @return string HTML-String for edit or display CMS-Type
*
* @link Contenido-Forum <http://forum.contenido.org/viewtopic.php?f=62&t=23603>
* @link Contenido-Wiki <http://www.contenido-wiki.org/wiki/index.php?title=Modul#Verwandte_Themen>
*/
function make_cms_type( $sCmsType, $iCmsTypeId ) {
global $a_content, $idartlang, $idart, $idcat, $lang, $db, $edit, $sess, $client, $cfg, $cfgClient;
$sql = "SELECT * FROM ".$cfg["tab"]["type"]." WHERE type = '$sCmsType'";
$db->query($sql);
$db->next_record();
$sCmsTypeCode = $db->f("code");
$iCmsIdType = $db->f("idtype");
if( !$edit ) {
$db2 = new DB_Contenido;
$sql = "SELECT * FROM ".$cfg["tab"]["content"]." AS A, ".$cfg["tab"]["art_lang"]." AS B, ".$cfg["tab"]["type"]." AS C
WHERE A.idtype = C.idtype
AND A.idartlang = B.idartlang
AND B.idart = '".Contenido_Security::toInteger($idart)."'
AND B.idlang = '".Contenido_Security::escapeDB($lang, $db)."'
AND A.idtype = '".$iCmsIdType."'
AND A.typeid = '".$iCmsTypeId."'";
$db2->query($sql);
$db2->next_record();
$a_content[$db2->f("type")][$db2->f("typeid")] = $db2->f("value");
}
$val = $iCmsTypeId;
eval($sCmsTypeCode);
$tmp_output = str_replace('\\\"','"',$tmp);
$tmp_output = stripslashes($tmp_output);
return $tmp_output;
}
// Aufruf der Funktion
echo make_cms_type("CMS_HTML","1");
?>
