Child pages
  • PIFA - Form Assistant
Skip to end of metadata
Go to start of metadata
The form assistant plugin PIFA allow for the easy creation of forms in the CONTENIDO backend that can be displayed anywhere in your sites frontend.

Tables

NameDescription
con_pifa_formthis data table stores forms for the clients and their languages
con_pifa_fieldthis table stores structure of form fields and their properties

Formular assistant also creates data tables, which are defined in backend of form assistant. The names of the data tables can be free defined. The defined name is always refered to the form.

Classes

NameDescription
cContentTypePifaFormcontent type class for CMS_PIFAFORM
PifaAbstractFormModuleabstract class for form module
PifaAbstractFormProcessorabstract class for form processor
PifaAjaxHandlerform assistant ajax handler class, contains methods which are called through ajax

PifaException

form assistant exception classes
PifaDatabaseException
PifaNotImplementedException
PifaIllegalStateException
PifaNotYetStoredException
PifaValidationException
PifaExporterclass for exporting formulars
PifaExternalOptionsDatasourceInterfacethis class allows add external sources for pifa fields like select options or checkboxes
PifaFieldCollectionItem collection class for the form field
PifaFieldItem class for the form field
PifaFormCollectionItem collection class for the form
PifaFormItem class for the form

PifaLeftBottomPage

GUI classes used in plugin
PifaRightBottomFormPage
PifaRightBottomFormFieldsPage
PifaRightBottomFormDataPage
PifaRightBottomFormExportPage
PifaRightBottomFormImportPage
PifaImporterimporter class to import forms from xml

Templates

Translation missing

This part should be translated to english.

Im Editor-Dialog des ContentTypen CMS_PIFAFORM können mehrere Templates definiert werden.

  • Klassen & Vorlagen | Vorlagen - GET: Vorlage für die Darstellung des Formulares
  • Klassen & Vorlagen | Vorlagen - POST: Vorlage für die Darstellung einer Erfolgsmeldung nach dem Absenden des Formulares
  • Benutzer-Mail | Vorlagen: Vorlage für Erstellung einer Mail an den Benutzer der das Formular ausgefüllt hat
  • System-Mail | Vorlagen: Vorlage für Erstellung einer Mail an den Betreiber der Website

Vorlagen werden im Verzeichnis "templates" des Mandanten abgelegt und können auch über das CONTENIDO Backend gepflegt werden.

Damit Vorlagen vom PIFA erkannt werden müssen deren Namen folgenden Namenskonventionen entsprechen:

  • GET-Vorlage: /cms_pifaform_[^\.]+_get\.tpl/
  • POST-Vorlage: /cms_pifaform_[^\.]+_post\.tpl/
  • Benutzer-Mail-Vorlage: /cms_pifaform_[^\.]+_mail_client\.tpl/
  • System-Mail-Vorlage: /cms_pifaform_[^\.]+_mail_system\.tpl/

Settings

Area/TypeNameDescriptionDefaultScope
pifafield-css-classes 'half-row,full-row,line-bottom,line-top'SCGU
pifatimestamp'always', 'byform', 'never''always'SCGU
pifa-recaptchasitekeyThe web page sitekey provided by Google reCAPTCHA SCGU
pifa-recaptchasecretThe web page secret provided by Google reCAPTCHA  SCGU

PIFA Extensions

Translation missing

This part should be translated to english.

Im Plugin form_assistant gibt es einen Unterordner namens "extensions". In diesem kann man eigene FormModule- und FormProcessor-Klassen ablegen, die, sofern sie der Namenskonvention (s.u.) folgen und eine Klasse enthalten, die von PifaAbstractFormModule bzw. PifaAbstractFormProcessor erben, automatisch vom PIFA erkannt und im Dialog des ContentTypen CMS_PIFAFORM zur Auswahl angeboten werden.

Namenskonventionen

Extensions sind in Dateien abzulegen dern Namen folgende Form hat: class.pifa.<class_name>.php.
Im Dateinamen ist "class_name" komplett klein zu schreiben und mit Unterstrichen zu trennen!
Die Klasse *in* dieser Datei ist wiederum in der "CamelCase"-Notation zu schreiben. Aus "class_name" wird "ClassName".
Beispiel: Die Klasse MailedFormProcessor findet sich in der Datei class.pifa.mailed_form_processor.php.

Vererbung von Extensions

Eine eigene FormModule-Klasse muß von PifaAbstractFormModule, eine FormProcessor-Klasse von PifaAbstractFormProcessor erben.
Durch die Vererbung stehen einer Instanz der eigenen FormProcessor-Klasse u.a. folgende Methoden zur Verfügung:

public function getModule() {
    // returns instance of defined FormModule
}

public function getForm() {
    // returns instance of PifaForm
}

Implementation einer eigenen FormModule-Klasse

Eine FormModule-Klasse ist für das Verhalten des Formulares zuständig, d.h. wie ein PIFA-Formular auf verschiedene Anfragen (GET bzw. POST) reagiert. Wie man seine eigene FormModule-Klasse implementiert werde ich später erklären.

Implementation einer eigenen FormProcessor-Klasse

Eine FormProcessor-Klasse hingegen ist für die Verarbeitung der erfaßten Daten verantwortlich. Der DefaultFormProcessor z.B. implementiert keine "eigenen" Aktionen, so daß ausschließlich das Verhalten seiner Vaterklasse (PifaAbstractFormProcessor) dafür sorgt, daß die Daten aus der Anfrage gelesen, validiert und in der Datenbank gespeichert werden. (Ich weiß, hier habe ich einen kleinen Fehler in der Architektur begangen.)

Der MailedFormProcessor hingegen erweitert das o.g. Verhalten des PifaAbstractFormProcessor um das Versenden von zwei Mails, einer an die Adresse des Benutzers, eine an das System (z.B. den sysadmin). Um das Verhalten seines FormProcessors zu implementieren kann der Entwickler folgende Methoden überschreiben oder überlagern:

 

protected function _processReadData() {
}

protected function _processValidatedData() {
}

protected function _processStoredData() {
}

 

Dabei handelt es sich um "Schablonen"-Methoden die nach dem lesen, validieren bzw. speichern aufgerufen werden.

Ist es mit dem neuen Formular-Assistent möglich die Inhalte des Formulars als Anhang (CSV) zu senden?

Um der erzeugten Mail auch die Formulardaten als CSV-Datei anzuhängen schreibst du dir einen eigenen FormProcessor (z.B. MaildCsvFormProcessor) und kopierst den Code aus dem MailedFormProcessor. Mittels PifaAbstractFormProcessor::getForm() holst du dir das Formular, dessen Daten du wiederum mittels PifaForm::getValues() erhältst. Daraus kannst du dir nun deinen Anhang bauen. Alternativ kannst du dir auch die Methode PifaForm::getCsv() anschauen, vielleicht kannst du ja mit der was anfangen.

Anbindung von Google reCAPTCHA

Ab CONTENIDO Version 4.9.13 ist der Formular-Assistent in der Lage, Google reCAPTCHA anzubinden.

Damit ein Formular ein solches Captcha-Feld korrekt verarbeiten kann muss einmalig bei Google reCAPTCHA ein Schlüsselpaar erzeugt und in den Mandanteneinstellungen hinterlegt werden (siehe Abschnitt "Settings").

Format der XML-Export-Datei

Mit der Version 1.1 des PIFA steht nun das Feature "Im- und Export von Formularen" zur Verfügung. Hier soll das Format der erzeugten XML-Datei erläutert werden um so auch das händische Erzeugen von Formularen mittels XML zu ermöglichen.

PIFA - Struktur der XML-Datei

Jede PIFA-XML-Datei besteht aus genau einem "pifa"-Element mit genau einem "form"-Element. Optional kann auch maximal ein "data"-Element enthalten sein. Das "form"-Element samt Nachfahren beschreibt die Struktur des Formulares, wogegen das "data"-Element die erfaßten Formulardaten dokumentiert.

 

<pifa>
	<form>
		<field></field>
		...
	</form>
	<data>
		<row></row>
		...
	</data>
</pifa>

FORM - Struktur des Formulares

Das "form"-Element dient der Definition des Formulares als solches. Angaben dazu werden als Attribute gespeichert. Zudem enthält es (optional) "field"-Elemente zur Definition der einzelnen Formularfelder welche weiter unten erläutert werden. Das "form"-Element unterstützt folgende Attribute:

AttributWerteBeschreibung
nameZeichenketteDer Name des Formulares, so wie er im Backend in der linken Navigation ausgegeben wird.
tableZeichenketteDer Name der Datenbank-Tabelle zur Speicherung der Formulardaten.
methodget | postAnfragemethode beim Absenden des Formulares.
timestamptrue | falseOb beim Speichern von Formulardaten auch ein Zeitstempel erfaßt werden soll. Siehe Setting "pifa/timestamp".

FIELD - Struktur der Formularfelder

Für jedes Formularfeld wird genau ein "field"-Element definiert. Einige Angaben zum Formularfeld werden als Attribute, andere als Kindelemente notiert. Das "field"-Element unterstützt folgende Attribute:

AttributWerteBeschreibung
rankZahl

Die Position des Formularfeldes im Formular.

Die Reihenfolge der Felder in der XML-Datei ist dabei irrelevant. Einzig dieses Attribut entscheidet über die Reihenfolge der Felder im Formular.
typeinputtext, textarea, inputpassword, inputradio, inputcheckbox, select, selectmulti, datepicker, inputfile, processbar, slider, buttonsubmit, buttonreset, buttonback, matrix, paragraph, inputhidden, fieldset_begin, fieldset_endDer Typ des Formularfeldes, der auch den Tabellentyp der Datenbank-Spalte bestimmt.
columnZeichenkette (erlaubt sind hier die Zeichen a-z, A-Z, 0-9 und _ [Unterstrich])Der Name der Datenbank-Spalte zur Speicherung der Formulardaten.
obligatorytrue | falseOb es sich bei diesem Feld um ein Pflichtfeld handelt oder nicht.

Einige Angaben zu Formularfeldern werden als Kindelemente definiert. Dies sind:

ElementWerteBeschreibung
labelZeichenkette

Die Beschriftung des Formularfeldes, so wie sie im Frontend ausgegeben wird.

Dieses Element hat ein Attribut "display" (true oder false) mit dem definiert werden kann, ob die Beschriftung im Frontend ausgegeben werden soll oder nicht.
helpZeichenkette

Der optionale Hilfetext zu einem Formularfeld.

Der Wert dieses Elementes muß als CDATA notiert werden!
errorZeichenkette

Die optionale Fehlermeldung zu einem Formularfeld.

Der Wert dieses Elementes muß als CDATA notiert werden!
ruleZeichenkette

Die optionale Validierungsregel zu einem Formularfeld. Hierbei handelt es sich um einen regulären Ausdruck.

Der Wert dieses Elementes muß als CDATA notiert werden!
classes"class"-Elemente

Mit dem Element "classes", das weitere "class"-Elemente enthält, werden die Namen der CSS-Klassen definiert die für ein Formularfeld ausgegeben werden sollen.

<classes>
	<class>foo</class>
	<class>bar</class>
</classes>
options"option"-Elemente

Mit dem Element "options", das weitere "option"-Elemente enthält, werden die Optionen für Formularfelder der Typen inputradio, select und selectmulti definiert. Deren Wert gibt die Beschriftung an, die im Frontend ausgegeben wird, wogegen deren "value"-Attribut den Wert angibt, der in der Datentabelle gespeichert wird.

<options>
	<option value="1">foo</option>
	<option value="1">bar</option>
</options>

Wenn die Optionen higegen aus einer externen Datenquelle bezogen werden sollen, wird das "options"-Element mit dem Attribut "source" anstelle von "option"-Elementen notiert. Dieses enthält dann den Namen der Extension-Klasse die zum Bezug der Options verwendet wird.

<options source="YourFancyDataSourceClass" />