Model und Controller

Die Funktionen von access.php sind für das Ein- und Auslesen der Daten verantwortlich. Dafür werden zwei assoziative Arrays benötigt. Das erste bestimmt grundsätzliche Anweisungen für Tabelle und Formular, das zweite definiert die Datentypen für Eingabefelder und Datenausgabe.

Die Funktionen sind modular ausgelegt, sodass unterschiedliche Abläufe des Controllers möglich werden.

Damit ist abgedeckt:

  • Tabellarische Übersicht von Datensätzen
  • Suchfunktion
  • Eingabemasken
  • Speichern, Bearbeiten, Löschen
  •  Ausgabe von Daten

Die Funktionen im Überblick

$obj = new access($form)

Initialsierung eines Access-Objektes $obj mit den Formular- und Tabellenvorgaben $form.

$obj->add_input($inputs)

Übergibt die Eingabefelder-Daten $inputs an das Objekt in Vorbereitung auf $obj->form().

$html = $obj->form()

Aufruf für das Formular. $html ist für die Klasse gui mit dem Eingabe-Formular vorbereitet.

$html = $obj->table($inputs)

Aufruf für die Übersichtstabelle und Suchfunktion. $html ist für die Klasse gui mit der Tabelle vorbereitet.

$inputs = $obj->get_params($inputs)

Nach Absenden des Formulars werden die Eingaben in Vorbereitung von $obj->store($inputs) überprüft.

$inputs = $obj->sanitize($inputs)

Bei öffentlichen Formularen ist es ratsam, nach $inputs = $obj->get_params($inputs) mit dieser Funktion die Eingabedaten von allfälligen Exploit-Versuchen zu reinigen (SQL-Injection, Cross-Site-Scripting).

$id = $obj->store($inputs)

Die Eingaben werden gespeichert. Die ID des neuen Datensatzes wird zurückgegeben.

$inputs = $obj->get_value($inputs)

Die Daten eines bestehenden Datensatzes werden in Vorbereitung für $obj->form() ausgelesen. Der Wert ist nun gegebenenfalls in inputs['Datenfeld']['value'] zu finden.

get_multiple_values($input)

Mit dieser Funktion werden alle Daten mit der ID oder den IDs von $obj->rid uninterpretiert als Wertepaare ausgegeben. Die Funktion ist vorallem nützlich, wenn man vor dem Löschen eines oder mehrerer Datesätze noch Informationen zur weiteren Verarbeitung braucht.

$inputs = $obj->data_ref($inputs)

Die Daten eines bestehenden Datensatzes werden nach get_value() ausgelesen und im Gegensatz zu get_value() interpretiert (z.B. Wert des Arrays oder Lookups) ausgegeben. Der Wert ist nun in inputs['Datenfeld']['value'] zu finden. inputs['Datenfeld']['orig_val'] enthält den originalen Wert wie bei get_value().

$data = $obj->parsable_data($input)

Ähnlich wie oben, die Daten können nun aber zum Parsen in eine HTML-Vorlage oder -Schnippsel verwendet werden. $data['key'] ist nun der ausgebene Wert, $data['key_orig_val'] der Originalwert und $data['key_orig_capt'] die Bezeichnung des Felds.

$text = $obj->input2text($input)

Nach  $obj->get_params($inputs) oder $obj-> get_value($inputs) werden die Wertepaare als Text zurückgegeben.

$html['content'] = $obj->ask()

Gibt einen HTML-Dialog aus, ob ein oder mehrere bestimmte Datensätze gelöscht werden sollen.

$obj->delete()

Löscht einen oder mehrere Datensätze.

$obj->html_in($html);

Manchmal ist es notwendig, Veränderungen von $html wieder in das Objekt zu übertragen.

Variablen

$int = $obj->error

Frage, ob nach $obj->get_value($inputs) oder $obj->get_params($inputs) ein Fehler vorliegt, ergibt 1 (Fehler) oder 0 (kein Fehler).

$int = $obj->rows

Gibt die Anzahl der Treffer nach $obj->table($inputs) aus.

$feedback = $obj->feedback

Gibt den Feedback-Kommentar aus. Kann je nach Sinnhaftigkeit in $html['feedback'], $html['content'] oder $html['popup'] geschrieben werden.

$query = $obj->query

Gibt für Entwicklungszwecke nach form() und table() den verwendeten SQL-Befehl aus.

$script = $obj->scripts

Zugriff auf Javascript. Wird in der Regel nicht benötigt, da obj->form() und obj->table() diesen mitliefert.

$table_rows = $obj->table_rows

Zugriff auf die Daten der ausgegeben Tabelle nach $obj->table($inputs). Diese können nun Zeile für Zeile beliebig dargestellt werden. Zum Beispiel gibt $table_rows[0]['Datenfeld'] den ersten Wert des Feldes 'Datenfeld' aus.

$data = $obj->stored

Nach $obj->store($inputs) werden mit $obj->stored die soeben gespeicherten Daten als Wertepaar ähnlich wie bei get_value() ausgegeben. Damit können die Daten ohne neuerlichem Auslesen weiterverarbeitet werden.

$searchform = $obj->searchform

Gibt das Suchfeld nach $obj->table($inputs) aus. Wird in der Regel nicht benötigt, da obj->table() dieses mitliefert.

Angaben für die Formular- und Tabellenstruktur

Die Angaben betreffen sämtliche Aspekte des Datenzugriffs und der Darstellung der Datentabelle und des Eingabeformulars.

Beispiel:

$form = [ "title" => i18n("foo"), "table" => "foo", "myconf" => "foo", "human" => "foo", "html" => $html, "rid" => $rid, "table_fields" => ["foo1", "foo2", "foo3", ...] ];

wobei $html, das HTML-Objekt des GUIs ist und $rid der aktuelle Parameter der Datensatz-ID.

Angaben:

notwendige Angaben:

  • title: Bezeichnung des Formulars
  • table: Name der MySQL-Tabelle
  • myconf: Name des Aufrufs
  • human: Name des MySQL-Felds, das zur menschlichen Identifikation dient
  • html: Übergabe des HTML-Objektes $html
  • rid: Übergabe der aktuellen Datensatz-ID
  • table_fields: Array der Datenfelder, die in der Tabelle aufscheinen sollen

zusätzliche Angaben:

  • method: Übertragungsart, "post" (Standard) oder „get“
  • enctype: Übertragungstyp; Standard: "multipart/form-data"
  • name: Name-Tag des Formulars; Standard: "table"
  • action: Action-Tag des Formulars; Standard: "index.php"
  • primary: ID-Feld der Tabelle; Standard: "id"
  • view: Typ der Tabelle: Tabellenansicht "table" (Standard) oder „tiles“ für Kachelansicht
  • no_edit: Array mit ID's von Datensätzen, die nicht bearbeitet werden dürfen
  • no_del: Array mit ID's von Datensätzen, die nicht gelöscht werden dürfen
  • no_logical: 1 unterbindet und-oder-Auswahl im Suchfeld; Standard ist 0
  • search: Name der MySQL-Datenfelder, in denen wahlweise gesucht werden kann. „fulltext“ ist das Schlüsselwort für eine Suche in den als „FULLTEXT“ definierten Datenfeldern
  • searchform: auf 0 setzen, wenn kein Suchfeld aufscheinen soll; Standard 1
  • orderby: Feldname, nach dem sortiert wird, Standard id
  • defsort: ASC oder DESC, Standard: ASC
  • q_limit: Anzahl der angezeigten Datensätzen pro Seite; Standard ist 20;
  • q_limit2: Anzahl der zugleich anwählbaren Seiten in Offset-Navigation; Standard ist 20;
  • button_text: Text des Absende-Buttons; Standard: "save" (multilingual);
  • autocomplete: 0 setzt die autocomplete-Funktion außer Kraft, Standard: 1
  • maxsize: maximale Ausgabelänge eines Textes in Tabellensicht; Standard: 40;
  • defsize: maximale Länge des Eingabefeldes (einzeiliges Textfeld); Standard: 40;
  • before_form: Text oder HTML vor dem Formular
  • in_form: Text oder HTML im Formular
  • after_form: Text oder HTML nach dem Formular
  • in_searchform: Text oder HTML im Suchformular
  • no_cancel: falls 1 wird kein Abbrechen-Button angezeigt; Standard 0;
  • no_af: falls 1 wird kein Autofokus auf das erste Feld gesetzt angezeigt; Standard 0;
  • button_before: Text oder HTML vor den Buttons
  • button_after: Text oder HTML nach den Buttons
  • wrap_class: CSS-Klasse für das DIV, das die Tabelle umschließt, wrap_class => 'list' umgibt die Tabelle mit einem scrollbaren Element, das die Übersicht von Tabellen mit vielen Datenfeldern erleichtert. Standard: leer;
  • submit: Name des Submit-Feldes; Standard "_store";
  • prefer_new = 0;
  • before_table: Text oder HTML vor der Tabelle;
  • no_action: true = Keine Aktionen wie edit, delete, etc.; Standard false
  • allow_edit: Editieren von Datensätzen erlauben, unterbinden oder den Aufruf durch eine Funktion manipulieren. (true/false/Name einer Funktion); Standard: true;
  • allow_del: Löschen von Datensätzen erlauben oder unterbinde (true/false); Standard: true;
  • allow_something: Eine beliebige Funktion "allow_something" => foo ruft eine mit $todo '_foo' aufrufbare Funktion innerhalb des Skripts auf, falls foo.png existiert, wird dieser Icon verwendet.
    Als Array: "allow_something" => [foo, icon, text]
    Standard: false;
  • allow_sort: Sortieren von sort-Feldern; Standard: false;
  • allow_box: Auswahlbox erlauben
    • "del" für mehrfaches Löschen,
    • "attr": für das mehrfache Setzen von Attributen;
    • "both": beides
    • "": keines
    • Standard: del;
  • attr_to_set: Array mit Datenfeldern, die für das mehrfache Setzen von Attributen bestimmt sind
  • clause: zusätzlich SQL-Bedingung ohne „WHERE“
  • table_sums: zweidimensionales Array, das die Summe einer Tabelle zurückgibt:
    "table_sums" => ['amount' => 0, 'price' = 0]; Die Summe ist danach für Datenfeld price mit $obj->table_sums['price'] auslesbar.

Angaben für Eingabefelder

Die Angaben beziehen sich auf die Art des Datenfeldes und die Definitionen des Eingabefeldes.

Beispiel

$inputs = [
	"foo"	=> ["type" => "text", "duty" => 1 ],
	"foo2"	=> [ "type" => "number", "default" => 10, "duty" => 1 ],
	... 
	]

In diesem Fall werden zwei Datenfelder definiert, die in der Datenbank mit Feldnamen foo1 und foo2 angegeben sind. Das Formular berücksichtigt die hier vorgegebene Reihenfolge.

notwendige Angaben

type: gibt den Datentyp und somit Eingabetyp an; siehe unten

zusätzliche Angaben allgemein

  • caption: Bezeichnung des Datenfeldes, Beispiele:
    "caption" => "Mein Feld"
    "caption" => i18n('my_field')
    Standard: i18n(Feldname)
  • size: Länge des einzeiligen Eingabefeldes abweichend von "defsize"
  • duty: 1: Eingabe muss erfolgen, 0 Eingabe ist optional; Standard: 0
  • abbr: Kurzbezeichnung des Datenfeldes für Tabellensicht
  • html_in_table => true: erlaubt HTML-Codierung von WYSIWYG-Daten in der Tabelle, (oder den Daten der Tabelle für eigene Views)
  • default: Standardwert des Eingabefeldes (wird bei neuem Datensatz eingesetzt)
  • css_class: zusätzliche CSS-Klasse, um das Styling des Eingabefeldes bei Bedarf zu verändern.
  • css_label: zusätzliche CSS-Klasse, um das Styling des Label-Feldes bei Bedarf zu verändern.
  • in_label: Text oder HTML der nach dem Label aufscheint
  • in_body: Text oder HTML der nach dem Eingabefeld aufscheint
  • pattern: ein Muster, um Zahlen in der Tabellensicht zu formatieren
    Beispiel "pattern" => "%05d" macht aus "45" "00045"

Dazu kommen Angaben die Datentyp-spezifisch sind, siehe unten.

Datentypen

text

einfaches einzeiliges Textfeldes

zusätzliches Angabe:

  • "extra" => "url"
    der Text ist eine URL, die aufgerufen werden kann
  • "extra" => "email"
  • der text ist eine E-Mail-Adresse, die als mailto geöffnet werden kann
hidden

ausschließlich für Formular: Wert wird als hidden-input geführt

void

ausschließlich für Formular: das Feld wird ignoriert. Dies kann notwendig sein, falls ein Feld ausschließlich in der Tabellensicht erscheinen soll, jedoch keine Eingabe erfordert.

free

Parameter ohne Zugehörigkeit zu einem Datenfeld, das durch sämtliche Ebenen durch getragen wird und somit für allerlei Zwecke verwendet werden kann.

readonly

ausschließlich für Formular: Datenwert wird angezeigt, ist jedoch nicht editierbar

pwd

Eingabefeld als Passwort

zusätzliches Angabe:

  • "repeat" => true
    erfordert zweifache Angabe des Passwortes etwa bei Neuerstellung oder Änderung.
number

bei diesem Eingabefeld wird eine Zahl erwartet; der Dezimalpunkt wird erzwungen: aus 20,15 wird 20.15

spin

Spin-Feld für ganze Zahlen

zusätzliches Angabe:

  • max => 1000
  • min => 1
  • interval => 50

In diesem Fall ist die Angabe einer Zahl zwischen 1 bis 1000 möglich und ein Klick auf die Auf- und Ab-Pfeilchen bewirkt ein Plus oder Minus von 50. Standard: 100, 1, 1;

bigtext

Die Eingabe wird als Textarea ausgeführt.

zusätzliches Angaben:

  • "cols" => 60
    Das Eingabefeld ist somit 60 Zeichen breit; Standard analog zu defsize (40)
  • "rows" => 20
    Das Eingabefeld ist somit 20 Zeichen hoch; Standard 10
  • "code": Soferne Codemirror implementiert ist, wird aus bigtext ein Editor mit Syntax-Highlighting; Werte: "text/html", "php", "sql", "css", "perl", "javascript" (je nach Implemetierung)
wysiwyg

Eingabe wird mit Editor ermöglicht

  • "cols" => 60
    Das Eingabefeld ist somit 60 Zeichen breit; Standard 80
  • "rows" => 20
    Das Eingabefeld ist somit 20 Zeichen hoch; Standard 25
  • "config" => "small"
    Der Editor ist nun mit weniger (ausschließlich textorientierten) Funktionen bestückt; Standard "normal"
date

Datumseingabe mit Kalender-Assistent. Der Datentyp in der Datenbank sollte "date" sein.

Die Vorgabe für den Standardwert etwa für das aktuelle Datum würde so aussehen: "default" => date('Y-m-d'), für ein bestimmtes Datum: "default" => "1969-02-23"

array

Array gibt ein Auswahlfeld der Werte, die in "extra" eingetragen sind. In der Datenbank wird der Wert 1 für "eins" gespeichert, der Datentyp ist daher TYNIINT, INT... Will man als Standardwert "zwei" haben wird "default" => 2 eingetragen. Ist für mittelgroße Auswahlmöglichkeiten gedacht.

  • "extra" => ["eins", "zwei", "drei"]
    erstellt ein Auswahlfeld (SELECT) mit "eins", "zwei", "drei"
  • "raw" => 1
    In diesem Fall wird nicht 1 für "eins" gespeichert sondern der ursprüngliche Wert "eins", der Datentyp wäre hier VARCHAR.
  • "view" => ["Erste", "Zweite", "Dritte", ...]
    Wenn "raw" gesetzt ist, wird der Wert von "extra" gespeichert jedoch der Wert von "view" angezeigt.
  • "icons" => ["icon1", "icon2", "icon3"...]
    Das Auswahlfeld wird zur besseren Veranschaulichung mit Icons hinterlegt, die im Verzeichnis "icons" als PNG-Datei zu finden sind. In diesem Fall würde icons/icon2.png für den Wert "2" oder "zwei" ausgegeben.
radio

Die Radio-Box ist analog zu Array zu betrachten, wird jedoch als Fieldset mit Radio-Buttons ausgegeben.Ist für kleine Auswahlmöglichkeiten gedacht.

  • "extra" => ["eins", "zwei", "drei"]
    erstellt ein Fieldset mit Radio-Boxen "eins", "zwei", "drei"
  • "cols" => [1..4]
    Darstellung in 1 bis vier Spalten. Standard 4. Spalten sind responsive.
  • "raw" => 1
    In diesem Fall wird nicht 1 für "eins" gespeichert sondern der ursprüngliche Wert "eins", der Datentyp wäre hier VARCHAR.
  • "view" => ["Erste", "Zweite", "Dritte", ...]
    Wenn "raw" gesetzt ist, wird der Wert von "extra" gespeichert jedoch der Wert von "view" angezeigt.
lookup

Mit dem Auswahlfeld Lookup wird ein nummerischer Wert mit der ID einer Lookup-Tabelle verknüpft. Lookup-Tabellen können ebenfalls editierbar sein.

zusätzliches Angaben:

  • "lid": die ID der Vergleichstabelle; Standard: "id"
  • "lval": das Feld, das angezeigt werden soll
  • "tval": das Feld, das in der Tabelle angezeigt werden soll (falls abweichend)
  • "lord": das Feld der Vergleichstabelle, nach dem sortiert werden soll; Standard: "id"
  • "lclause": eine zusätzliche einschränkende SQL-Bedingung für die Tabelle
  • "lgroup": ein zusätzliches Feld, nach dem innerhalb des Auswahlfeldes gruppiert wird (OPTGROUP)

Da Auswahlfelder mit zu hoher Anzahl an OPTION-Felder unbequem sind, wird ab 200 Einträge das Auswahlfeld in ein Autofill-Feld mit Alax-Unterstützung umgewandelt (Type-Ahead). Mit "limit" kann dieser Schwellwert nach belieben verändert werden: "limit" => 1 erzwingt ein Type-Ahead Feld von Anfang an.

multicheck

Mit multicheck ist eine Mehrfachauswahl möglich.

als Lookup:

  • "lid": die ID der Vergleichstabelle; Standard: "id"
  • "lval": das Feld, das angezeigt werden soll
  • "tval": das Feld, das in der Tabelle angezeigt werden soll (falls abweichend)
  • "lord": das Feld der Vergleichstabelle, nach dem sortiert werden soll; Standard: "id"
  • "lclause": eine zusätzliche einschränkende SQL-Bedingung für die Tabelle

als Liste:

"raw" => true

"extra" => ['A','B','C','D']

"row_class" => [class]
Klasse(n) für Spaltenteilung: Standard 'col w3 l4 m6' (vier Spalten Desktop, 3 Spalten Laptop, 2 Spalten Mobile)

icon

Ein Auswahlfeld, das sämtliche PNG Dateien eines bestimmten Verzeichnisses zu Auswahl stellt.

  • "css_class": CSS-Klasse; Standard ist hier "icons"
  • "icon_dir" => relativer Pfad zum Verzeichnis; Standard: "icons"
country

Ein Auswahlfeld aller Staaten nach ISO 3166 mit Flaggen.

Falls eine Abkürzung "abbr" angegeben ist, werden in der Tabelle ausschließlich die Flaggen mit alt- und title-Tag des jeweiligen Staates angezeigt. Als Abkürzung kann auch die Weltkugel als Icon verwendet werden:

"abbr" => get_icon("world", i18n('country')),

image

Ermöglicht die Auswahl eines vorhandenen Bildes sowie das Hochladen einer Bilddatei des Formates JPG, GIF, PNG.

  • "upload": Nur Hochladen, unterbindet Zugriff auf dem Bildassistenten
  • "display": Nur ansehen
  • Standard: keine Angabe Bildassistent und Hochladen
custom

Für spezielle Bedürfnisse sind selten aber doch spezielle Eingaben erforderlich. Mit custom kann unter "extra" beliebiger Code für das Formular und unter "view" beliebiger Code für die Tabellenübersicht eingetragen werden, wobei ++VALUE++ ein Platzhalter für den Wert des Datenfeldes ist.

Würde man etwa ein einfaches Texteingabefeld umständlicherweise als custom erstellen, wäre:

"foo" => [
	"type" => "custom",
	"extra" => "<input name='foo' id='ifoo' value='++VALUE++'/>",
	"view" => "Mein Wert ist: ++VALUE++"
	]

Im Eingabeformular wäre das Endergebnis für "foo" identisch mit type => "text", in der Tabelle würde "Mein Wert ist: XY" stehen.

Für extra als auch für view können Namen von Funktionen übergeben werden:

extra => "foo_func" leitet zu foo_func($value, $field, $rec), wenn diese existiert.

Beispiel:

function foo_func($val, $field, $rec) { if ($rec['somefield'] == 'bar') {
 $input = "<input name='$field' id='i$field' value='$val'/>";
 }
	else {$input = "&nbsp;";}
 	return $input; }

In diesem Beispiel würde nur dann ein Eingabefeld angezeigt, wenn das Datenfeld somefield im aufgerufenen Datensatz den Wert "bar" hat.

fieldset

Kein Eingabefeld sondern eine reine Fieldset-Gruppierung, um Eingaben zu strukturieren. Fieldsets können auch ein- und ausklappbar gestaltet werden.

  • "end": Name des Datenfeldes vor dem das Fieldset ended, es ended automatisch am Ende des Formulars oder vor dem nächsten fieldset-Feld.
  • "collapsed": auf 1 gesetzt wird das Fieldset ausklappbar, Standard: 0;
subform

Mit "subform" wird ein Unterformular zu einer Tabelle hinzugefügt, die mit der Haupttabelle in einer 1:∞ Beziehung steht. Das Unterformular wird als Iframe eingebettet und muss als eigenständiges Plugin oder eigenständiger Plugin-Teil vorhanden sein.

  • 'conf': Die Bezeichnung des Plugin-Aufrufes
  • 'foreign': Der Foreign Key der Zieltabelle mit dessen ID die Haupttabelle verknüpft ist
  • 'height': optionale Höhenangabe; Standard 350 (=350px).
Für die korrekte Verbindung mit dem Unterformular müssen folgende Kriterien erfüllt sein:
  • Der Foreign Key muss als Parameter übernommen werden
  • und in $form['filters'] angeführt sein
  • in $inputs (type 'hidden') mit 'default' des Wertes enthalten sein
  • im Aufruf für den neuen Datensatz enthalten sein (&amp;[foreign]=[WERT])
function

Experimentelles Feld: Erlaubt innerhalb der Tabelle eine Feldberechnung

  • "value": einfache Formel mit Angabe von Datenfeldern in geschwungener Klammer

Beispiel: "{price}*0.2" Das Feld "price" muss in "table_fields" enthalten sein und vor dem Funktionsfeld stehen. In diesem Zusammenhang empfiehlt sich auch z.B.: "pattern" => "%.02f".

Reservierte Parameter

folgende Parameternamen sind reserviert und können bei gleichlautenden Feldnamen zu Konflikten führen:

"rid", "sid", "_id", "_w", "_ob", "_sb", "_s", "_l", "_o", "_hl"