BlackCat CMS Dokumentation, Tutorials, Tipps und Tricks

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== Droplets ======

Die Idee der Droplets stammt noch aus Website Baker. Hiermit wurde eine flexible Möglichkeit geschaffen, kleine Codeschnipsel an beliebigen Stellen unterzubringen - etwa Datum und Uhrzeit der letzten Änderung einer Seite irgendwo im Template, oder ein kleiner Kalender mitten im Fließtext (WYSIWYG-Modul) einer Seite.

===== Wo ist der Haken dabei? =====

Dieser Text wurde aus der [[https://addons.phpmanufaktur.de/de/name/dropletsextension/documentation.php#|Dokumentation des Moduls DropletsExtension]] übernommen:

Die Platzhalter für die Droplets werden unmittelbar vor der Anzeige einer Webseite herausgefiltert, der Code des Droplets ausgeführt und das Ergebnis des Mini-Programms an Stelle des Platzhalters auf der Seite eingefügt und die fertige Webseite danach im Browser angezeigt:

  * Nichts von dem, was ein Droplet berechnet, bei einer Datenbank abfragt und anzeigt wird von der WebsiteBaker oder LEPTON CMS Suchfunktion berücksichtigt - Droplets werden vollständig und sehr konsequent ignoriert.
  * Droplets haben keinen Einfluss auf den Seitentitel sowie auf die im Dateiheader enthaltene Kurzbeschreibung (description) und die aufgelisteten Schlüsselwörter (keywords), selbst dann nicht, wenn Sie den Inhalt einer Seite vollständig bestimmen.
  * Droplets können im Unterschied zu Seitenmodulen Cascading Stylesheets (CSS) nicht automatisch laden, der verantwortliche Webmaster muss den erforderlichen CSS Code von Hand im Stylesheet der Website einbinden.

<WRAP center round tip 100%>
Diese Einschränkungen gelten für BlackCat CMS **nicht**, denn wir haben die Grundlagen der DropletsExtension in den Core übernommen. Es ist also **nicht** notwendig, das Modul DropletsExtension in BlackCat CMS zu installieren!
</WRAP>

<WRAP center round important 100%>
**Wichtige Voraussetzung:** Da es hier um zusätzlich einzubindende Dateien geht, ist es natürlich notwendig, diese irgendwo zu hinterlegen. Daher erfordern diese Funktionalitäten, daß zum Droplet auch ein Modul gehört.
</WRAP>

===== Seitentitel, -beschreibung und -Schlüsselwörter ändern =====

BlackCat CMS bringt alle erforderlichen Funktionen im Droplet-Helper bereits mit. Da dieser auf dem DropletsExtension-Modul basiert, gelten viele der dortigen Grundlagen auch für unseren Helper.

Soll ein Droplet in der Lage sein, Seitentitel und -beschreibung zu verändern, muß eine Datei

''droplet.extension.php'' 

existieren. Diese definiert eine Funktion 

''<module_directory>_droplet_header($page_id)'', 

wobei ''<module_directory>'' durch den Verzeichnisnamen des Moduls ersetzt wird, in dem die Datei ''droplet.extension.php'' residiert. Diese Funktion liefert ein assoziatives Array mit folgenden Informationen zurück:

<sxh php>
$result = array(
  'title'       => $title,       // Seitentitel
  'description' => $description, // Kurzbeschreibung
  'keywords'    => $keywords     // Schluesselwoerter
);
</sxh>

Fehlt einer der drei Schlüssel, wird der Standardwert verwendet, mit anderen Worten das, was bei der Seite eingestellt ist.

==== Das Droplet bekannt machen ====

Damit BlackCat CMS weiß, daß es die o.g. Datei auf einer bestimmten Seite einbinden soll, muß diese registriert werden. Hierzu dient die Funktion

''CAT_Helper_Droplet::register_droplet_header( //String// $droplet_name, //Integer// $page_id, //String // $module_directory)''

Diese Funktion kann im Droplet selbst aufgerufen werden, da ja nur das Droplet "weiß", auf welcher Seite es eingebunden ist. Um zu vermeiden, daß sich ein Droplet mehrfach registriert, existiert eine entsprechende Funktion

''CAT_Helper_Droplet::is_registered_droplet_header( //String// $droplet_name,  //Integer// $page_id)''

Der vollständige Code, den ein Droplet verwenden kann, sieht (beispielhaft) demnach so aus:

<sxh php>
    global $page_id;
    // ... maybe more code here...
    if(!CAT_Helper_Droplet::is_registered_droplet_header('mydropletname',$page_id)) {
        CAT_Helper_Droplet::register_droplet_header('mydropletname',$page_id,'mymodulename');
    }
</sxh>

Natürlich sind 'mydropletname' und 'mymodulename' durch die tatsächlichen Werte zu ersetzen!

===== Droplet-CSS und -JS einbinden =====

Manchmal ist es notwendig, für ein Droplet eigene CSS- und JavaScript-Dateien einzubinden. In Website Baker und LEPTON gibt es ohne das DropletsExtension-Modul keine validen Möglichkeiten dafür. In BlackCat CMS natürlich schon.

Analog zu den obigen Funktionen existieren für das Einbinden von CSS- und JS-Dateien entsprechende Funktionen:

''is_registered_droplet_css( //String// $droplet_name, //Integer// $page_id)''\\
''register_droplet_css( //String// $droplet_name, //Integer// $page_id, //String// $module_directory, //String// $file)''

''is_registered_droplet_js( //String// $droplet_name, //Integer// $page_id)''\\
''register_droplet_js( //String// $droplet_name, //Integer// $page_id, //String// $module_directory, //String// $file)''

===== Das Droplet in die Suchfunktion einbeziehen =====

Da war doch noch die Einschränkung mit der Suche... 

Ein Droplet kann sehr einfache bzw. für die Suche nicht relevante Informationen in die Seite einbinden, z.B. das Datum der letzten Änderung, das Suchformular selbst oder eine Login-Box. Es kann aber auch sehr komplexe Inhalte liefern, z.B. einen Veranstaltungskalender. Und die möchte man dann bei der Suche durchaus auch finden können.

Hierzu existiert analog zur Funktion ''<module_directory>_droplet_header($page_id)'' eine Funktion ''<module_directory>_droplet_search($page_id)'', die in der Datei ''droplet.extension.php'' hinterlegt werden kann. Auch diese wird auf dem 'üblichen' Weg bekannt gemacht:

<sxh php>
    global $page_id;
    // ... maybe more code here...
    if(!CAT_Helper_Droplet::is_registered_droplet_search('mydropletname',$page_id)) {
        CAT_Helper_Droplet::register_droplet_search('mydropletname',$page_id,'mymoduledirname');
    }
</sxh>

Als Rückgabe wird eine Gruppe von assoziativen Arrays erwartet, mit der Struktur:

<sxh php>
foreach ($items as $item) {
  $result = array(
    'url'           => $page_url,      // URL der Seite, die die Fundstelle anzeigt 
    'params'        => $params,        // zusaetzliche Parameter die uebergeben werden sollen
    'title'         => $title,         // Titel der Fundstelle
    'description'   => $description,   // Kurzbeschreibung der Fundstelle
    'text'          => $text,          // der zu durchsuchende Text der Fundstelle
    'modified_when' => $modified_when, // UNIX Timestamp
    'modified_by'   => $modified_by    // User ID
  );
}
</sxh>

Wobei die Funktion ''<module_directory>_droplet_search($page_id, $page_url)'' einfach alle in Frage kommenden Fundstellen zurückliefern soll - die eigentliche Suche wird von der CMS-Suchfunktion durchgeführt, die hierzu auf das Feld 'text' zugreift. Daher sollte in dem Feld 'text' plain text ohne HTML Formatierungen stehen. 

===== Droplet-Registrierungen entfernen =====

Bei der Deinstallation des Moduls sollten natürlich auch die Registrierungen entfernt werden, da es sonst zu Fehlermeldungen im Frontend kommt. Hierzu existieren für jeden Typ entsprechende ''unregister''-Methoden:

''unregister_droplet_search( //String// $droplet_name, //Integer// $page_id)''\\
''unregister_droplet_header( //String// $droplet_name, //Integer// $page_id)''\\
''unregister_droplet_css( //String// $droplet_name, //Integer// $page_id)''\\
''unregister_droplet_js( //String// $droplet_name, //Integer// $page_id)''
BlackCat CMS Dokumentation, Tutorials, Tipps und Tricks

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Seiten-Werkzeuge
