Trails

Trails für die Kernentwicklung.

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

Achtung: Die folgende Dokumentation bezieht sich auf die Verwendung von Trails für die Stud.IP-Kernentwicklung. Für die Verwendung von Trails in Plugins lesen Sie bitte Trails in Plugins.

1.  Trails & Stud.IP-Kern

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. Ab Stud.IP Version 2.5 werden Models aus 'app/models' automatisch geladen.

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 {

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

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

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

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

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

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

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

5.  Die View

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

5.1  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'); ?>

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

Zu beachten ist, dass $controller->link_for('path_to_action') an den Stellen genutzt werden sollte, wo ein Link ausgegeben wird und $controller->url_for('path_to_action') an den Stellen, wo die URL noch von einer weiteren API verwendet wird.

Ab Stud.IP 4.3 können Links zu Controller-Aktionen auch dadurch erzeugt werden, indem man $controller->action(<parameter>) aufruft. Der Pfad zum Controller und der Controller selbst müssen somit nicht mehr angegeben. Eine entsprechende URL erhält man durch das Anhängen von URL an die aufgerufene Methode: $controller->actionURL($parameter);

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

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.

6.  Trails und SimpleORMap (ab Stud.IP 4.3)

Ab Stud.IP 4.3 sind Trails und SimpleORMap etwas näher miteinander verknüpft. Als Parameter von link_for() und url_for() bzw. den kurzen action() bzw. actionURL()@@ Aufrufen können direkt die SimpleORMap-Objekte übergeben werden, wodurch ihre Id als Parameter genutzt wird:

  1. $controller->link_for('controller/edit', $sorm);
  2. // bzw.
  3. $controller->edit($sorm);

Die Parameter der Action am Controller können ebenfalls direkt SimpleORMap-Objekte zurückgeben, indem sie einen entsprechenden Typehint erhalten. In dem Fall wird die übergebene Id genutzt, um das Objekt zu laden. Solange der entsprechende Parameter nicht optional ist (= null), wird SimpleORMap::find() verwendet, um das Objekt zu laden. Ist das Objekt als optional markiert, wird das Objekt mittels new SORM($id); erzeugt.

Über die Eigenschaft _autobind am Controller kann gesteuert werden, ob die derart erzeugten Objekte auch automatisch mittels des Namens des Parameters an den View gebunden werden, damit sie dort auch verfügbar sind.

Ein Beispiel hierfür:

  1. # Controller
  2.  
  3.     protected $_autobind = true;
  4.  
  5.     // ...
  6.  
  7.     public function edit_action(SORM $sorm)
  8.     {
  9.     }
  10.  
  11. # View
  12.  
  13. <label>
  14.     <?= _('Titel') ?>
  15.    <input type="text" name="title" value="<?= htmlReady($sorm->title) ?>">
  16. </label>

Letzte Änderung am January 15, 2019, at 06:12 PM von tleilax.