Zur Übersicht

Beispiel: Serendipity-Plugin

Sidebar-Plugin im Blog

Den Quellcode des Beispiels finden Sie unter http://api.golem.de/download/index.php#s9yexample.

Serendipity, kurz meist S9Y genannt, ist eine populäre Blogsoftware, die sehr einfach über Plugins erweitert werden kann. Das Beispiel implementiert ein Seitenleisten-Plugin, um die neusten fünf Artikel auf Golem.de im Blog darzustellen.

Hinweis: Dieser Artikel ist keine Einführung in die Erstellung eines S9Y-Plugins. Wenn Sie nähere Informationen zur Programmeirung eines S9Y-Plugins suchen, sollten Sie einen Blick in dessen Technischen Dokumentation werfen.

Verzeichnisstruktur

Die Dateisystemstruktur eines S9Y-Plugin besteht aus einem Verzeichnis, dass alle notwendigen Dateien des Plugins enthält. Erstellen Sie im plugin-Verzeichnis Ihrer S9Y-Installation das Verzeichnis serendipity_plugin_golemlatestarticle. Das ist Ihr Plugin-Verzeichnis.

In das Verzeichnis kopieren Sie das PHP-API-Paket. Sie müssen nicht das vollständig entpackte Paket dorthin kopieren, das Verzeichnis Golem ist ausreichend. Sie benötigen es, um einfach auf Golem.de-Inhalte zugreifen zu können.

Der eigentliche Code des Plugins befindet sich in der Datei serendipity_plugin_golemlatestarticle.php. Der Name der Datei muss dem Namen des Plugin-Verzeichnisses entsprechen Diese Datei wird von S9Y automatisch eingebunden. Innerhalb der Datei müssen Sie eine Klasse mit dem Namen der Datei implementieren, also serendipity_plugin_golemlatestarticle. Sie wird von S9Y angesprochen und stellt die Funktionen des Plugins bereit.

Die Plugin-Klasse

Innerhalb der Datei definieren Sie eine Klasse entsprechend dem Dateinamen, und die Klasse muss abgeleitet werden von serendipity_plugin, der Basisklasse für ein Plugin.

class serendipity_plugin_golemlatestarticle extends serendipity_plugin {

...

}
Beispiel 1: Klassendefinition

Damit ein Anwender das Plugins auch nutzen kann, benötigt es einen Konfigurations-Parameter für die Angabe des Golem.de-Entwicklerschlüssels. Sinnvoll ist auch eine Auswahl wie viele Einträge dargestellt werden sollen.

S9Y ruft bei der Einbindung des Plugins die Methode introspect() auf, in der Sie S9Y sagen, dass wir die beiden Parameter devkey und count definieren. Der Parameter devkey nimmt den Entwicklerschlüssel auf, count enthält die Anzahl der Einträge.

class serendipity_plugin_golemlatestarticle extends serendipity_plugin {

    function introspect(&$propbag) {

        ...
        $propbag->add('configuration', array('devkey', 'count'));

    }

    ...
}
Beispiel 2: introspect()-Methode

Mit jedem Eintrag der übergebenen Liste wird die Methode introspect_config_item() aufgerufen. Für jeden der Konfigurationsparameter definieren Sie dessen Datentyp. Standardwert und das zugehörige Textlabel im Konfigurationsdialog.

    ...

    function introspect_config_item($name, &$propbag) {
        global $serendipity;
        switch($name) {
            case 'devkey':
                $propbag->add('type',        'string');
                $propbag->add('name',        'devkey');
                $propbag->add('description', PLUGIN_GOLEMLATESTARTICLE_DEVKEY);
                $propbag->add('default',     '');
                break;

            case 'count':
                $propbag->add('type',        'string');
                $propbag->add('name',        'count');
                $propbag->add('description', PLUGIN_GOLEMLATESTARTICLE_COUNT);
                $propbag->add('default',     '5');
                break;

            default:
                return false;
        }
        return true;
    }

    ...

Beispiel 2: introspect_config_methode()-Methode

Nachdem Sie die Basis für das Plugin geschrieben haben, können Sie die eigentlich Funktion des Plugins umsetzen. Zentrale Anlaufstelle dafür ist die Methode generate_content(). S9Y ruft sie auf, um die Ausgabe des Plugins zu erhalten, also die HTML-Liste der Artikel.

    ...
    function generate_content(&$title) {
        
        ...

    }
    ...
Beispiel 3: Gerüst der generate_content()-Methode

Artikelliste laden und darstellen

Innerhalb der Methode verwenden Sie die Klasse Golem_Api_Article_Latest, um die neusten Golem.de-Artikel zu erhalten. Dafür benötigen Sie den Entwicklerschlüssel und die Anzahl der Einträge aus der Plugin-Konfiguration. Sie erhalten sie über die Methode get_config(), die von der geerbten Klasse bereitgestellt wird.

    ...
    function generate_content(&$title) {
        
        ...

        $devkey = $this->get_config('devkey');
        $count  = $this->get_config('count');
        
        if(empty($devkey)) {

            echo PLUGIN_GOLEMLATESTARTICLE_NODEVKEY;

        }

    }
    ...
Beispiel 4: Zuweisung der Konfigurationsparameter

Sie sollten prüfen, ob der Parameter für den Entwicklerschlüssel tatsächlich einen Wert enthält und nicht leer ist. Ansonsten sollten Sie eine Fehlermeldung anzeigen.

Die Abfrage nach den Artikeln erfordert keinen großen Aufwand. Sie erzeugen ein neues Objekt der Klasse Golem_Api_Article_Latest, dem Konstruktor übergeben Sie den Entwicklerschlüssel und die Anzahl der gewünschten Einträge. Die Abfrage führen Sie mit der fetch()-Methode aus. War sie erfolgreich, erhalten Sie eine Liste der Artikel in einem Array von getArticles(). Sie sollten die Abfrage in einen Try-Catch-Block packen, damit sie kontrolliert Fehler abfangen können.


        ...

        $request = new Golem_Api_Article_Latest($devkey, $count);

        ...

        try {

            $request->fetch();

            $articles = $request->getArticles();

        } catch (Exception $e) {

            echo $e->getMessage();

        }

        ...

Beispiel 5: Artikelliste holen

Aus dem Array bauen Sie in einer Schleife die HTML-Liste, die Sie per echo ausgeben. Damit ist das einfache S9y-Plugin bereits fertig.


        ...

        $html = '';

        $html = $html.'<ul>';

        foreach( $articles as $article ) {

            $html = $html.'<li>';
            $html = $html.'<a href="'.$article['url'].'" target="_blank">'.$article['headline'].'</a>';
            $html = $html.'</li>';

        }

        $html = $html.'</ul>';

        echo $html;
        
        ...
Beispiel 6: Artikelliste ausgeben

Caching

Entsprechend Ihren realen Möglichkeiten und der Besucheranzahl sollten sie das Plugin um eine spezifische Cache-Lösung erweitern. Zum einen kostet die Anfrage an den Golem.de-Server jedes Mal Zeit, um die sich die Auslieferungszeit des Blogs verzögert. Zum anderen sind mit einem normalen Entwicklerschlüssel nur eine begrenzte Anzahl von Abfragen pro Tag erlaubt. Wird das Limit überschritten, würde das Plugin nur einen Fehler anzeigen, wenn zu viele Besucher auf dem Blog waren.

Deshalb empfiehlt es sich, den Request nur in bestimmten Zeitabständen durchzuführen, zum Beispiel alle 10 Minuten, und die erzeugte HTML-Liste in einer Datei oder per memcached zu speichern, und regulär nur diese gecachte HTML-Liste auszuliefern.

Installation

Konfigurationsbox des Plugins

Wenn Sie das Verzeichnis serendipity_plugin_golemlatestarticle im plugin-Verzeichnis Ihrer S9Y-Installation angelegt haben, dann wird es automatisch von S9Y erkannt. Gehen Sie in die Verwaltungsoberfläche von S9Y und klicken Sie im Menü auf Plugins verwalten.

Gleich am Anfang der Plugin-Verwaltung befindet sich der Link Hier klicken, um Seitenleisten-Plugin zu installieren. Klicken Sie Ihn an und suchen Sie ihr Plugin in der erscheinenden Liste. Klicken Sie auf das Disketten-Symbol rechts vom Plugineintrag, um es einzubinden.

Danach erscheint es in der Auflistung der Seitenleisten-Plugins. Als nächstes müssen Sie von hier aus müssen Sie die Konfigurationsseite des Plugins aufrufen. Klicken Sie dazu auf das Schrauben-Symbol im Kasten des Plugins.

Auf der Konfigurationsseite werden die beiden Parameter mit ihren Standardwerten aufgelistet. Tragen Sie Ihren Entwicklerschlüssel ein und ändern Sie die Anzahl der Einträge, wenn sie es möchten. Klicken Sie danach auf den Speichern-Button und die Artikel werden im Blog angezeigt.

Konfigurationsseite des Plugins

Zur Übersicht

Beispiel: Serendipity-Plugin