Anleitung eigenes Modul für Xentral

In dieser Anleitung wird beschrieben wie man eigene Module für Xentral programmiert. Grundstruktur Jedes Modul besteht aus mindestens einer .php Datei und passenden Templates. Die Struktur bzw. der Aufbau der .php Datei ist vorgegeben. Ein zusammenhängendes Beispiel findet man in Xentral (vorlage.php). Die .php Datei ist immer im Ordner www/pages. Der Name der Datei entspricht dem Modulnamen. Die Templates findet man im Ordner www/pages/content. Beispiel:
Beschreibung Name
PHP Datei meinmodul.php Alle Buchstaben klein
Klassenname in PHP Datei class Meinmodul Erster Buchstabe muss groß geschrieben sein, der Rest klein
Template für das Action list meinmodul_list.tpl Passendes Template für das Action list
Template für das Action edit meinmodul_edit.tpl Passendes Template für das Action edit
Wichtig ist, dass man sich an diese Namenskonventionen hält, da das Framework basierend auf diesen Namen automatisch die Module laden kann, bzw. z.B. auch das Rechtesystem automatisch die Actions erkennen kann.

Module vs. Action

Der Name der App, bzw. das Modul oder einfach gesagt die .php Datei heißt in Xentral Modul. In der Datei findet man alles was zu einem Modul bzw. einer App gehört. Um in Xentral als Oberfläche aufzutauchen, muss man als Benutzer die entsprechenden Rechte haben. Damit Xentral weiß was ein Benutzer aufrufen darf, schreibt man für einzelne Unteroberflächen oder Aktionen eigene “Actions”. Wie man diese aufteilt ist einem prinzipiell selbst überlassen. Man muss nur wissen, dass in der Rechteverwaltung diese Actions einem Benutzer von den Rechten her gegeben werden kann oder nicht. Typische Actions sind
"action" Beschreibung Weitere Infos
list Anzeige der Haupttabelle des Moduls Z.B. Übersicht über Angebote, Aufträge, Artikel, Spezialabrechnungen etc.
edit Bearbeiten eines Haupteintrages
create Anlegen eines Haupteintrages
delete Löschen eines Haupteintrages
Wenn möglich sollte man sich immer an diese Konvention halten. Es ist z.B. so dass “list” automatisch versucht wird zu starten, wenn das Modul ohne Action aufgerufen wird. Der Aufruf der Module mit den passenden Actions kann über die URL geschehen. index.php?module=meinmodul&action=list Als weitere Besonderheit ist zu beachten, dass als GET Parameter aktuell meist nur id für die Übergabe des Primärschlüssels für den aktuellen Datensatz und cmd für die Übergabe eines “Unterkommandos für das Action” wenn notwendig zu verwenden sind. Alle weiteren Parameter werden als POST übergeben.

Grundaufbau Modul Datei und Templates

Eine Datei sieht minimal so aus:
<?php
//WAWIFILEONLYON VERSION=ALL


class Meinmodul {
  var $app;


  function __construct(&$app, $intern = false) {
    $this->app=&$app;
    if($intern)return;
    $this->app->ActionHandlerInit($this);


    // ab hier alle Action Handler definieren die das Modul hat
    $this->app->ActionHandler("list", "MeinmodulList");
    $this->app->ActionHandler("create", "MeinmodulCreate");
    $this->app->ActionHandler("edit", "MeinmodulEdit");
   
    $this->app->ActionHandlerListen($app);
  }




  function MeinmodulList()
  {
    $this->app->Tpl->Parse("PAGE","existenzgruender_list.tpl");
  }
Passend das Template in www/pages/content/meinmodul_list.tpl
<!-- WAWIFILEONLYON VERSION=ALL -->
<!-- gehort zu tabview -->
<div id="tabs">
    <ul>
        <li><a href="#tabs-1">Test</a></li>
    </ul>
<!-- ende gehort zu tabview -->


<!-- erstes tab -->
<div id="tabs-1">
[MESSAGE]
[TAB1]
[TAB1NEXT]
</div>


<!-- tab view schließen -->
</div>
Im Konstruktor sieht man die Definition der ActionHandler. Das sind die einzelnen Unteroberflächen wenn man so möchte. Xentral erlaubt den Aufruf nur, wenn der Benutzer die entsprechenden Rechte hat. D.h. man muss sich nicht als Entwickler darum kümmern ob der Benutzer das aktuell darf oder nicht, da sich darum das Framework selbständig kümmert. Jedes Action muss im Konstruktor registriert werden.
$this->app->ActionHandler("edit", "MeinmodulEdit");
Im ersten Parameter steht der Name, der über index.php?module=meinmodul&action=edit angegeben wird. Im zweiten Parameter ist der lokale Methodenname. D.h. in dieser Datei muss es eine Methode MeinmodulEdit geben, die dann automatisch aufgerufen wird.
function MeinmodulEdit()
{
}

Templates

Für die Ausgabe von Oberflächen gibt es ein Templatesystem. Im wesentlichen sind diese .tpl Dateien die HTML Stücke bzw. Teiloberflächen die Xentral übergeben werden damit der Benutzer seine Oberflächen sieht. In der PHP Datei sollten keine kompletten HTML Strukturen stehen, sondern nur Inhalte die in das Template gefüllt werden. Muss eine spezielle Tabelle in PHP erstellt werden (wobei man wissen muss, dass es Mechanismen für Tabellen in Xentral gibt) wäre es in Ordnung wenn man maximal die Tabelleninhalte per PHP (also die <tr> und <td> Tags) erstellt. Aber mehr sollte es eigentlich nicht sein. Alles andere kann direkt in die .tpl Datei. Inhalte kommen in die .tpl Datei immer über Templatevariablen. Das sind in eckigen Klammern komplett groß geschriebene Variablen z.B. [DATUM], [STRASSE], [FORMVAL1_ADRESSE] Diese Werte im Template kann man mit den beiden Methoden Set und Add füllen. Mit Set wird der komplette Inhalt der Variable überschrieben. Mit Add bleibt der bestehende Inhalt, der zuvor mit Set oder Add definiert worden ist, bestehen und wird entsprechend hinten angehängt. Beispiele:
$this->app->Tpl->Set("NAME", $name_aus_db);
$this->app->Tpl->Add("NAME","Hans");
Der komplette Inhalt eines Templates kann wiederum einer Templatevariable übergeben werden. So kann man z.B. die Oberfläche eines ActionHandlers an Xentral übergeben in dem man das Template nach [PAGE] ausgibt. Am Ende des ActionHandler findet man daher meist so eine Zeile
$this->app->Tpl->Parse("PAGE","meinmodul_list.tpl");
D.h. es wird das Template mit den gesamten zuvor gefüllten Variablen in die neue Variable PAGE geschrieben. Xentral gibt diese später wenn man die notwendigen Rechte etc. hat aus.
$output = $this->app->Tpl->Output("meinmodul_list.tpl);
git das Template direkt in die Varibale $output aus. 

Zugriff auf Datenbank, Formularvariablen und Benutzersession

Im folgenden wird beschrieben wie Standardfunktionen mit Xentral abgebildet werden. Alle Module sollten nach diesem Schema entwickelt werden.

Datenbank

Auf die Datenbank greift man mit Xentral über das Modul $this->app->DB zu. Hier gibt es verschieden Methoden. Man sollte immer diese verwenden und nicht mit anderen zugreifen. Um z.B. an die Adressdaten einer Adresse zu kommen kann man die Methode SelectArr verwenden: $this->app->DB->SelectArr("SELECT * FROM ..."); gibt ein zweitdimensionales Array aus $this->app->DB->Select("SELECT nummer FROM artikel WHERE id = '$id' LIMIT 1");gibt ein einzelnen Wert aus, falls sich genau eine Spalte und eine Zeile aus dem Query ergibt. Sonst ein Array Abfrage ohne direkte Ausgabe
$query = $this->app->DB->Query("SELECT * FROM artikel WHERE projekt = '$projekt'");
Holen der nächsten Zeile aus dem Query
$row = $this->app->DB->Fetch_Array($query);
Freigeben der Resource
$this->app->DB->free($query);
Datensätze hinzufügen:
$this->app->DB->Insert("INSERT INTO artikel (nummer, name_de) VALUES ('10000','Beispielartikel');
Holen der Datensatz-Id nach dem Insert
$id = $this->app->DB->GetInsertID();
Um einen Datensatz zu ändern:
$this->app->DB->Update("UPDATE artikel SET projekt = '1' WHERE id = '$id'");

Formularvariablen

Auf Variablen eines Formularsgreift man immer über das Modul Secure zu. Das stellt unter anderem sicher, dass die Inhalte keine SQL Injection oder ähnliches enthalten. Man darf in Xentral nie direkt auf $_GET und $_POST zugreifen. Beispiele:

Benutzersession

Oft muss man wissen, welcher Benutzer aktuell etwas durchführt weil z.B. bei der eigenen Zeiterfassung die Datensätze mit der eigenen ID verknüpft gehört, oder allgemein wenn etwas benutzerspezifisch durchgeführt oder gespeichert werden soll.

DatePicker, AutoComplete, Live-Tabellen, etc.

Für viele Standardwidgets gibt es in Xentral fertige Mechanismen.
DatePicker
Ein DatePicker kann einfach aktiviert werden: $this->app->YUI->DatePicker("datum");
<input type="text" id="datum" name="datum">
AutoComplete
Oft gibt es in Xentral Felder bei denen man lostippt und dann weitere Sachen vorgeschlagen werden. Das ist z.B. ein AutoComplete
LiveTabelle
Verfügbare Variablen $heading $heading ist ein Array mit den Tabellenüberschriften
$heading = array ('Beleg-Nr','Kundennummer','Kunde','Umsatz','Men&uuml;');
$width gibt die Breiten der Spalten in % an.
$width = array('20%','20%','29%','10','1%');
$findcols Für jede Spalte muss der Sortierungsaudruck angeben
$findcols = array('a.belegnr','adr.kundennummer','adr.name','a.umsatz_netto','a.id');
$searchsqlGibt die Spalten / Ausdrücke in der gesucht werden kann.
$searchsql = array('a.belegnr', 'adr.kundennummer','adr.name','adr.ort');
$defaultorderGibt die Spalte an nach der Standardmäßig sortiert werden soll (Zählung beginnt ab 1).
$defaultorder = 5;//Sortierung nach id
$defaultorderdescGibt an ob die Standardsortierung aufsteigend (0) oder absteigend (1) erfolgen soll.
$defaultorderdesc = 1; //Absteigend sortiert
$sqlEnthält das SQL-Query mit Spalten und FROM-Anteil, allerdings ohne WHERE, GROUP BY, SORT oder LIMIT
$sql = "SELECT SQL_CALC_FOUND_ROWS a.id,a.belegnr, adr.kundennummer,a.name,format(a.umsatz_netto,2) , a.id
FROM auftrag a 
LEFT JOIN adresse adr ON a.adresse = a.id"
$whereEnthält die Bestandteile der WHERE abfrage ohne das Schlüsselwort WHERE
$where = "a.status != 'angelegt'";
$countGibt das komplette Query an, dass die Anzahl der Datensätze zurückgibt.
$count = "SELECT count(id) FROM auftrag WHERE status != 'angelegt'";
$menucolGibt die Position der Menüspalte an. Dies ist notwendig falls Minidetails eingebunden werden.
$menucol = 5;
$alignrightSollen Spalten rechtsbündig angezeigt werden (z.B. bei Beträgen), kann dies in der Variable $alignright angegben werden. Dies geschieht in einem Array mit den Spaltennummern als Elemente.
$alignright = array(4); //Umsatzspalte wird rechtsbündig
$sumcolEs kann eine Summierung der angezeigen Datensätze angezeigt werden im Footer der Tabelle
$sumcol = 4;
die Umsätze werden summiert angzeigt.Ab Xentral 16.4 kann dies auch als array geschrieben werden, falls mehrere Spalten summiert werden.

Benutzerrechte für Module

Xentral zieht automatisch aus dem ActionHandler Informationen im Konstruktor, die Infos für die Rechteverwaltung. Inkl. Screenshot das man es grob

Abfrage der Benutzerrechte im Quellcode

Im Code kann geprüft werden ob der aktuelle Benutzer die Rechte für ein Action hat. Administratoren haben grundsätzlich alle Rechte.
if($this->app->erp->RechteVorhanden('auftrag','edit'))
{
  //Benutzer darf Aufträge editieren
}

Überladen von Wdigets (ab 16.4)

Um ein Widget zu erweitern, muss das Originalwidget inlcludiert werden und die Original-Klasse mit einem Custom angehängt überladen werden.Beispiel Auftragwidget:
<?php
include_once ("widget.auftrag.php");

class WidgetAuftragCustom extends WidgetAuftrag 
{
...

Debugging

Um das Programmieren zu vereinfachen kann in www/index.php die Zeile 'error_reporting(E_ERROR);' zu 'error_reporting(E_ALL);' geändert werden. Dadurch werden Syntaxfehler nicht mehr vom Parser verschluckt. Allerdings sollte die Option wieder auf den ursprünglichen Status zurückgesetzt werden wenn sie nicht mehr gebraucht wird, da unter Umständen sensible Daten ausgegeben werden können.

FAQs

War der Artikel hilfreich?
Vielen Dank für Ihr Feedback!

Made with ❤ at zwetschke.de