kitForm - Formulare individuell anpassen und mit Presets arbeiten

Bei kitForm wird der eigentliche Programmcode und die Ausgabe der Formulare strikt voneinander getrennt. Diese klare Trennung hat den Vorteil, dass die für die Anzeige der Formulare erforderlichen XHTML sowie CSS Anweisungen sich in separaten Template Dateien befinden, die Sie mit jedem Editor bearbeiten können. Mit Grundkenntnissen in XHTML sowie in CSS können Sie die Formulare beliebig ergänzen und anpassen ohne dass Sie in den Quellcode von kitForm eingreifen müssen, mit der Programmiersprache PHP brauchen Sie sich nicht auseinandersetzen.

Die von Ihnen durchgeführten Änderungen und Anpassungen bleiben auch bei einer Aktualisierung (Update) von kitForm erhalten und werden nicht überschrieben.

Was benötigen Sie?

• einen FTP Zugang zu Ihrer WebsiteBaker Installation, z.B. mit FileZilla
• einen Editor, z.B. Notepad++

Â

Schritt für Schritt:

1. Öffnen Sie mit Ihrem FTP Programm Ihre WebsiteBaker Installation,
2. Wechseln Sie in das Verzeichnis /modules/kit_form/htt/,
3. Kopieren Sie das dort enthaltene Verzeichnis /1 lokal auf Ihren Rechner,
4. Benennen Sie das lokale Verzeichnis von /1 in /100 um.
5. Öffnen Sie das lokale Verzeichnis /100,
6. Öffnen Sie das dort enthaltene lokale Verzeichnis /DE.

In dem Verzeichnis /100/DE befinden sich 4 Dateien:

• form.htt - die Template Datei für das anzuzeigende Formular
• confirm.htt - die Template Datei, die dem Besucher nach dem Absenden des Formular als Bestätigung angezeigt wird
• mail.client.htt - die Template Datei, die die E-Mail Bestätigung enthält, die dem Absender des Formular zugesendet wird,
• mail.provider.htt - die Template Datei, die die E-Mail Benachrichtigung enthält, die dem Betreiber der Website (Ihnen) zugesendet wird.

KeepInTouch sowie kitForm verwenden die Template Engine Dwoo. Kurz umrissen ist eine Template Engine ein Programm, das eine Datei (Template) verarbeitet und in dieser enthaltene Platzhalter mit aktuellen Werten ersetzt. Die jeweils aktuellen Werte werden Dwoo durch ein Steuerungsprogramm (in diesem Falle von kitForm) geliefert. Auf diese Weise lässt sich der Programmcode von der formatierten Ausgabe sauber trennen, was mehrsprachige Ausgaben oder einfache Anpassungen bzw. Umstellungen der Ausgabe ermöglichen (z.B. von einem Tabellenorientierten Layout zu einer tabellenlosen Ausgabe etc.). Darüber hinaus kennen Template Engines wie Dwoo oder Smarty einfache Funktionen sowie Blockbefehle, die den Webdesigner bei flexiblen Gestaltung der Templates unterstützen.

Öffnen Sie mit Ihrem Editor bitte zunächst die Datei confirm.htt.

{*
 * kitForm
 *
 * @author Ralf Hertsch (ralf.hertsch@phpmanufaktur.de)
 * @link http://phpmanufaktur.de
 * @copyright 2011
 * @license GNU GPL (http://www.gnu.org/licenses/gpl.html)
 * @version $Id: confirm.htt 7 2011-04-11 06:19:53Z phpmanufaktur $
 *}

Im oberen Teil der Datei befindet sich ein Kommentar, dieser wird mit einer geschweiften Klammer nach links sowie einem Stern {* eingeleitet und und mit einem Stern sowie einer geschweiften Klammer nach rechts beendet *}. Kommentare werden nicht ausgegeben (auch nicht versteckt) und blähen somit die eigentliche Ausgabe nicht auf.

Unterhalb des Kommentar beginnt das eigentliche Template. Dieses besteht bei der confirm.htt im Wesentlichen aus einem <div> Container, der eine Überschrift <h2>, mehrere Absätze <p> sowie eine Tabelle <table> enthält. Dazwischen befinden sich die bereits erwähnten Platzhalter sowie verschiedene Funktionen und Blockbefehle.

• Platzhalter beginnen immer mit einer geschweiften Klammer nach links sowie einem Dollarzeichen und enden mit einer geschweiften Klammer nach rechts, z.B.: {$contact.kit_email}
• Bei Blockbefehlen und Funktionen fehlt das Dollarzeichen.

Eine Übersicht über die in Dwoo verfügbaren Blockbefehle und Funktionen finden Sie zusammen mit Beispielen in der Windows Hilfedatei zur Dwoo Documentation - ich empfehle Ihnen, sich diese Datei herunterzuladen.

Wenn Sie über das Template schauen, stellen Sie fest, dass es zwei Gruppen von Platzhaltern gibt: {$contact.xyz} und {$items.xyz}.

Die Platzhalter {$contact.xyz} stehen für Datenfelder aus KeepInTouch in den Templates confirm.htt, mail.client.htt und mail.provider.htt zur Verfügung:

• {$contact.kit_title} - Anrede (Herr, Frau)
• {$contact.kit_title_academic} - akademischer Titel (Dr., Prof. ...)
• {$contact.kit_first_name} - Vorname
• {$contact.kit_last_name} - Nachname
• {$contact.kit_company} - Firma
• {$contact.kit_department} - Abteilung
• {$contact.kit_street} - Straße
• {$contact.kit_zip} - Postleitzahl
• {$contact.kit_city} - Stadt
• {$contact.kit_phone} - Telefon
• {$contact.kit_phone_mobile} - Mobiltelefon, Handy
• {$contact.kit_fax} - Telefax
• {$contact.kit_email} - E-Mail Adresse
• {$contact.kit_newsletter} - Array mit den abonnierten Newslettern

Die Platzhalter {$items.xyz} stehen in den Templates confirm.htt, mail.client.htt und mail.provider.htt zur Verfügung und repräsentieren die freien Formularfelder, die Sie für das jeweilige Formular definiert bzw. festgelegt haben. Sie enthalten die über das Formular eingegebenen Werte, diese können in einer Schleife abgerufen und ausgegeben werden:

<table width="100%">
  <colgroup>
    <col width="150" />
    <col width="*" />
  </colgroup>
  {foreach $items item}
  <tr>
    <td>{$item.label}</td>
    <td>{$item.value}</td>
  </tr>
  {/foreach}
</table>

Der Zugriff erfolgt über den Blockbefehl {$foreach $items item} ... {/foreach}. Der Blockbefehl schreibt für jedes Formularfeld eine Zeile in die Tabelle, wobei {$item.label} der Feld Titel ist, den Sie für das jeweilige Formularfeld angegeben haben und {$item.value} der Wert ist, den der Besucher in das Formular eingetragen hat. Der Wert wird entsprechend dem Datentyp (Text, Ganzzahl, Dezimalzahl, Datum...) automatisch formatiert.

Mit recht einfachen Mitteln können Sie z.B. auf der Bestätigungsseite (confirm.htt) oder in der Bestätigungsmail (mail.client.htt) an den Kunden eine personalisierte Anrede realisieren:

<h2>{if count_characters($contact.kit_last_name) > 0}Sehr geehrte{if $contact.kit_title == 'Herr'}r{/if} {$contact.kit_title} {$contact.kit_last_name},{else}Sehr geehrte Besucherin, sehr geehrter Besucher,{/if}</h2>

Mit Hilfe der Funktion count_characters() können Sie feststellen, ob das Feld {$contact.kit_last_name}, das den Nachnamen enthält, länger ist als 0 Zeichen - also einen Namen enthält oder nicht.

Existiert ein Nachname, wird eine persönliche Anrede verwendet. Zusätzlich wird geprüft, ob der Kunde männlich {if $contact.kit_title == 'Herr'} ist oder nicht - im ersten Fall wird an "Sehr geehrte" noch ein "r" angehängt und anschließend der Nachname ausgegeben.

Befindet sich kein Nachname in der Datenbank, wird eine neutrale Anrede verwendet: "Sehr geehrte Besucherin, Sehr geehrter Besucher,".

Die grundsätzliche Funktionsweise ist in allen Templates gleich. Das Template für das eigentliche Formular form.htt ist gleichwohl etwas komplexer, da wesentlich mehr Parameter berücksichtigt werden müssen als bei der Ausgabe von Ergebnissen.

Bitte öffnen Sie jetzt das Template form.htt in Ihrem Editor.

Im Kopf des Template befindet sich wieder ein Kommentar {* ... *} danach folgt ein <div> Container, der ein vollständiges Formular <form> enthält.

Das Template form.htt enthält zwei Gruppen von Platzhaltern:

• {$form.xyz} - enhält Angaben und Werte zum Formular selbst
• {$fields.xyz} - enthält alle Angaben und Werte zu den einzelnen Feldern

An den Angaben zum dem Formularkopf:

 <div class="kit_form">
   <form name="{$form.name}" action="{$form.action.link}" method="post">
    <input type="hidden" name="{$form.action.name}" value="{$form.action.value}" />
    <input type="hidden" name="{$form.id.name}" value="{$form.id.value}" />
    <h2>{$form.title}</h2>
    {if isset($form.response)}
      {*entfernen Sie den Block $form.response nicht, er ermöglicht es dem Programm
        Mitteilungen auszugeben! *}
      <div class="message">{$form.response}</div>
    {/if}

sowie dem Formularfuß:

      {/foreach}
      {if $form.captcha.active == 1}
        <tr>
          <td>&nbsp;</td>
          <td colspan="2">
            {$form.captcha.code}
          </td>
        </tr>
      {/if}
      <tr>
        <td>&nbsp;</td>
        <td colspan="2">
          <input type="submit" value="{$form.btn.ok}" /> <input type="button" value="{$form.btn.abort}" onclick="javascript: window.location = '{$form.action.link}'; return false;" />
        </td>
      </tr>
    </table>
   </form>
 </div>

Hier werden Sie vermutlich nur wenig ändern - falls doch, achten Sie darauf, dass die Formularangaben im Kopf auf jeden Fall enthalten bleiben, sonst wird kitForm nicht mehr richtig funktionieren.

Die Felder selbst werden nacheinander über einen Blockbefehl {foreach $fields field} ... {/foreach} Zeilenweise in die Tabelle geschrieben.

Für alle Felder sind die folgenden Platzhalter gültig:

• {$field.id} - eine eindeutige Kennziffer für jedes einzelne Feld, die von kitForm automatisch vergeben wird. ID's unter 100 sind hierbei für KeepInTouch (KIT) Datenfelder reserviert, freie Formularfelder erhalten ID's über 100.
• {$field.type} - der Datentyp des jeweiligen Formularfeld. Handelt es sich hierbei um ein KIT Formularfeld, entspricht der Datentyp dem KIT Feld - die verfügbaren Felder haben sie weiter oben bei dem Datentyp {$contact.xyz} bereits kennengelernt (kit_title, kit_first_name, ... kit_city ...)
• {$field.label} - enthält den Titel des jeweiligen Formularfeld
• {$field.must} - der Wert des Platzhalters bestimmt, ob das Feld ein Pflichtfeld ist  = 1 oder nicht = 0
• {$field.name} - der Feld Bezeichner. Bei den KIT Datenfeldern entspricht der Feld Bezeichner dem Datentyp, bei den freien Formularfeldern gibt kitForm Bezeichern nach dem Muster free_xyz vor, diese können Sie jedoch über das kitForm Backend bei der Formulardefinition frei vergeben.
• {$field.value} - der Wert des Feldes. Dies ist entweder der Vorgabe Wert oder - falls das Formular mehrmals angezeigt wird - der bereits vom Besucher eingesetzte Wert
• {$field.hint} - der Hilfs- oder Hinweistext zu dem jeweiligen Feld

Darüber hinaus gibt es zu den einzelnen Datentypen der Felder noch ergänzende Angaben, wie z.B. {$field.checked} zum überprüfen ob eine Checkbox gesetzt ist oder nicht - diese erschließen sich Ihnen sicherlich aus dem direkten Zusammenhang und lassen sich für die einzelnen Datenfelder leicht nachvollziehen.

Mit dieser Dokumentation erhalten Sie eine Basis für die Anpassung und Änderung der Formulare in kitForm.

Wichtig ist, dass sie die bestehenden Formulare nicht überschreiben.

Wir haben ganz am Anfang das Verzeichnis /1 auf Ihren Rechner kopiert und dort in /100 umbenannt. Wenn Sie alle Änderungen an den Templates durchgeführt haben, kopieren Sie bitte das das Vereichnis /100 mit Hilfe Ihres FTP Programm unter /modules/kit_form/htt auf Ihren Webserver.

Sie werden sich fragen, warum?

• die nächsten Versionen von kitForm werden wahrscheinlich weitere Formulare enthalten - z.B. für eine Newsletter An- und Abmeldung,
• die Kennziffern 1 - 99 sind deshalb für kitForm reserviert
• ab Kennziffer 100 können Sie Formulare als Preset verwenden

Wie funktioniert das mit den Presets?

• Sie haben das neue Formular unterhalb von /modules/kit_form/htt in dem Verzeichnis 100 abgespeichert - dies ist gleichzeitig die Preset Kennung
• um das neue Formular zu verwenden, rufen Sie das Droplet kit_form mit dem zusätzlichen Parameter preset und der dazugehörigen Kennung auf:

[[kit_form?form=formular_name&preset=100]]

Dies bedeutet in der Praxis, dass Sie für ein und das selbe Formular unterschiedliche Templates gestalten können - diese weisen Sie dann einfach als Preset zu. Für das nächste Template verwenden Sie dann z.B. die Kennziffer 101 (speichern Sie das Template im Verzeichnis /101 ab!).

Diese Dokumentation ist ganz sicher nicht vollständig, ich freue mich über Ihre Hinweise und über Ihre Beiträge zu Ergänzung!

Ralf Hertsch, 19.04.2011

Zurück zur Übersicht