(:redirect 'http://docs.studip.de/develop/Entwickler/Trails':)

Ein Controller sollte nie direkt Zugriff auf die Datenbank nehmen und auch sonst so wenig wie möglich Datenstrukturen generieren. Er ist dafür zuständig, die korrekten Daten aus dem richtigen model in die view zu schaffen. Models liegen im passenden Verzeichnis, nämlich 'app/models' und müssen zur Verwendung mittels require_once im Controller inkludiert werden.

Es gibt auch einen Foliensatz, der das Konzept hinter Trails und die Konfiguration von Trails für Stud.IP zeigt:\\

Attach:simple_trails_example.zip

Um das ganze Konzept und die Möglichkeiten zu veranschaulichen wird im Folgenden en detail eine Beispiel-Trails-Seite erklärt, die komplette Seite gibt es auch als ZIP:
Attach:trails_example.zip

Trails & Stud.IP

(:toc:)

(:toc=3:)

(:toc:)

Nur in Stud.IP Eingeloggte oder frei verfügbar?

Die index_action - Wichtigste Action im Controller

Das Url-Schema

Templates für Actions

Manipulation des Kontrollflusses - I

Routing in Trails

Persistente Werte

Manipulation des Kontrollflusses - II

Die folgende Datei ist die view für unser Beispiel.

Infobox

Variablenzugriff und Partials

var_dump($daten) gibt das aus, was wir im Controller mittels $this->daten=… zugewiesen haben. Auf diese Art und Weise gelangen vorbelegt Variablen ins Template.

URLs zu Aktionen in Controllern

Zugriff auf persistente Werte im Template

function redirect_action() {

    $this->redirect('example/asite/helloworld/Hallo Welt! Dieses mal sogar weitergeleitet von redirect!');

} @]

(:source lang=php linenum:)[@

    // do something

Diese Action beinhaltet zwei der wohl wichtigsten Möglichkeiten von Trails.

Zum einen kann man mit $this->redirect(pfad_zum_controller/name_des_controllers/action[/parameter]); auf eine andere Action in einem beliebigen anderen Controller weiterleiten. Das ermöglicht es einem Actions zu haben, die keine eigene Ausgabe brauchen, da sie z.B. nur einen Eintrag löschen und danach die selbe Seite wieder anzeigen. So muss man auch nicht in der index_action irgendwelche $cmd, $command oder sonstige Variablen auswerten. Gibt es eine neue Aktion, baut man einfach eine weitere Action ein und leitet dann passend weiter.

Die Möglichkeit des routens führt uns direkt zu einem weiteren Aspekt von Trails. Was nun, wenn so eine "verdeckt" operierende Aktion eine Statusmeldung auf der Hauptseite, zu der sie hin-routet haben möchte? Für diesen und ähnliche Zweck gibt es die spezielle Variabel flash.
Dieser Variablen kann man direkt einen Wert oder einen Wert an einer Stelle in einem Array zuweisen (wie im Beispiel verwendet). Dieser Wert bleibt nun solange in der Variable $flash gespeichert, bis er ausgelesen wird.
In einer Action kann man dann dort mittels $this->flash zugreifen, im Template einfach $flash.

Außer $this->redirect gibt es noch weitere Möglichkeiten zum Eingriff in den Kontrollfluß.

Ruft man $this->render_text(…) auf so wird nur der angegebene Text ohne jeglichen Stud.IP-Kontext ausgegeben.

$this->render_action(action) ruft das Template für eine Action in diesem Controller auf und gibt es mit Stud.IP-Kontext aus.

$this->render_template(pfad_zum_controller/name_des_controllers/name_des_templates) gibt das angebgene Template ohne Stud.IP-Kontext aus.

Mit $this->render_nothing() sagt man Trails: Bitte kein Template ausgeben.

Die folgende Datei ist die view üfr unser Beispiel.

// Füllt man die Variable $infobox, so erhält man eine Infobox

@]

Die automagische Variable Infobox wird wie eine klassische Infobox mit einem Array gefüllt und dann automatisch ausgegeben. Tut man dies nicht, so wird die Infobox in der Ausgabe als fehlend angezeigt.

(:source lang=php linenum:)[@

$this->render_partial(template) kennt man schon von den normalen Templates. Es erlaubt einem, innerhalb eines Templates ein Subtemplate, ein sogenanntes partial zu inkludieren und anzeigen. Der Inhalt dieser partials wird weiter unten erklärt.
Besonders beachten sollte man, das render_partial einem einen String zurückliefert, den man erst noch ausgeben muss. In unserem Beispiel geschiet dies mittels <?=.

<br> So erhält man einen Pfad zu einem Controller:<br> $controller->url_for('example/asite/backendwithmessage');<br> <br> <a href="<?= $controller->url_for('example/asite/backendwithmessage') ?>"><button>Ausprobieren</button></a> @]

$controller->url_for(path_to_action) ist die wohl wichtigste Funktion innerhalb eines Templates. Wie der Name schon andeutet, erhält man hier eine URL zu einer bestimmten Action in einem bestimmten Controller.
Dies ist die URL die man in Formular, Links, etc. hineinsteckt, wenn man sich innerhalb von Trails bewegen möchte.

app/views/example/asite/_feedback.php (:source lang=php linenum:)[@

@]

Dies ist das oben bereits genannte partial. Partials haben automatisch Zugriff auf alle Variablen ihres Eltern-Templates (dort wo render_partial gesagt wurde). In diesem speziellen Fall wird auf die automagische Variable $flash zugegriffen, die in der backendwithmessage_action definiert hatten.

Diese Action beinhaltet zwei der wohl wichtigsten Möglichkeiten von Trails.
Mit $this->redirect(pfad_zum_controller/name_des_controllers/action[/parameter]

app/views/example/asite/index.php

@]

app/views/example/asite/_feedback.php (:source lang=php linenum:)[@ if ($flash['nachricht']['message']) {

    foreach ($flash['nachricht']['message'] as $nachricht) {
        echo MessageBox::info($nachricht);
    }

}

Hierbei handelt es sich nun um eine Action. Davon kann es in jedem Controller beliebig viele geben. die index_action hat dabei einen kleinen Sonderstatus, wird nämlich in der URL keine Action angegeben, so dient diese als Fallback.

Diese Url hat dabei folgendes Schema:
http://irgendeinstudip/dispatch.php/pfad_zum_controller/name_des_controllers/name_der_action[/parameter1][/parameter2][…]

Das besondere am Trails-Framework ist, dass man sich nicht erst aus der Template-Factory ein Template holen muss, sondern dass (solange man nichts anderes sagt) implizit ein Template, welches zur Action gehört, anzeigt.
Diese Templates liegen unter 'app/views' und dort in diesem Fall unter 'example/asite/index.php'.

Variablen an dieses Template übergibt man, indem sie mittels $this setzt. Im Beispiel oben sieht man, dass $this->daten ein Array erhält. Im Template hat man dann automagisch eine Variable $daten zur Hand, die eben die im Controller zugewiesenen Werte enthält, dazu weiter unten im Ausgabetemplate mehr.

Eine Action kann bei Trails mehr tun, als nur Daten an ein automagisch geladenes Template zu übergeben, sie kann auch auf den Kontrollfluss einfluss nehmen.

Dazu folgende Beispiel-Actions:

function backendwithmessage_action() {

    // delete something
    $this->flash['nachricht'] = array('message' => array('Diese Nachricht wurde bereits in der delete_action in der reservierten Variable flash gespeichert!'));

    // return to index-action
    $this->redirect('example/asite/index');

} @]

function redirect_action() {
    $this->redirect('example/asite/helloworld/Hallo Welt! Dieses mal sogar weitergeleitet von redirect!');
}

(:source lang=php linenum:)[@
function helloworld_action($text = 'Hallo Welt!') {
    $this->render_text(
        'helloworld, $this->render_text(\''. htmlReady(urldecode($text)) .'\')<br>' .
        'Hier wird das einfach nur Text ausgegeben, ohne Layout<br><br>' .
        htmlReady(urldecode($text))
    );
}

function index2_action() {
    $this->daten = array('index2, $this->render_action(\'index\')', 'Hier wird das Template für eine Action in diesem Controller gerendert, mit Layout');
    $this->render_action('index');
}

function index3_action() {
    $this->daten = array('index3: $this->render_template(\'example/asite/index\')', 'Hier wird nur ein Template aus view gerendert, ohne Layout');
    $this->render_template('example/asite/index');
}

(:source lang=php linenum:)[@ function nihilist_action() {

    $this->render_nothing();

    function index_action($param1 = false, $param2 = false)
    {
        // Daten holen

Hierbei handelt es sich nun um eine Action. Davon kann es in jedem Controller beliebig viele geben. die index_action hat dabei einen kleinen Sonderstatus, wurd nämlich in der URL keine Action angegeben, so dient diese als Fallback.
Diese Action kann in Stud.IP nun wie folgt aufgerufen werden:
http://irgendeinstudip/dispatch.php/example/asite/index

Diese Url hat folgendes Schema:
http://irgendeinstudip/dispatch.php/pfad_zum_controller/name_des_controllers/action

<br> So erhält man einen Pfad zu einem Controller:<br> $controller->url_for('example/asite/backendwithmessage');<br> <br> <a href="<?= $controller->url_for('example/asite/backendwithmessage') ?>"><button>Ausprobieren</button></a>

require_once 'app/controllers/studip_controller.php';

@]

Die erste Entscheidung, die man treffen muss, ist, ob man diesen Controllern nur als eingeloggter Nutzer sehen kann oder auch wenn man nicht eingeloggt ist. Dafür entscheidet man sich einfach für eine von zwei Klassen, von denen man erbt.
Wie der Name schon sagt, ist die Klasse 'AuthenticatedController' diejenige, die dafür sorgt, dass nur eingeloggt Nutzer diesen Trails-Controller aufrufen können. Erbt man von 'StudipController', so ist eben (erstmal) kein einloggen nötig. Das müsste der Controller dann bei Bedarf selbst tun.
Der Klassenname des Controllers muss dabei folgenden Aufbau folgen: Pfadangabe1_Pfadangabe2_ … DateinameController

(:source lang=php linenum:)[@

@]

Hierbei handelt es sich nun um eine Action. Davon kann es in jedem Controller beliebig viele geben. die index_action hat dabei einen kleinen Sonderstatus, wurd nämlich in der URL keine Action angegeben, so dient diese als Fallback.

(:source lang=php linenum:)[@

app/controllers/example/asite.php

<?php

require_once 'app/controllers/authenticated_controller.php';

class Example_AsiteController extends AuthenticatedController {
    function index_action($param1 = false, $param2 = false) {
        // Daten besorgen

        $this->daten = array('index', 'Hier wird automagisch das in views/exmaple/asite/index.php hinterlegte Template verwendet. Der Dateiname des Templates ist immer gleich der Action');
    }

    function backendwithmessage_action() {
        // delete something
        $this->flash['nachricht'] = array('message' => array('Diese Nachricht wurde bereits in der delete_action in der reservierten Variable flash gespeichert!'));

        // return to index-action
        $this->redirect('example/asite/index');

    }

    function redirect_action() {
        $this->redirect('example/asite/helloworld/Hallo Welt! Dieses mal sogar weitergeleitet von redirect!');
    }

    function helloworld_action($text = 'Hallo Welt!') {
        $this->render_text(
            'helloworld, $this->render_text(\''. htmlReady(urldecode($text)) .'\')<br>' .
            'Hier wird das einfach nur Text ausgegeben, ohne Layout<br><br>' .
            htmlReady(urldecode($text))
        );
    }

    function index2_action() {
        $this->daten = array('index2, $this->render_action(\'index\')', 'Hier wird das Template für eine Action in diesem Controller gerendert, mit Layout');
        $this->render_action('index');
    }

    function index3_action() {
        $this->daten = array('index3: $this->render_template(\'example/asite/index\')', 'Hier wird nur ein Template aus view gerendert, ohne Layout');
        $this->render_template('example/asite/index');
    }

    function nihilist_action() {
        $this->render_nothing();
    }
}

Die View

app/views/example/asite/_feedback.php

<?php

if ($flash['nachricht']['message']) {
    foreach ($flash['nachricht']['message'] as $nachricht) {
        echo MessageBox::info($nachricht);
    }
}

app/views/example/asite/index.php

<?php

// Füllt man die Variable $infobox, se erhält man eine Infobox

$infobox['picture'] = 'modules.jpg';        // Das Bild der Infobox

$infobox['content'] = array(                // Die Elemente der Infobox
    array(
        'kategorie' => _('Informationen:'),
        'eintrag'   => array(
            array('icon' => 'ausruf_small.gif', 'text' => _('Diese Einträge erhält man durch Füllen der Variable $infobox in einem Template (einer View)')),
            array('icon' => 'link_intern.gif',  'text' => 'Man kann natürlich auch mehrere Einträge haben.')
        )
    )
);


// Ausgeben der im Controller gesetzten Variable
var_dump($daten);
?>

<!-- Ein wenig Text/HTML -->
<b>Huhu</b>

<!-- Ein partial-Template -->
<?= $this->render_partial('example/asite/_feedback'); ?>

Ein Controller sollte nie direkt Zugriff auf die Datenbank nehmen und auch sonst so wenig wie möglich and Datenstrukturen generieren. Er ist dafür zuständig, die korrekten Daten aus dem richtigen model in die view zu schaffen. Models liegen im passenden Verzeichnis, nämlich 'app/models' und müssen zur Verwendung mittels require_once im Controller inkludiert werden.

Ausgaben passieren prinzipiell nur innerhalb der view in Templates. Die Templates liegen dabei in 'app/views' und haben darunter folgende Pfadstruktur '/pfad_zum_controller/name_des_controllers/name_der_action.php'

Um das ganze Konzept und die Möglichkeiten zu veranschaulichen wird im Folgenden en detail eine Beispiel-Trails-Seite erklärt, die komplette Seite gibt es auch als ZIP: Attach:trails_example.zip

Die Struktur

Der Controller ist der Dreh- und Angelpunkt für eine Seite.

Einen neuen Controller erstellt man im Verzeichnis 'app/controllers'. Im einfachsten Fall erstellt man dort direkt eine PHP-Datei. Handelt es sich um eine größere Sammlung von Controllern, kann man auch Unterverzeichnisse erstellen. Die dortige Pfadstruktur überträgt sich dabei 1 zu 1 auf die URL.

Beispiel

Im Folgenden wird im Detail eine Beispiel-Trails-Seite erklärt, die komplette Seite gibt es auch als ZIP: Attach:trails_example.zip

Der Controller

Das Model

Die View

http://luniki.github.com/trails/trails.pdf

Trails & Stud.IP

Im Folgenden gibt es eine kleine Einführung zur Entwicklung von Trails-Seiten in Stud.IP.

Trails folgt dem MVC-Paradigma. Diesem Paradigma folgend gibt es in Stud.IP im Hauptverzeichnis einen Ordnern namens 'app', welcher drei Unterordner hat, 'controllers', 'models' & 'views' besitzt.

Es gibt auch einen Foliensatz, der das Konzept hinter Trails und die Konfigration von Trails für Stud.IP zeigt:
http://luniki.github.com/trails/trails.pdf

Trails

Trails ist ein eigenständiges MVC-Framework, welches in Stud.IP fertig konfiguriert zur Verfügung steht.

Die API-Dokumentation findet man hier:
http://luniki.github.com/trails/doc/index.html

Es gibt auch einen Foliensatz, der die Grundlagen von Trails

Trails