Formicula

Guite edited this page Nov 15, 2014 · 4 revisions

== Formicula ==

Formicula ist ein Zikula-Modul, mit dem Formulare zur Kontaktaufnahme zur Verfügung gestellt werden können. Es werden 2 vorgefertigte Formulare angeboten. Für das Basisformular kann eingestellt werden, welche Felder angezeigt werden sollen und ob diese Pflichtfelder oder optionale Felder sein sollen. Außerdem kann eine Anti-Spam Funktion aktiviert werden.

=== Voraussetzungen ===

*Formicula 2.0 läuft nur mit Zikula 1.0.x *Formicula 2.1 läuft nur mit Zikula 1.1.x *CAPTCHAs benötigen die GD-Lib - die ist bei den meisten PHP-Konfigurationen aber aktiv

=== Installation === Zunächst wird Formicula wie ein normales : #Formicula auspacken und ins Modulverzeichnis hochladen. #Modulliste erneuern, Formicula initialisieren und aktivieren. #Während der Installation versucht Formicula das Verzeichnis formicula_cache mit einer leeren index.html und einer schützenden .htaccess anzulegen. Das kann schief gehen, wenn der Safe_Mode bei deiner PHP-Konfiguration eingeschaltet ist oder das temporäre Verzeichnis von Zikula außerhalb des DocumentRoot liegt. Dann musst Du das manuell nachholen: ##Lege das Verzeichnis formicula_cache in Deinem temporären Verzeichnis ("pnTemp") and und setze die Schreibrechte auf 777, so dass Zikula dort schreiben darf. ##Lege darin eine leere index.html an - du kannst auch einfach eine aus modules/formicula hierher kopieren. Diese Datei verhindert, dass bei einem falsch konfigurierten Apache oder einem Webserver, der keine .htaccess kennt der Inhalt des Verzeichnisses einfach im Browser einsehbar ist. ##Lege eine .htacess in formicula_cache an mit folgendem Inhalt:

SetEnvIf Request_URI ".gif$" object_is_gif=gif
SetEnvIf Request_URI ".png$" object_is_png=png
SetEnvIf Request_URI ".jpg$" object_is_jpg=jpg
Order deny,allow
Deny from all
Allow from env=object_is_gif
Allow from env=object_is_png
Allow from env=object_is_jpg
Diese Regeln weisen den Webserver an, aus diesem Verzeichnis nichts anderes auszuliefern als Grafiken. So kann kein Hacker ein ausführbares Skript einschmuggeln. #Lege nun Kontakte in der Administration von Formicula an. Formicula legt da bei der Installation automatisch einen Kontakt für den Admin an. #Du musst nun Zugriffsrechte für Formicula anlegen. Mit dieser Regel bekommen alle Besucher Deiner Site das Recht alle Formicula-Formulare aufzurufen. Da schon einige Formulare mitgeliefert werden, die Du aber vielleicht gar nicht nutzt, ist das unter Umständen nicht gewünscht. Du solltest noch einmal weiter unten nachschauen, wie man nur die benutzten Formulare freigibt: {| border=1 class="wikitable" ! '''Gruppe''' ! '''Komponente''' ! '''Instanz''' ! '''Berechtigung''' |- | Unregistrierte | formicula:: | .* | kommentieren |}

Mitgeliefert werden zwei Beispiel-Formulare mit den IDs 0 und 1: *0 ist ein normales Kontaktformular *1 ist ein Formular für Online-Bewerbungen Anhand der Beispiele kannst Du Dir abgucken, wie Du eigene Formulare für Deine Zwecke erstellen kannst.

=== Konfiguration === {| border=1 class="wikitable" !X anzeigen !Hier kannst Du bestimmte Felder einfach ein und ausschalten. Das das per Template mit weniger Aufwand ginge, wird diese Konfiguration in Zukunft wegfallen |- | Bestätigungsmail an User verschicken | Soll derjenige, der ein Formular absendet dafür eine Bestätigung bekommen? |- | Verzeichnis für Dateiupload | Wenn Du Uploads per zulassen willst, musst Du hier das Verzeichnis einstellen. Sichere es dann auch mit einer .htaccess, so dass es nicht als Angriffspunkt von Hackern benutzt werden kann/ |- | Datei nach dem Senden löschen | Damit werden eventuelle Uploads nach dem Versenden der Mail an den Kontakt gelöscht |}

{| border=1 class="wikitable" !Spamcheck aktivieren !CAPTCHAs werden angezeigt |- | Spam Check nicht in diesem Formularen verwenden | kommaseparierte Liste der FormIDs, die z.B. in Pagesetter eingebettet sind, hier könnte es zu Problemen beim Weiterleiten kommen, wenn der Benutzer die Rechenaufgabe nicht korrekt löst. |}

=== Kontakte === Jeder Kontakt verfügt über bestimmte Informationen: {| border=1 class="wikitable" !Bezeichnung !Name des Kontaktes. Das kann der richtige Name sein oder so etwas wie "Webmaster" |- | Emailadresse | E-Mail-Adresse, an die die Daten geschickt werden sollen |- | Öffentlich | Nur wenn hier ein Häkchen gesetzt ist, wird die Adresse angezeigt. So kann man bestimmte Kontakte auch vorübergehend aus dem Formular nehmen |- | Absendername | Name, der in der E-Mail (auch in der Bestätigung) als Absender stehen soll. |- | Absenderemail | Adresse, die in der E-Mail (auch in der Bestätigung) als Absender stehen soll, z.B. noreply@example.com |- | Betreff | Betreff der Mail an den Kontakt ('''nicht''' der Bestätigung!) - z.B. "Kontaktformular: %s" |}

Im Betreff sind folgende Variablen benutzbar: {| border=1 class="wikitable" !%s !Site-Name |- | %l | Slogan |- | %u | Site URL |- | %c | Kontakt Name |- | %n | Extrafeld-Name |- | %d | Extrafeld-Daten |}

=== Templates === Die Formulare werden in Form dieser Templates angelegt: {| border=1 class="wikitable" !X_userform.html !Dein eigentliche Formular mit allen Eingabefeldern |- | X_userconfirm.html | Diese Seite wird nach dem erfolgreichen Absenden des Formulars angezeigt |- | X_usererror.html | Diese Seite wird bei einem Fehler angezeigt. |- | X_usermail.txt | Plain-Text Bestätigungsmail für den Benutzer |- | X_usermail.html | HTML Bestätigungsmail für den Benutzer |- | X_adminmail.txt | Plain-Text Mail an den Kontakt |- | X_adminmail.html | HTML-Mail an den Kontakt |}

(X ist dabei eine Zahl und die ID des Formulars. 0 und 1 sind schon vergeben - siehe oben.) ==== Bestätigungsmails ==== Wenn Du Deine Benutzer aussuchen lassen willst, ob sie die Bestätigung als HTML-Mail oder als Plain-Text (empfohlen) bekommen wollen, geht das so:





Sonst kannst Du einfach ein verstecktes Feld mit der von Dir bevorzugten Variante einfügen:


Wenn gar keine Bestätigung verschickt werden soll, setzt Du einfach:

 
 

Das überschreibt auch die Einstellung in der Modul-Konfiguration.

==== Zusätzliche Felder ==== Neben den vorhandenen Feldern kannst Du beliebige, weitere Felder in einem Formular benutzen. So kannst Du leicht komplett eigene Formulare anlegen.

Dazu benötigt Formicula allerdings einige weitere Informationen von dem Formular. Im Folgenden steht X für die laufende Nummer des Zusatzfeldes (beginnend mit 0!) {| border=1 class="wikitable" !'''name''' !'''type''' !value |- | customXname | (hidden field) | Name des Zusatzfeldes |- | customXmandatory | (hidden field) | 1 = Pflichtfeld |- | customXdata | (input field) | Das eigentliche Eingabefeld |}

'''Beispiel:'''

Ein Feld (Pflichtfeld)





Noch ein Feld (Optional)



Stelle sicher, dass Deine Zusatzfelder immer von 0-n konsistent durchnummeriert sind!

Zum Aufruf der Felder in den Templates X_userform.html, X_userconfirm.html, X_adminmail.html/.txt, X_usermail.html/.txt kann folgender Code verwendet werden:

Aufruf Name

Aufruf Daten

XYZ steht dabei für das Zusatzfelder (z.B. das Erste: 0)

Hinweis: Du solltest darauf achten, die vordefinierten (Pflicht-)Felder für Username, Email und Nachricht nicht aus dem Formular zu löschen, da ansonsten Probleme bei der Validierung beim Abschicken des Formulars auftreten. Werden diese Felder im selbsterstellten Formular nicht benötigt, kann man sie jedoch als hidden field einfügen und mit einem Wert belegen, der die Validierung besteht. ==== Dateianhänge ==== Natürlich kann Formicula auch mit Dateianhängen arbeiten. Leider unterstützt das keines der Beispielformulare. Es ist aber ganz einfach.

#'''Wichtig:''' Das Formtag muss das Attribut ''enctype="multipart/form-data"'' und ''method="POST"'' gesetzt sein! Dies ist notwendig um eine Datei übertragen zu können. ''enctype'' steht dabei für die Art des Übertragunsformats vom Browser zum Server. Das Übertragungsformat ''"multipart/form-data"'' erlaubt den Transfer ganzer Dateien, egal ob es sich dabei um Bilder, Texte oder andere Daten handelt. ''method'' steht für die Art der Übertragung, wobei der Wert ''"POST"'' festlegt, daß die Übertragungsdaten im HTTP Protokoll nicht im sogenannten Header sondern im Body übertragen werden. Der Tag '''' im Formular gibt an, daß eine Datei beim Absenden des Formulars übertragen wird. Der Feldname, der im Formular für diese Datei steht, heißt beim Beispielformular "DATEI1". #Nun legst Du einfach so viele Zusatzfelder (siehe oben) mit Upload-Funktion an, wie Du brauchst. #In der Administration setzt Du den Upload-Pfad. Das Verzeichnis muss natürlich existieren und beschreibbar sein.

=== Zugriffsrechte === Du kannst für jedes Formular eigene Zugriffsrechte setzt. Wenn eine Gruppe Formulare ausfüllen und absenden können soll, benötigt sie '''kommentieren''' Rechte für das Formular.

'''Beispiel 1''' Alle unregistrierten Benutzer dürfen alle vorhandenen Formulare benutzen und an alle Kontakte schreiben: {| border=1 class="wikitable" ! '''Gruppe''' ! '''Komponente''' ! '''Instanz''' ! '''Berechtigung''' |- | Unregistrierte
| formicula:: | .*
| comment |}

'''Beispiel 2''' Alle unregistrierten Benutzer dürfen Formular 0 benutzen und an alle Kontakte schreiben: {| border=1 class="wikitable" ! '''Gruppe''' ! '''Komponente''' ! '''Instanz''' ! '''Berechtigung''' |- | Unregistrierte
| formicula::
| 0::
| comment |}

'''Beispiel 3''' Alle registrierten Benutzer dürfen in Formular 1 an die Kontakte 2 und 3 schreiben: {| border=1 class="wikitable" ! '''Gruppe''' ! '''Komponente''' ! '''Instanz''' ! '''Berechtigung''' |- | Benutzer
| formicula::
| 1:(2/3):
| comment |}

=== Verlinken === Du kannst Formicula ganz einfach im Hauptmenü mit {formicula} verlinken. Daraus wird dann index.php?name=formicula und das ruft automatisch Formular 0 auf.

Willst Du ein anderen Formular aufrufen trägst Du im Menü {formicula:main:user&form=X} (X = Formular ID) ein oder gibst die URL index.php?name=formicula&form=X (X = Formular ID) ein.

==== Werte übergeben ==== Du kannst dem Formular auch Daten per URL übergeben. Das ist zum Beispiel sinnvoll, wenn Du in einem anderen Modul Veranstaltungen beschreibst und ein Anmeldeformular verlinkst. Das geht dann mit dem URL-Parameter addinfo[]: ''index.php?name=formicula&form=2&addinfo[var]=MEINWERT'' Im Formicula-Formular 2 steht dann der übergebene Wert in dieser Form zur Verfügung:


=== Validierung im Browser === Die Validierung der Eingaben im Browser funktioniert mit Prototype - Wenn Du das nicht nutzen möchtest, kannst Du die Aufrufe einfach aus dem Template entfernen.

Eine genaue Beschreibung der Validierung findest Du auf: http://tetlaw.id.au/view/blog/really-easy-field-validation-with-prototype/

=== CAPTCHA === Das Plugin "simplecaptcha" fügt dem Formular eine einfache Mathematikaufgabe hinzu, die dazu dient, zu erkennen, ob ein Mensch oder ein Spam-Bot zugreift. Der Mensch sollte die Aufgabe auch auf dem erzeugten Bild erkennen und dann lösen können. Der Spam-Bot erkennt das Bild nicht als Aufgabe.

Formicula versucht die Bilder in dieser Reihenfolge in einem Format zu erzeugen: #gif #jpg #png Sollte keines dieser Formate auf Deinem Server erlaubt sein, funktionier der Spam-Check nicht und Du solltest ihn in der Administration deaktivieren. Weiterlesen: http://php.net/manual/en/ref.image.php

Formicula kommt auch damit zurecht, wenn Dein temporäres Verzeichnis außerhalb der /DocumentRoot liegt. Das Bild wird dann nicht direkt verlinkt, sondern von einer eigenen Funktion geholt und dargestellt.

=== Tipps und Tricks === Hier ein paar Anwendungsbeispiele: ==== Beispiel: Impressum ==== Oft soll das Impressum gleich über dem Kontaktformular angezeigt werden. Dann bietet sich an, einfach in Pages das Impressum anzulegen und die Seite mit dem Impressum per API-Aufruf direkt auf der Seite des Kontaktformulars einzubinden. Dazu musst Du das Template für das Kontaktformular öffnen (/modules/formicula/pnTemplates/X_userform.html - X = Deinen Formularnummer) und trägst dort an der Stelle, wo das Impressum auftauchen soll ein:

  
  

Wobei Y die ID der Page des Impressums ist (Siehe [//community-german/attachment/wiki/moduleBeispielKleineFirma/pagesID.png Screenshot]).

*'''Demo:''' [http://foerdefluesterer.de/Kontakt/ http://foerdefluesterer.de]

Das funktioniert übrigens genauso mit Content: *'''Demo:''' [http://didgeridoos-und-luren.com/Kontakt/ http://didgeridoos-und-luren.com] *'''Demo:''' [http://clemens-coaching.de/Kontaktformular/ http://clemens-coaching.de/]

==== Beispiel: Anmeldeformular ==== Nehmen wir an Du hast in Pagesetter einen Publication Type mit der ID 4 und in diesem Publication Type hast Du verschiedene Veranstaltungen. Unter jeder Veranstaltung soll direkt ein Anmeldeformular erscheinen. Dann kannst Du einfach statt des Pagesetter-Artikels das Anmeldeformular auf rufen und dem tid und pid direkt übergeben: ''index.php?name=formicula&form=2&addinfo[tid]=4&addinfo[pid]=17''

Dann hast Du die zwei Werte im Template 2_userform.html) mit diesem Aufruf:

   => 4
   => 17

Damit kannst Du die Pagesetter-Publication aufrufen:


Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.