DropletsExtension - der Nachbrenner für ihre Code-Schnipsel

Es gibt Leute, die behaupten Droplets machen süchtig. Dafür gibt es gute Gründe, ich kenne kein anderes Content Management System, das über eine ähnlich leistungsfähige und flexible Möglichkeit verfügt an einer beliebigen Stelle mit einem einfachen Befehl Datenbankabfragen und Programmcode einzubinden.

Solange Droplets dazu verwendet werden beispielsweise mitten im Fliesstext auszurechnen, dass es noch 220 Tage dauert, bis das Christkind wieder vor der Tür steht, also kleine und einfache Berechnungen oder Datenbankabfragen durchzuführen, ergeben sich daraus keinerlei Nachteile. Droplets werden jedoch auch als Schnittstelle für vollständige Anwendungen genutzt und bilden z.B. eine Brücke zwischen einem Admin-Tool im Backend und der Interaktion mit dem Frontend.

Hieraus ergeben sich neue und sehr anpassungsfähige Anwendungsmöglichkeiten. So können Termine und Veranstaltungen mit kitEvent zentral und übersichtlich mit Hilfe eines Admin-Tools verwaltet und organisiert werden, die Ausgabe erfolgt an unterschiedlichen Stellen auf der Website - wie hier auf der phpManufaktur in Form eines Kalenderblatt unterhalb der Navigation auf der linken Seite und zusätzlich als übersichtliche Liste unter Workshops & Termine sowie gezielt mit Veranstaltungshinweisen für die WebsiteBaker Usergroup Berlin. Darüber hinaus können die Termine mit Details und einem Anmeldeformular angezeigt werden. Diese Flexibilität wird durch Droplets überhaupt erst möglich.

Wo ist der Haken dabei?

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 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.

Diese Nachteile behebt DropletsExtension vollständig, der Programmierer erhält eine Schnittstelle über die er seinem Droplet die gewünschten Fähigkeiten zur Verfügung stellen kann.

Wie funktioniert es?

Der erste Schritt besteht darin, das Seitenmodul DropletsExtension zu installieren. Dieses Seitenmodul erfüllt keinen unmittelbar sichtbaren Zweck, es muss vorhanden sein und es muss letztlich genau einmal auf irgendeiner Seite als zusätzlicher Abschnitt eingebunden sein. DropletsExtension bildet eine Brücke zwischen beliebigen Droplets und der WebsiteBaker Suchfunktion. Hierfür stellt es den Droplets ein Interface zur Verfügung.

Ein Droplet in die WebsiteBaker Suchfunktion einbinden

Zunächst muss das Droplet das DropletsExtension Interface einbinden:

// Connect with DropletsExtension Interface
if (file_exists(WB_PATH.'/modules/droplets_extension/interface.php')) {
  require_once(WB_PATH.'/modules/droplets_extension/interface.php');
}

Der nächste Schritt besteht darin, dass das Droplet sich bei DropletExtension für die WebsiteBaker Suchfunktion registriert:

// Register Droplet for the WebsiteBaker Search Function
if (function_exists('is_registered_droplet_search') && !is_registered_droplet_search('droplet_name', PAGE_ID)) {
  register_droplet_search('droplet_name', PAGE_ID, 'module_directory');
}

Die Funktion is_registered_droplet_search() dient dazu abzufragen, ob das angegebene Droplet bereits für die WebsiteBaker Suche registriert ist, register_droplet_search() dient dazu das Droplet für die Suche anzumelden. Verwendet werden hierbei drei Parameter:

• droplet_name ist der Bezeichner des jeweiligen Droplet
• die WebsiteBaker Konstante PAGE_ID enthält die ID der Seite, auf der sich das Droplet befindet
• module_directory ist der Name des WebsiteBaker /modules Verzeichnis, in dem sich das Addon befindet zu dem das jeweilige Droplet gehört

Die WebsiteBaker Suche arbeitet in zwei Schritten. Im ersten Schritt werden die Seiteninhalte durchsucht und im zweiten Schritt erhalten Seitenmodule (und nur diese!) die über eine search.php im Modulverzeichnis verfügen eine Aufforderung die Inhalte bereitzustellen, die bei der Suche berücksichtigt werden sollen. DropletExtension reicht diese Aufforderung über seine eigene search.php an die jeweiligen Droplets durch.

Hierzu sucht DropletExtension im Modulverzeichnis der registrierten Droplets nach der Datei droplet.extension.php und in dieser Datei nach der Funktion module_directory_droplet_search($page_id, $page_url) - wobei module_directory durch den tatsächlichen Verzeichnisnamen des jeweiligen Addon zu ersetzen ist! DropletExtension liefert der Funktion die $page_id der Seite für die ein Suchergebnis zu liefern ist und zusätzlich mit $page_url die vollständige URL der Seite.

Als Rückgabe erwartet DropletExtension eine Gruppe von assoziativen Arrays 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 WebsiteBaker Suchfunktion durchgeführt, die hierzu auf das Feld 'text' zugreift. Liefern Sie der Suchfunktion in dem Feld 'text' plain text ohne HTML Formatierungen.  

In dem Addon kitEvent sieht der vollständige Funktionsaufruf so aus:

function kit_event_droplet_search($page_id, $page_url) {
  global $dbEvent;
  global $dbEventItem;
  global $parser;
  $SQL = sprintf( "SELECT * FROM %s,%s WHERE %s.%s=%s.%s AND %s='%s' ORDER BY %s DESC",
                  $dbEvent->getTableName(),
                  $dbEventItem->getTableName(),
                  $dbEvent->getTableName(),
                  dbEvent::field_event_item,
                  $dbEventItem->getTableName(),
                  dbEventItem::field_id,
                  dbEvent::field_status,
                  dbEvent::status_active,
                  dbEvent::field_event_date_from);
  $events = array();
  if (!$dbEvent->sqlExec($SQL, $events)) {
    trigger_error(sprintf('[%s - %s] %s', __FUNCTION__, __LINE__, $dbEvent->getError()), E_USER_ERROR);
    return false;
  }
  $result = array();
  $htt_path = WB_PATH.'/modules/'.basename(dirname(__FILE__)).'/htt/';
  $tpl_title = new Dwoo_Template_File($htt_path.'search.result.title.htt');
  $tpl_description = new Dwoo_Template_File($htt_path.'search.result.description.htt');
  foreach ($events as $event) {
    $result[] = array(
      'url' => $page_url,
      'params' => http_build_query(array(eventFrontend::request_action => eventFrontend::action_event,
                                         eventFrontend::request_event => eventFrontend::view_id,
                                         eventFrontend::request_event_id => $event[dbEvent::field_id],
                                         eventFrontend::request_event_detail => 1)), 
      'title' => $parser->get($tpl_title, array('date_time' => sprintf('%s %s', date(event_cfg_datetime_str, strtotime($event[dbEvent::field_event_date_from])), event_text_hour),
                                                'title' => $event[dbEventItem::field_title])), 
      'description' => $parser->get($tpl_description, array('description' => strip_tags($event[dbEventItem::field_desc_short]))),
      'text' => strip_tags($event[dbEventItem::field_desc_short]).' '.strip_tags($event[dbEventItem::field_desc_long]),
      'modified_when' => strtotime($event[dbEvent::field_timestamp]),
      'modified_by'		=> 1 // admin
    );
  }
  return $result; 
} // kit_event_droplet_search()

Das Ergebnis kann sich sehen lassen. Probieren Sie es aus, in dem Sie nach "Stallman" suchen:

Sie sehen, dass sich die Darstellung Suchergebnis durchaus gestalten lässt.

Interessant wird es, wenn Sie sich den Link auf die Veranstaltung genauer ansehen, er verweist auf die Seite Workshops & Termine und zusätzlich werden eine Reihe von Parametern übergeben, die es dem Droplet [[kit_event]] ermöglichen die Details zu dem Event "Richard Stallman" anzuzeigen.

Damit sind wir bei der nächsten Fähigkeit von DropletsExtension angelangt, die es einem Droplet ermöglicht, den Seitentitel, die Kurzbeschreibung und die Schüsselwörter einer Seite festzulegen. Schauen Sie sich bitte die Detailseite zu dem Event "Richard Stallman" an, der Termin legt die Seitenbeschreibung fest.

Die Seitenbeschreibung durch ein Droplet festlegen lassen

Damit die Beschreibung einer Seite beliebig verändert werden kann, ist es erforderlich das Template der Website in diese Dynamik einzubeziehen. Hierzu dient eine spezielle Funktion von DropletsExtension die anstatt der Standard Aufrufe für die Seitenbeschreibung, Schlüsselwörter und den Seitentitel eingebunden wird.

Ersetzen Sie hierzu im Template der Website die Aufrufe:

<meta name="description" content="<?php page_description(); ?>" />
<meta name="keywords" content="<?php page_keywords(); ?>" />
<title><?php page_title('', '[WEBSITE_TITLE]'); ?></title>

durch die folgenden Zeilen:

<?php
  if (file_exists(WB_PATH.'/modules/droplets_extension/interface.php')) { 
    require_once(WB_PATH.'/modules/droplets_extension/interface.php');
    print_page_head();
  }
  else { ?>
    <meta name="description" content="<?php page_description(); ?>" />
    <meta name="keywords" content="<?php page_keywords(); ?>" />
    <title><?php page_title('', '[WEBSITE_TITLE]'); ?></title>
  <?php }
?>

Die Funktion print_page_head() funktioniert vom Prinzip her wie das bekannte simplepagehead() von Chio Maisriml und unterstützt ebenfalls Topics (weitere Module und Addons werden noch folgen).

Als nächstes definieren Sie in der Datei droplet.extension.php die Funktion module_directory_droplet_header($page_id), wobei Sie module_directory wieder durch den tatsächlichen Verzeichnisnamen des jeweiligen Addon ersetzen.

DropletsExtension ruft die Funktion module_directory_droplet_header($page_id) auf und erwartet die Rückgabe eines assoziativen Array, das folgende Angaben enthält:

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

Zu guter Letzt muss sich das Droplet noch bei DropletsExtension registrieren:

if (function_exists('is_registered_droplet_header') && !is_registered_droplet_header('droplet_name', PAGE_ID)) { 
  register_droplet_header('droplet_name', PAGE_ID, 'module_directory');
}

... und schon kann das Droplet die Seitenbeschreibung selbst nach Belieben festlegen.

Automatisch ein Cascading Stylsheet für das Droplet laden

Jetzt fehlt nur noch die Möglichkeit, dass automatisch ein bestimmtes CSS-Stylesheet für das Droplet geladen wird. Die Voraussetzung hierfür ist, dass die Funktion print_page_head() im Template der Website eingebunden ist.

Das Droplet registriert einfach das gewünschte Template bei DropletsExtension:

if (function_exists('is_registered_droplet_css') && !is_registered_droplet_css('droplet_name', PAGE_ID)) { 
  register_droplet_css('droplet_name', PAGE_ID, 'module_directory', 'frontend.css');
}

Die angegebene CSS-Datei muss sich im Verzeichnis des jeweiligen Moduls befinden.

Automatisch eine JavaScript Datei für das Droplet laden

Die Einbindung einer JavaScript Datei für das Droplet funktioniert genauso einfach. Auch hier ist die Voraussetzung, dass die Funktion print_page_head() im Template der Website eingebunden ist:

if (function_exists('is_registered_droplet_js') && !is_registered_droplet_js('droplet_name', PAGE_ID)) { 
  register_droplet_js('droplet_name', PAGE_ID, 'module_directory', 'javascript.js');
}

Die angegebene JavaScript-Datei muss sich im Verzeichnis des jeweiligen Moduls befinden.

Download DropletsExtension

Bitte helfen Sie mit diese Beschreibung zu ergänzen und zu verbessern!