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.

Dieser Text wurde aus der 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.

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:

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

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

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:

    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');
    }

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

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)

Beispiel:

    if(!CAT_Helper_Droplet::is_registered_droplet_css('mymodule',$page_id)) {
        CAT_Helper_Droplet::register_droplet_css('mymoduledroplet',$page_id,'/modules/mymodule','/css/frontend.css');
    }

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:

    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');
    }

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

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
  );
}

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.

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)