Trails

Trails

Auf dieser Seite... (ausblenden)

  1. 1. Trails & Stud.IP
  2. 2. Die Struktur
  3. 3. Beispiel
  4. 4. Der Controller
    1. 4.1 Nur in Stud.IP Eingeloggte oder frei verfügbar?
    2. 4.2 Die index_action - Wichtigste Action im Controller
    3. 4.3 Das Url-Schema
    4. 4.4 Templates für Actions
    5. 4.5 Manipulation des Kontrollflusses - I
    6. 4.6 Routing in Trails
    7. 4.7 Persistente Werte
    8. 4.8 Manipulation des Kontrollflusses - II
    9. 4.9 Infobox
  5. 5. Die View
    1. 5.1 Infobox
    2. 5.2 Variablenzugriff und Partials
    3. 5.3 URLs zu Aktionen in Controllern
    4. 5.4 Zugriff auf persistente Werte im Template

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 das Konzept hinter Trails und die Konfiguration von Trails für Stud.IP zeigt:
http://luniki.github.com/trails/trails.pdf

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

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

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.

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'

3. Beispiel

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:simple_trails_example.zip

4. Der Controller

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

app/controllers/example/asite.php

  1. require_once 'app/controllers/authenticated_controller.php';
  2. require_once 'app/controllers/studip_controller.php';
  3.  
  4. class Example_AsiteController extends AuthenticatedController {
[Code herunterladen]

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

4.2 Die index_action - Wichtigste Action im Controller

  1. function index_action($param1 = false, $param2 = false)
  2.     {
  3.         // Daten holen
  4.  
  5.         $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');
  6.     }
[Code herunterladen]

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.

4.3 Das Url-Schema

Diese Action kann in Stud.IP nun wie folgt aufgerufen werden:
http://irgendeinstudip/dispatch.php/example/asite/index

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

4.4 Templates für Actions

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.

4.5 Manipulation des Kontrollflusses - I

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:

  1. function redirect_action() {
  2.     $this->redirect('example/asite/helloworld/Hallo Welt! Dieses mal sogar weitergeleitet von redirect!');
  3. }
[Code herunterladen]
  1. function backendwithmessage_action()
  2. {
  3.     // do something
  4.     $this->flash['nachricht'] = array('message' => array('Diese Nachricht wurde bereits in der delete_action in der reservierten Variable flash gespeichert!'));
  5.  
  6.     // return to index-action
  7.     $this->redirect('example/asite/index');
  8.  
  9. }
[Code herunterladen]

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

4.6 Routing in 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.

4.7 Persistente Werte

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.

4.8 Manipulation des Kontrollflusses - II

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

  1. function helloworld_action($text = 'Hallo Welt!') {
  2.     $this->render_text(
  3.         'helloworld, $this->render_text(\''. htmlReady(urldecode($text)) .'\')<br>' .
  4.         'Hier wird das einfach nur Text ausgegeben, ohne Layout<br><br>' .
  5.         htmlReady(urldecode($text))
  6.     );
  7. }
[Code herunterladen]

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

  1. function index2_action() {
  2.     $this->daten = array('index2, $this->render_action(\'index\')', 'Hier wird das Template für eine Action in diesem Controller gerendert, mit Layout');
  3.     $this->render_action('index');
  4. }
[Code herunterladen]

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

  1. function index3_action() {
  2.     $this->daten = array('index3: $this->render_template(\'example/asite/index\')', 'Hier wird nur ein Template aus view gerendert, ohne Layout');
  3.     $this->render_template('example/asite/index');
  4. }
[Code herunterladen]

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

  1. function nihilist_action()
  2. {
  3.     $this->render_nothing();
  4. }
[Code herunterladen]

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

4.9 Infobox

Seit Stud.IP 2.3 kann die Infobox des Views auch wie im folgenden Beispiel gefüllt werden:

function infobox_action()
{
    // Definiert das Bild der Infobox
    $this->setInfoBoxImage('blank.gif');

    // Fügt Einträge zur Infobox hinzu
    $this->addToInfobox('Kategorie', 'Inhalt', 'icon.png');
    $this->addToInfobox('Info', '<strong>HTML</strong> erlaubt');
}
[Code herunterladen]

Werden mehrere Einträge zu einer Kategorie hinzugefügt, so werden diese gruppiert in der Reihenfolge des Hinzufügens angezeigt.

5. Die View

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

5.1 Infobox

app/views/example/asite/index.php

  1. // Füllt man die Variable $infobox, so erhält man eine Infobox
  2.  
  3. $infobox['picture'] = 'modules.jpg';        // Das Bild der Infobox
  4.  
  5. $infobox['content'] = array(                // Die Elemente der Infobox
  6.     array(
  7.         'kategorie' => _('Informationen:'),
  8.         'eintrag'   => array(
  9.             array('icon' => 'ausruf_small.gif', 'text' => _('Diese Einträge erhält man durch Füllen der Variable $infobox in einem Template (einer View)')),
  10.             array('icon' => 'link_intern.gif',  'text' => 'Man kann natürlich auch mehrere Einträge haben.')
  11.         )
  12.     )
  13. );
[Code herunterladen]

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.

5.2 Variablenzugriff und Partials

  1. // Ausgeben der im Controller gesetzten Variable
  2. var_dump($daten);
  3. ?>
  4.  
  5. <!-- Ein wenig Text/HTML -->
  6. <b>Huhu</b>
  7.  
  8. <!-- Ein partial-Template -->
  9. <?= $this->render_partial('example/asite/_feedback'); ?>
[Code herunterladen]

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.

$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 <?=.

5.3 URLs zu Aktionen in Controllern

  1. <br>
  2. So erhält man einen Pfad zu einem Controller:<br>
  3. $controller->url_for('example/asite/backendwithmessage');<br>
  4. <br>
  5. <a href="<?= $controller->url_for('example/asite/backendwithmessage') ?>"><button>Ausprobieren</button></a>
[Code herunterladen]

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

5.4 Zugriff auf persistente Werte im Template

app/views/example/asite/_feedback.php

  1. if ($flash['nachricht']['message']) {
  2.     foreach ($flash['nachricht']['message'] as $nachricht) {
  3.         echo MessageBox::info($nachricht);
  4.     }
  5. }
[Code herunterladen]

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.

0 Kommentare (zeigen/schreiben)

Letzte Änderung am 03.03.2012 19:27 Uhr von tleilax.

Hilfe?!

Hier finden Sie Entwickler-Dokumentation für Stud.IP.

Hilfe zur Bedienung und Administration von Stud.IP finden Sie im Dokumentations-Portal.

Entwickler-Doku

Spielregeln

Weitere Themen

Plugins

Spezielle Klassen

(c) Stud.IP e.V. und die Autoren der Stud.IP-Dokumentation.
Dieser Text ist unter der Lizenz "Creative commons Attribution/Share Alike" verfügbar.