SilverStripe-Tutorial für Neueinsteiger

In diesem Tutorial möchte ich Neueinsteigern anhand eines praktischen Beispiels (blog module) Schritt für Schritt erklären, wie Silverstripe CMS in der Webentwicklung zum Einsatz kommt.

Was wird in diesem Tutorial besprochen?

• Wie die System-Architektur eines modules von Silverstripe aufgebaut ist
• Wie man ein module richtig anlegt und Codes aufteilt
• Wie man models, controllers und templates erstellt
• Wie die Beziehungen (has_one und has_many) zwischen den einzelnen models aufgebaut werden
• Wie man models im admin-panel verwalten kann

Kurze Beschreibung des blog modules
Wir werden den Blog MyBlog nennen. Mithilfe des Blogs sollte es möglich sein, Blogeinträge im backend bzw. im admin-panel einzutragen und diese im frontend aufzulisten. Für jeden Blogeintrag werden folgende Informationen gespeichert:

• Blogüberschrift
• Kurze Beschreibung
• Bloginhalt

1. Vorbereitungen
Zunächst erstellen wir in unserem Installationsverzeichnis eine phpinfo-Datei. Mithilfe dieser Datei können wir herausfinden, ob unser Server die Silverstripe-Voraussetzungen erfüllt. Eine phpinfo-Datei sieht aus wie folgt:

<?php
    echo phpinfo();
?>

Danach downloaden wir von der Silverstripe Download-Website die neueste Version von Silverstripe (CMS + Framework).
Wir entpacken die Dateien in unser Installationsverzeichnis, z.B. localhost/myproject.
Anschließend wechseln wir ins Installationsverzeichnis, das nun folgende Verzeichnisse enthält:

• assets ist das Upload-Verzeichnis. Hier werden alle Bilder und Files von CMS hochgeladen.
• cms ist das Verzeichnis des CMS-Modules von silverstripe. Die Files in diesem Ordner dürfen nicht verändert werden.
• framework enthält alle Silverstripe-Frameworkfiles. Auch hier darf vorerst nichts verändert werden.
• mysite sind die working spaces unseres Projekts myproject. Hier werden controllers und models extension erstellt.
• themes ist das Templates-Verzeichnis. Hier werden Templates für unser Projekt MyBlog angepasst.
• vendor enthält Thirdparty Files

Nachdem wir die Vorbereitungen für CMS vorgenommen haben, können wir CMS installieren. Die Installation verläuft sehr einfach und schnell.
Wir rufen unsere Projektseite z.B. http://localhost/myproject auf. Daraufhin startet der Silverstripe-Installationsassistent automatisch. Nachdem die Installation erfolgreich abgeschlossen wurde, loggen wir uns im admin-panel http://localhost/myproject/admin ein. Nun können wir uns das CMS-System im admin-panel ansehen und versuchen, einige Seiten anzulegen, zu editieren und zu löschen, um mit Silverstripe vertraut zu werden.

2. Verzeichnis-Struktur eines Projekts anlegen
Zuerst ändern wir den Namen des Verzeichnisses mysite zu myblog. In mysite/code/ legen wir anschließend zwei Verzeichnisse an: controllers und models. Im controllers-Verzeichnis werden alle controllers des Modules myblog angelegt, im models-Verzeichnis alle models.

Wir erstellen nun ein neues Verzeichnis im themes-Verzeichnis und nennen es myblog.

Danach kopieren wir alle files vom Verzeichnis themes/simple/ und fügen diese in themes/myblog/ ein. Nun möchten wir Silverstripe unsere neue Verzeichnis-Architektur mitteilen, indem wir zu http://localhost/myproject/admin/settings/ gehen und das theme myblog aus der Liste wählen.

Um die neuen Updates der Verzeichnis-Struktur zu aktualisieren, rufen wir folgende URLs auf:
http://localhost/myproject/dev/build/    mit dieser URL wird die Verzeichnis-Struktur und Datenbank-Schema aktualisiert
http://localhost/myproject/?flush=1    mit dieser URL wird der Cache entleert

3. Model erstellen
Zunächst legen wir eine Datei MyBlog.php in myblog/models/ an.
Anschließend fügen wir in der Datei MyBlog.php folgende Zeilen ein:

<?php
class MyBlog extends DataObject {
    private static $db = array(
        'BlogTitle' => 'varchar', // Blogüberschrift
        'BlogShortDescription' => 'text', // kurze Beschreibung des Blogeintrags
        'BlogContent' => 'HTMLText', // Bloginhalt
    );
    private static $summary_fields = array(
        'ID',
        'BlogTitle',
    );
}
?>

Mit private static $db  legen wir das Datenbank-Schema des models fest.
Mit private static $summary_fields definieren wir, welche Felder auf der Modelübersichtsseite im admin-panel aufgelistet werden.

ACHTUNG! SILVERSTRIPE LEGT FÜR JEDES MODEL AUTOMATISCH ID, Created und LastEdited-FELDER AN.

Nachdem wir die Datei MyBlog.php gespeichert haben, rufen wir die URL http://localhost/myblog/dev/build/ auf, um das Datenbank-Schema des models zu bilden. Hier wird Silverstripe eine mysql-table MyBlog in der Datenbank anlegen.

Auf der Silverstripe-Website erhältst du weitere Informationen über DataObject, sowie über Data Types

4. Modeladmin
Um Blogeinträge in der Datenbank speichern zu können, benötigen wir ein Modeladmin für das MyBlog-Model. Diesen erhalten wir, indem wir eine Datei MyBlogAdmin.php im models-Verzeichnis myblog/code/models anlegen.
In der Datei MyBlogAdmin.php fügen wir folgende Zeilen ein:

<?php
class MyBlogAdmin extends ModelAdmin {
    static $managed_models = array('MyBlog');
    static $url_segment = 'MyBlog';
    static $menu_title = 'My Blog';
}
?>

static $managed_models definiert, welche models vom ModelAdmin im admin-panel verwaltet((Einträge hinzufügen, bearbeiten und löschen)) werden können
static $url_segment definiert die model-URL im admin-panel, z.B. admin/MyBlog/
static $menu_title definiert die Navigationsbezeichnung des models im admin-panel

Mehr über ModelAdmin findest du auf der Silverstripe-Website: http://doc.silverstripe.org/framework/en/reference/modeladmin

Nun speichern wir die Datei MyBlogAdmin.php und rufen folgende URLs auf:
http://localhost/myblog/dev/build/
http://localhost/myblog/?flush=1

Anschließend rufen wir http://localhost/myblog/admin/ auf. In der linken Spalte des admin-Menüs sehen wir den Navigationspunkt My Blog. Auf diesen klicken wir, um zur MyBlog Model-Übersichtsseite zu gelangen. Auf der Model-Übersichtsseite können wir unser model MyBlog verwalten. Um einen neuen Blogeintrag in der Datenbank zu speichern klicken wir auf Hinzufügen. Nun fügen wir mehrere Testeinträge hinzu und versuchen auch, sie zu bearbeiten, um mit dem model vertraut zu werden.

Wichtig zu erwähnen ist, dass Silverstripe Formulare im admin-Panel anhand des Datenbank-Schemas des MyBlog-models festlegt. In einem späteren Blog werde ich mithilfe eines Beispiels zeigen, wie Formulare individuell gestaltet werden können.

5. Page controller im frontend
Um Blogeinträge des MyBlog-models im frontend auflisten zu können, benötigen wir einen controller, der die Daten vom MyBlog-model holt und an ein template als array schickt.

Wir erstellen eine Datei MyBlogPage.php in myblog/code/controllers/ und fügen folgende Zeilen ein:

<?php
class MyBlogPage extends Page {}

class MyBlogPage_Controller extends Page_Controller {}
?>

Die Klasse MyBlogPage liegt im Silverstripe-CMS ein neuer Seitentyp heißt MyBlogPage. Weiters kann mit der Klasse MyBlogPage das Datenbank-Schema des Seitentyps MyBlogPage erweitert werden. Für unser Beispiel ist die Klasse MyBlogPage_Controller von größerer Bedeutung. In diese schreiben wir einzelne Methoden, um Daten von der Datenbank auszulesen.

Wir speichern die Datei MyBlogPage.php und rufen erneut folgende URLs auf:
http://localhost/myblog/dev/build/
http://localhost/myblog/?flush=1

Anschließend legen wir eine neue CMS-Seite MyBlog im Admin-Panel an. Als Seitentype wählen wir My Blog Page. Auch als Seitennamen, URL-Segment und Navigationsbezeichnung wählen wir MyBlog. In der Content- bzw. Inhalt-Box schreiben wir als Testeintrag „My Blog Seite“.  Zum Schluss klicken wir auf speichern und veröffentlichen.

Im CMS ist unsere Seite MyBlog bereits eingerichtet. Wir wechseln zu http://localhost/myblog/. In der Menüleiste sehen wir nun den Navigationspunkt MyBlog.

Um Blogeinträge im frontend aufzulisten, schreiben wie eine neue Methode items im MyBlogPage_Controller.

<?php
class MyBlogPage extends Page {}
class MyBlogPage_Controller extends Page_Controller {
    // Blogeinträge von der Datenbank auslesen
    public function items() {
        $items = MyBlog::get()->sort('BlogTitle ASC');
        if ($items)
            return $items;
        else
            return false;
    }
}
?>

6. Blogeinträge in der template auslesen
Um Blogeinträge im frontend auflisten zu können, müssen wir zuerst ein template MyBlogPage.ss in themes/myblog/templates/layout/ erstellen.
Der Templatename sollte lauten wie der Controllername, an den allerdings hinten noch das Wort Page angehängt wird. Silverstripe erkennt beim Aufruf des Controllers http://localhost/myblog/MyBlog automatisch das template MyBlogPage.ss.

Ist MyBlogPage.ss nicht definiert, wird Silverstripe die template themes/myblog/templates/layour/Page.ss als Defaulttemplate aufrufen.

Nachdem wir die template MyBlogPage.ss erstellt haben, fügen wir in dieses folgenden Code ein:

<article>
    <h1>$Title</h1>
    <div>$Content</div>
    <% if $items %>
        <% loop $items %>
        <h3<a href=”{$Up.URLSegment}/BlogDetails/{$ID}”>$BlogTitle</a></h3>
        <p>$BlogShortDescription</p>
        <% end_loop %>
    <% end_if %>
</article>

Erklärung zum obigen Code:
$Title ist die Überschrift der Seite MyBlog und kommt von CMS.
$Content ist der Content der Seite MyBlog und kommt ebenfalls von CMS.
$items ist ein array und kommt von public function items im MyBlogPage_Controller

Mit der loop-Schleife lesen wir einzelne Blogeinträge von der Variable $items.
$Up.URLSegment kommt von CMS und definiert die URL der Seite MyBlog.

“Mit $Up greifen wir auf die globale Variable außerhalb einer Schleife zu.”

BlogDetails ist der Actionname im MyBlog_Controller, den wir später als public function BlogDetails erstellen werden, um Details eines Blogeintrags von der Datenbank auszulesen und in einem template darzustellen.
$BlogTitle ist die Blogüberschrift jedes einzelnen Blogeintrags.

Mehr über templates erfährst du auf der Silverstripe-Website: http://doc.silverstripe.org/framework/en/reference/templates

Wir speichern nun unsere templates und leeren den Cache mit http://localhost/myblog/?flush=1
Anschließend rufen wir unsere MyBlog-Seite http://localhost/myblog/myblog/ auf.

7. Erstellen einer actions
Um Details eines Blogeintrags im frontend auflisten zu können, müssen wir eine action im MyBlog_controller schreiben. In unserem Fall heißt diese action BlogDetails.

Bevor wir die methode BlogDetails schreiben, müssen wir den actionnamen BlogDetails in der Variable $allowed_actions definieren, sodass Silverstripe-CMS diese action BlogDetails ausführt, wenn die URL http://localhost/myblog/myblog/BlogDetails/1 aufgerufen wird (1 ist die ID des Blogeintrags).
Wird BlogDetails in der Variable $allowed_actions nicht definiert, so wird beim Aufruf der action eine Fehlermeldung von Silverstripe erscheinen.

Nun schreiben wir in unserem MyBlog_controller die Methode BlogDetails.

   //
   //
   //Alle Details des Eintrags aus der Datenbank auslesen
    public function BlogDetails() {
        $params = $this->getURLParams();
        $item = MyBlog::get()->byID($params['ID']);
        if ($item)
            return $this->customise(array('BlogItem' => $item));
        else
            return false;
    }

Erstellen eines templates für unseren action-MyBlog
Um Details eines Blogeintrages in einem template darstellen zu können, müssen wir ein neues template MyBlogPage_BlogDetails.ss in themes/myblog/templates/layout/ anlegen.

Wir öffnen nun die template MyBlogPage_BlogDetails.ss und fügen folgende Zeilen ein:

<% if $BlogItem %>
    <article>
    <h1>$BlogItem .BlogTitle</h1>
    <div class=”content”>$BlogItem .BlogContent</div>
    <div class=”info”>$BlogItem .Created.Format('d.m.Y')</div>
    </article>
<% end_if %>

 Wir speichern MyBlogPage_BlogDetails.ss und entleeren den Cache nochmals mit http://localhost/myblog/?flush=1