KB form

Aus Kitbooth Wiki: Deutsch

(Unterschied zwischen Versionen)

Wechseln zu:Navigation, Suche

Aktuelle Version vom 19. März 2012, 21:50 Uhr

Inhaltsverzeichnis

1 Beschreibung
2 Verwendung
3 Beispiele

Beschreibung

Die Klasse KB_form unterstützt den Webdesigner und Entwickler beim Erstellen und Auswerten von Formularen. Zusätzliche Funktionen wie ein E-Mail-Versand oder eine Registrierung werden bei der Auswertung der übersendeten Daten unterstützt.

Verwendung

KB_form wird für jedes Formular einmal instanziert. Die Core-Funktionalität stellt dafür die Funktion $kbc->form_o() im globalen Kontext zur Verfügung.

$form = $kbc->form_o();

new_element()

Jedes Formular-Element wird einzeln definiert. Dazu wird die Methode new_element aufgerufen und der Name des Elements übergeben. Danach kann das Element über $form->element[' Name '] angesprochen werden.

$form->new_element("Name");

Das neu definierte Element besitzt bereits alle wichtigen Eigenschaften. So ist der z. B. Formulartyp ein Input-Feld. Vorgegebene Eigenschaften können überschrieben werden.

Eigenschaften

type

Type legt den Formulartyp fest. Mögliche Werte sind:

Eigenschaft	Beschreibung	HTML-Entsprechung
input	Texteingabefeld	<input type="text">
password	Passworteingabefeld	<input type="password">
hidden	Verstecktes Textfeld	<input type="hidden">
textarea	Mehrzeiliges Textfeld	<textarea>
radio	Einfachauswahl	<input type="radio">
select	Mehrfachauswahl	<select>
checkbox	Mehrfachauswahl zum Ankreuzen	<input type="checkbox">
dropdown	Dropdown-Menü	<select>
button	Schaltfläche	<button>
submit	Schaltfläche zum Absenden	<button type="submit">

$form->element['Name']['type'] = 'dropdown';

value

Mit value lassen sich die Werte von Formularelemente vorbelegen. Bei den Formularelmente, die eine Auswahl an Werten ermöglichen (wie Dropdown-Menü), ist zu dem die Festlegung der möglichen Werte über value pflicht.

Der Standardwert für value ist leer.

Für Elemente mit den Typ input, password, hidden, textarea , button oder submit wird der Wert als String übergeben.

$form->element['Name']['value'] =  'Wert' ;

Für Elemente mit den Typ radio, select, checkbox oder dropdown wird der Wert als Array übergeben.

$form->element['Name']['value'] = array( 'Wert',$array);

Der zweite Wert im Array, beinhaltet die möglichen Werte, die das Formular-Element haben kann, ebenfalls als Array. Die Vorbelegung und der versendete Wert werden mit den Keys (nicht den Values) des Arrays durchgeführt.

$array = array(
      'name1' => 'Erster Name',
      'name2' => 'Zweiter Name'
);

Soll Erster Name vorbelegt werden, muss name1 übergeben werden.

 $form->element['Name']['value'] = array( 'name1',$array);

Soll kein Wert vorbelegt werden, muss NULL übergeben werden.

$form->element['Name']['value'] = array( NULL,$array);

essential

Die Eigenschaft essential legt fest, ob das Formularelement ein Pflichtfeld ist, also ausgefüllt sein muss. Wenn das Feld nicht oder nicht korrekt ausgefüllt wurde, wird die Eigenschaft message über die Methode message() ausgegeben und die Methode check() gibt false zurück.

Der Standardwert für essential ist false.

$form->element['Name']['essential'] = true;

label

Die Eigenschaft label beinhaltet die Bezeichnung, die über die Methode label() das Label des Formularelements als HTML ausgibt.

Der Standardwert für label ist leer.

$form->element['Name']['label'] = 'Name:';

description

Der Standardwert für description ist leer.

message

Die Eigeschaft message beinhaltet den Text, der ausgegeben wird falls beim zugehörigen Formularelement ein Fehler durch die Methode check() ermittelt wurde.

Der Standardwert für message ist Dieses Feld muss ausgefüllt sein.

$form->element['Name']['message'] = 'Name muss ausgefüllt sein.';

markup

Der Standardwert für markup ist leer.

label()

Die Methode label() gibt das die Eigenschaft label als HTML Label (<label>) aus. Ist die Eigenschaft leer, wird nichts ausgegeben.

$form->label('Name');

field()

Die Methode field() gibt das Formularfeld als HTML aus.

$form->field('Name');

message()

Die Methode message() gibt das die Eigenschaft message aus.

$form->message('Name');

check()

Beispiele

@@ Zeile 1: / Zeile 1: @@
-== Funktionalität ==
+== Beschreibung==
 {{Zurück|Klassen}}
 Die [[Klassen|Klasse]] '''KB_form''' unterstützt den Webdesigner und Entwickler beim Erstellen und Auswerten von Formularen. Zusätzliche Funktionen wie ein E-Mail-Versand oder eine Registrierung werden bei der Auswertung der übersendeten Daten unterstützt.
 == Verwendung ==
-KB_form wird pro Formular einmal instanziert. Die Core-Funktionalität stellt dafür die Funktion ''$kbc->form_o()'' im globalen Kontext zur Verfügung. Die Formular-Klasse erwartet als Parameter ein Array mit den Formulardefinitionen sowie ein optionales Array mit Einstellungen und Vorgaben.
+KB_form wird für jedes Formular einmal instanziert. Die Core-Funktionalität stellt dafür die Funktion '''$kbc->form_o()''' im globalen Kontext zur Verfügung.
-=== Formulardefinition ===
+ $form = $kbc->form_o();
-Die Formulardefinition ist ein mehrdimensionales Array. Jeder Eintrag im Array enthält eine Definition für ein bestimmtes Formular-Element. Jedes Formular-Element wird wiederum durch ein unbenanntes Array definiert. Die unterschiedlichen Formular-Elemente werden zwar ähnlich aber nicht in allen Fällen identisch definiert.
+=== new_element() ===
-Beispielhaftes Registrierungsformular:
+Jedes Formular-Element wird einzeln definiert. Dazu wird die Methode '''new_element''' aufgerufen und der Name des Elements übergeben. Danach kann das Element über '''$form->element[' ''' ''Name'' ''' ']''' angesprochen werden.
-  $formular = Array(
+  $form->new_element("Name");
-   array('input', 1, 'E-Mail-Adresse:','email', '','Bitte geben Sie eine korrekte E-Mail Adresse an.', '',''),
-   array('password_reg', 1, array('Passwort:','Passwort Wiederholung:'),'password', '','Die eingegebenen Passwörter sind nicht identisch.','', ''),
+Das neu definierte Element besitzt bereits alle wichtigen Eigenschaften. So ist der z. B. Formulartyp ein Input-Feld. Vorgegebene Eigenschaften können überschrieben werden.
-   array('input', 1, 'Vorname / Titel:','fname', '','Bitte geben Sie Ihren Vornamen / Titel an.','', '/[a-zA-Z\-]/'),
-   array('input', 1, 'Nachname:','name', '','Bitte geben Sie Ihren Namen an.','', '/[a-zA-Z\-]/'),
+=== Eigenschaften ===
-   array('input', 1, 'Firma:','company', '','Bitte geben Sie Ihre Firma an.','', '/[a-zA-Z0-9\-]/'),
-   array('captcha', 1, 'Verifizierungscode:','code', '','Bitte geben Sie den Code an.', '', '', "ffffff"),
+==== type ====
-   array('button', 1, 'absenden', 'send')
+Type legt den Formulartyp fest. Mögliche Werte sind:
+{| class="wikitable"
+|-
+! Eigenschaft!! Beschreibung!! HTML-Entsprechung
+|-
+| input  || Texteingabefeld ||  <input type="text">
+|-
+| password || Passworteingabefeld || <input type="password">
+|-
+| hidden|| Verstecktes Textfeld || <input type="hidden">
+|-
+| textarea || Mehrzeiliges Textfeld || <textarea>
+|-
+| radio || Einfachauswahl || <input type="radio">
+|-
+| select ||Mehrfachauswahl  ||<select>
+|-
+| checkbox|| Mehrfachauswahl  zum Ankreuzen ||<input type="checkbox">
+|-
+| dropdown || Dropdown-Menü  ||  <select>
+|-
+| button|| Schaltfläche ||  <button>
+|-
+| submit || Schaltfläche zum Absenden ||  <button type="submit">
+|}
+ $form->element['Name']['type'] = 'dropdown';
+----
+==== value ====
+Mit '''value''' lassen sich die Werte von Formularelemente vorbelegen. Bei den Formularelmente, die eine Auswahl an Werten ermöglichen (wie Dropdown-Menü), ist zu dem die Festlegung der möglichen Werte über '''value''' pflicht.
+Der Standardwert für '''value''' ist leer.
+Für Elemente mit den Typ '''input''', '''password''', '''hidden''', '''textarea ''', '''button''' oder '''submit ''' wird der Wert als String übergeben.
+ $form->element['Name']['value'] = '' 'Wert' '';
+Für Elemente mit den Typ '''radio''', '''select''', '''checkbox''' oder '''dropdown''' wird der Wert als Array übergeben.
+ $form->element['Name']['value'] = array('' 'Wert',$array'');
+Der zweite Wert im Array, beinhaltet die möglichen Werte, die das Formular-Element haben kann, ebenfalls als Array. Die Vorbelegung und der versendete Wert werden mit den Keys (nicht den Values) des Arrays durchgeführt.
+ $array = array(
+       'name1' => 'Erster Name',
+       'name2' => 'Zweiter Name'
   );
-Der erste Eintrag eines Formular-Element-Arrays ist immer die Bezeichnung des Formular-Elements gefolgt von einem Boolean ob das aktuelle Element bei einer Prüfung in Augenschein genommen werden soll. Der dritte Eintrag beinhaltet immer das Label eines Elements; der Vierte das Attribut ''name''. Der fünfte Eintrag
+Soll ''Erster Name'' vorbelegt werden, muss ''name1'' übergeben werden.
+  $form->element['Name']['value'] = array('' 'name1',$array'');
+Soll kein Wert vorbelegt werden, muss NULL übergeben werden.
+ $form->element['Name']['value'] = array('' NULL,$array'');
+----
+==== essential ====
+Die Eigenschaft '''essential''' legt fest, ob das Formularelement ein Pflichtfeld ist, also ausgefüllt sein muss. Wenn das Feld nicht oder nicht korrekt ausgefüllt wurde, wird die Eigenschaft '''message''' über die Methode [[#message()|message()]] ausgegeben und die Methode [[#check()|check()]] gibt ''false'' zurück.
+Der Standardwert für '''essential''' ist false.
+ $form->element['Name']['essential'] = true;
+----
+==== label ====
+Die Eigenschaft '''label''' beinhaltet die Bezeichnung, die über die Methode [[#label()|label()]] das Label des Formularelements als HTML ausgibt.
+Der Standardwert für '''label ''' ist leer.
+ $form->element['Name']['label'] = 'Name:';
+----
+==== description ====
+Der Standardwert für '''description''' ist leer.
+----
+==== message ====
+Die Eigeschaft '''message''' beinhaltet den Text, der ausgegeben wird falls beim zugehörigen Formularelement ein Fehler durch die Methode [[#check()|check()]] ermittelt wurde.
+Der Standardwert für '''message ''' ist ''Dieses Feld muss ausgefüllt sein.''
+ $form->element['Name']['message'] = 'Name muss ausgefüllt sein.';
+----
+==== markup ====
+Der Standardwert für '''markup''' ist leer.
+----
-Typische Einteilung eines Formular-Element-Arrays: <br>
+=== label() ===
-. Bezeichnung des Formular-Typs (Achtung, nicht Bezeichnung nach HTML Standard, sondern nach der implementierten Funktion in KB_form) <br>
-. Boolean ob das aktuelle Element bei einer Prüfung berücksichtigt werden soll <br>
-. Label den Elements <br>
-. HTML - Attribut ''name'' <br>
-. Voreingetragene Werte oder Auswahlmöglichkeiten (Übergabe als Array) bei ''select, radio und checkbox'' <br>
-. Angepasste Fehlermeldung zur Ersetzunug der Standardnachricht <br>
-. zusätzliche optionale Attribute wie ''class'' oder ''style'' z.B. ''style="color:red"'', die ohne weitere Prüfung integriert werden. <br>
-. regulärer Ausdruck für preg_match um die Eingabe validieren <br>
-=== Settings ===
+Die Methode '''label()''' gibt das die Eigenschaft [[#label|label]] als HTML Label (<label>) aus. Ist die Eigenschaft leer, wird nichts ausgegeben.
-Settings ist ein ein- oder mehrdimensionales Array, welches die Verhaltensweise der Klasse KB_form steuert oder weitere Parameter für die nachfolgende Verarbeitung übergibt.
-Beispielhaftes Array:
+  $form->label('Name');
-  $settings = array('error' => 'err_mess', 'autocheck' => 'send', 'register'=>true, 'mail' => $core['form_email'], 'subject' => 'Registrierung' );
-Die Array Elemente setzen folgende Parameter:
+=== field() ===
-error -> die CSS Klasse der Fehlermeldungen wird auf ''err_mess'' gesetzt
+Die Methode field() gibt das Formularfeld als HTML aus.
-autocheck -> sobald send im $_POST Array vorhanden ist, wird die automatische Eingabeprüfung gestartet
+ $form->field('Name');
-register -> gibt der KB_form zu verstehen, dass eine Registrierung vorgesehen ist. Es wird dann automatisch nicht nur die Eingabe validiert sondern auch die E-Mail-Adresse als primäres Attribut mit der Usertabelle abgeglichen.
-mail -> Ersetzung der Standard - E-Mail - Adresse bei Mail - Versand
-subject -> Ersetzung des Standardbetreffs bei Mail - Versand
-... much more will follow ...
+=== message() ===
+Die Methode '''message()''' gibt das die Eigenschaft [[#message|message]] aus.
-=== Instanzierung und Übergabe der Parameter ===
+  $form->message('Name');
-Da der include bereits in der Core-Funktionalität vorgenommen wurde, steht die Klasse sofort zur Verfügung. Ebenso stellt diese eine einfach Instanzierungsvariante zur Verfügung. Mit dem Aufruf (KB_core::form_o())
-  $form = $kbc->form_o($formular, $settings [,$values]);
-wird eine neue Instanz der Klasse Formular zurück geliefert. $formular und $settings werden dabei zwingend voraus gesetzt, $values ist eine optionale Übergabe.
-=== Formularausgabe ===
+=== check() ===
-==== generate_all() ====
-Die einfachste Möglichkeit der Ausgabe ist die Funktion ''$form->generate_all()'' (KB_form::generate_all). Diese erzeugt das komplette Formular mit allen HTML Tags. Die optionalen Parameter ''separator, class'' und ''action'' sollten zuvor Eintrag in den Settings übergeben werden. Dieser wird jeweils einmal nach Ausgabe des Label, des Formular-Elements sowie des eventuellen Fehlermeldung angewand.
- $formular = ( array('input', 1, 'Name','name', '','Bitte geben Sie Ihren Namen an.', '','') );
- $settings = array('separator' => '&lt;br&gt;');
- $form = $kbc->form_o($formular, $settings);
- $form->generate_all();
-==== gen_all_tpl() ====
-Die Funktion ''$form->gen_all_tpl()'' (KB_form::gen_all_tpl) entspricht weitgehend der Funktion ''$form->generate_all()''; erzeugt das Formular aber mit einem übergebenen Template. Der Template-String muss zuvor in den Settings übergeben werden, ebenso die optionalen Parameter ''template_pre, template_post, class'' und ''action'' Dieser String kann dabei beliebiges HTML enthalten, setzt aber für eine erfolgreiche Ausgabe die dre Platzhalter &lt;#1#&gt; (=Fehlermeldung) &lt;#2#&gt; (=Label) &lt;#3#&gt; (=Formular-Element) voraus.
- $formular = ( array('input', 1, 'Name','name', '', 'Bitte geben Sie Ihren Namen an.', ' ',' ') );
- $settings = array('template' => '&lt;tr&gt; &lt;td&gt;&lt;#2#&gt;&lt;/td&gt; &lt;td&gt;&lt;#3#&gt;&lt;/td&gt; &lt;td&gt;&lt;#1#&gt;&lt;/td&gt; &lt;/tr&gt;');
- $form = $kbc->form_o($formular, $settings);
- $form->gen_all_tpl();
 == Beispiele ==
 [[Kategorie:Handbuch]]