Formate

Einleitung

Formate sind dynamische Ausgabe-Templates die in der Programmiersprache PHP erstellt werden und auf einer Seite letztendlich HTML erzeugen. Zum grundsätzlichen Verständnis was Formate sind, empfehlen wir zuerst den Artikel Formate - die Grundlagen zu lesen.

Um Formate optimal selbst programmieren zu können, werden Kenntnisse in PHP und HTML empfohlen.

 

Daten und Parameter

Formate können von außen erhaltene Daten und Parameter übergeben bekommen und verarbeiten. Im Normalfall geschieht dies über entsprechend erstellte Platzhalterkonfigurationen. Das eCMS reicht die Daten oder Parameter entsprechend weiter, so dass Sie bei der Programmierung von Formaten zur Verfügung stehen.

 

Format-Object

Format-Objects sind von der Basisklasse ecms_formatObj abgeleitete PHP-Klassen. Der Klassen Namen wird als Format-Label verwendet und den Format-Label wird das Format innerhalb des eCMS adressiert. Die Formate werden auf der Festplatte speichert und liegen im Site Include-Verzeichnis "site_inc" im "lib_formatobject". Der Dateiname hat den folgenden Syntax:

  1. <format_label>.class.php

Der einfachste Weg ein neues Format zu erstellen ist über den eCMS-Admin unter Komponenten > Formate.

Daten und Parameter

Übergebene Daten stehen Ihnen im Methodenparameter der Methode generateContent unter dem Array-Schlüssel $params['data'] zur Verfügung. Auf die dem Format-Object übergebene Parameter können Sie über den Pointer $this->params zugreifen.

Standard-Methoden

Ein Format-Object kann auf Standard-Methoden der Basisklasse zugreifen. Die wichtigstens Methoden sind __construct, generateContent , frm_catch und cmd_catch. Wenn Sie AJAX Anwendungen erstellen wollen, stehen Ihnen in der Basisklasse unter anderem die Methoden ajax_getActionURL und ajax_catchAction zur Verfügung.

__construct

Dies ist der Konstruktor der Klasse, der in einem Format-Object entsprechend überschrieben werden kann. Die Basisklasse ecms_formatObj erzeugt hier diverse Pointer auf Objekte.

generateContent

Diese Methode erhält die eigentliche Ausgabe des Format-Objects. Sie muss in jedem Format-Object geschrieben werden, um eine Ausgabe auf der Website erzeugen zu können. Im Normalfall wird hier HTML erzeugt, welches beim Laden der Seite entsprechend ausgeliefert und dargestellt wird.

Die Rückgabe der Methode ist ein Array. Nachfolgend ist die Struktur des Rückgabe-Array beschrieben:

  1. <?php
  2. [...]
  3. // Rückgabe-Array
  4. $R['src'] = '<!-- Your HTML content --> '; // Das HTML was ausgegeben werden soll.
  5. $R['status'] = true; // Status-Flag, im Normalfall auf <em>true </em>gesetzt
  6. $R['cache']['cacheable'] = true; // Cache-Aktivierung mit dem Wert <em>true</em> oder Deaktivierung mit <em>false</em>
  7. return $R;
  8. [...]
  9. ?>

frm_catch

Wenn Sie ein Formular programmieren wollen, wird diese Methode bei einem Submit des Formulares automatisch aufgerufen. Hier können Formularvalidierungen und Aktionen ausgeführt werden, die nach dem Absenden des Formulares ausgeführt werden sollen.

cmd_catch

Die Methode wird zur Verarbeitung von GET-Kommandos verwendet. Sie wird angesteuert, wenn der Benutzer einen entsprechend konfigurierten Link angeklickt hat. Zur Erzeugung dieses Links benötigen Sie die Methode cmd_buildLink.

ajax_getActionURL & ajax_catchAction

Wenn diesen Methoden können Sie AJAX-Urls erzeugen und entsprechend verarbeiten. Diese sind hilfreich wenn Sie AJAX Ausgaben programmieren wollen.

Weitere Informationen, wie Sie AJAX im eCMS nutzen können erfahren Sie unter: AJAX im eCMS.

Beispiele

Beispiel 1: Ein einfaches Format-Object ist zum Beispiel die Ausgabe eines Textes, den ein Benutzer in einem einfachen Formular einträgt:

  1. class mein_text_formular extends ecms_formatObj
  2. {
  3.       public $mytext;
  4.  
  5.       /**
  6.        * Konstruktor
  7.        */
  8.       public function __construct($params)
  9.      {
  10.          parent::__construct($params);
  11.      }
  12.  
  13.       /**
  14.        * GenerateContent - Format-Ausgabe
  15.        */
  16.       public function generateContent ($params)
  17.      {
  18.           $S = '';
  19.  
  20.           if (!empty($this->myText)){
  21.               // Text in Variable gefunden, Ausgabe des Textes
  22.               // Achtung: In diesem Beispiel erfolgt keine Sicherheitsausgabe (Entfernen von "schädlichem Code", etc)
  23.               $S = '<div class="meintext">'.$this->myText.'</div>';
  24.           }
  25.  
  26.           $S .= '<div class="meinformular">
  27.                          ${eCMS-FORM}$
  28.                               ${eCMS-INPUT-TEXT:meintext}$ ${eCMS-INPUT-SUBMIT:absenden}$
  29.                          </form>
  30.                     </div>';
  31.  
  32.            $R['src'] = $S;
  33.            $R['status'] = true;
  34.            $R['cache']['cacheable'] = false;
  35.            return $R;
  36.      }
  37.  
  38.     
  39.       /**
  40.        * Formularverarbeitung
  41.        */
  42.       public function frm_catch($params)
  43.      {
  44.          if (isset($params['absenden']) || isset($params['absenden_x'])){
  45.                // Button "absenden" geklickt. speichern des Inhalt des Text-Inputs auf Variable
  46.                $this->myText = $params['meintext'];
  47.          }
  48.      }
  49. }

Beispiel 2: Sie haben eine Datenabfrage Daten an das Format-Object übergeben. Bei den Daten handelt es sich um einen einfachen Datensatz bestehend aus den Schlüsseln firstname und lastname mit entsprechenden Werten. Sie wollen diese Daten ausgeben und haben zur Hervorhebung noch den im Format-Object unterstützten Parameter style gesetzt.

  1. class meine_datenausgabe extends ecms_formatObj
  2. {
  3.       /**
  4.        * Konstruktor
  5.        */
  6.       public function __construct($params)
  7.      {
  8.          parent::__construct($params);
  9.      }
  10.  
  11.       /**
  12.        * GenerateContent - Format-Ausgabe
  13.        */
  14.       public function generateContent ($params)
  15.      {
  16.           $S = '';
  17.  
  18.           if (is_array($params['data']) && count($params['data'])>0){
  19.               // Daten in $params['data'] sind wahrscheinlich vorhanden
  20.               // Style-Wert findet sich in den Parametern wieder, also kann über $this->params['style'] darauf zugegriffen werden.
  21.  
  22.               $S = '<div class="name" style="'.$this->params['style'].'">Name: '.$params['data']['firstname'].' '.$params['data']['lastname'].'</div>';
  23.           }
  24.  
  25.            $R['src'] = $S;
  26.            $R['status'] = true;
  27.            // Die Ausgabe soll in den eCMS Cache geschrieben werden, wenn dieser aktiviert ist
  28.            $R['cache']['cacheable'] = true;
  29.            return $R;
  30.      }
  31. }