Kontaktformulare @ L.V. Expertise X3

Funktionsweise

Im Folgenden wird die Vorgehensweise bei der Anlage eines 'XTEND-Formulars' mit der Aktion 'Speichern' des X3-Objekts AYZ per Klick auf einen Button der HTML-Seite beschrieben. Die Formulardaten werden vom Benutzer in der Feldern des HTML-Formulars erfasst und als Aktionsparameter übergeben.

Wenn Ihre XTEND-Wert seit auf Basis einer Kopie von ASAMPLE erstellt wurde, sind die Parameterdaten bereits angelegt.

Sonst können sie entweder angelegt oder mit dem X3-Aktionsbutton 'Kopieren' einzeln von der Website ASAMPLE kopiert werden.

XTEND-Formulare bestehen aus:

Kopfzeile (Listenblock):

Betreff (TTL)
E-Mail-Adresse des Benutzers (MAICOD)
Meldung (CMT)
Typ (TYP)

Parameter (Tabellenblock) für die Optionsverwaltung:

Bezeichnung (PARCOD)
Wert (PARVAL)

Die bei der Anlage berechneten Daten sind der Code (FRMCODE), der Status (STATUT) und das Anlagedatum (CREDAT).

In unserem Beispiel werden wir ein Kontaktformular (TYP = CON) anlegen, dass in Bezug auf die betreffende Person folgende Angaben enthält:

Unternehmen
Aktivität
Postleitzahl

Erstellung

Anlage einer HTML-Seite (AXTDFRMCREATE) mit einem Erfassungsformular
Die Formulardaten werden in Beispiel verschlüsselt übermittelt (HTTPS)
Anlage einer Schnittstelle (AXTDFRM) für den Aufruf des Webservice
Anlage eine Webaktion vom Typ X3-Objektanlage (AXTDFRMCREATE). Als Parameter werden der Titel, die E-Mail-Adresse, der Kommentar und die Liste der gewählten Optionen übergeben.
Diese Parameter werden mit den Parametern des Webservice gemappt.
Anlage eines <dynamic link>-Tokens (ADLKCONTACTNEW), das in die HTML-Seite eingefügt wird (Button 'Anlegen'), um die Parameter mit den Feldwerten des HTML-Formulars zu belegen und die Aktion anzustoßen.

X3-Parameter

In diesem Absatz ist ein Zusatz zum Anlageprozess für Benutzeraktionen.

1. Schritt – Schnittstellenanlage

1. Es wird die Schnittstelle 'Benutzeraktion Objekt' AXTDFORM angelegt, die sich auf den Veröffentlichungsnamen des Objekts AYZ stützt (AXTDAYZ)

2. Zugriff generieren

3. Generierung aller Schnittstellenfelder
Siehe Menü 'Tools/<field>-Token anlegen'

2. Schritt – Entitäten anlegen

Entitäten anlegen:

AXTDFRMHEAD mit den Kopfzeilenfeldern
XTDFRMPARAM mit den Feldern der Optionen PARCOD und PARVAL

Siehe Menü Tools / Eingabehilfe.

Diese Entitäten werden anschießend beim Mapping der Rückgabe der Formularanlageaktion verwendet.

In unserem Beispiel sind zwei Schlüssel für AYZ definiert:

FRMCOD entspricht der Formular-Id
FCYCOD ist der Code der XTEND-Website und entspricht dem Code der aktuellen Website

FCYCOD filtert die Formulare der aktuellen ASAMPLE-Website.

Dieser Schlüssel muss gelöscht werden, wenn alle Formulare der Datenbank gelesen werden sollen

3. Schritt – Anlage der Webaktion

Parameterdeklaration

Anlage einer standardmäßigen AXTDFRMCREATE-Aktion. Als Parameter werden Typ, Titel, E-Mail-Adresse, Kommentar und Optionen übergeben.

Lediglich die vom Aufrufkontext der Aktion abhängigen Webserviceparameter werden als Parameter der Erfassungsaktion deklariert.

Wie diese in Abhängigkeit des Aufrufkontexts zu belegen sind, richtet sich nach dem <dynamic link>-Token (Webfeld, XTEND-Feld etc.).

Löschen am Anfang
aktiviert, um die Entitäten AXTDFRMHEAD und AXTDFRMPARAM zu Beginn der Aktion zu löschen (vor der Ergebnisrückgabe des Unterprogrammaufrufs). Dies dient der korrekten Ergebnisanzeige auf derselben HTML-Seite mithilfe eines Tokens für bedingte Blöcke auf Basis des Feldes FRMCOD.

Rückmeldung Aktivität
Ja: damit jeder Aktionsaufruf in der Protokolldatei geführt wird

Aktiv nach Reload
Nein: damit nicht erneut ein Formular erstellt wird, wenn der Benutzer nach der Formularerstellung auf F5 drückt

Aktivierung Button
Anlegen: um den Aktionsbutton AYZ-Objekt speichern anzustoßen

Mapping der Aufrufparameter

Die XTEND-Felder müssen den Aufrufparametern des Webservice zugeordnet werden.

In unserem Fall müssen nur die Aktionsparameter TYP, TTL, CMT,MAIDCOD, PARCOD und PARVAL gemappt werden.

PARCOD und PARVAL können mehrfach vorkommen, d. h. der XTEND-Server kann mehrere HTML-Felder desselben Namens auf einen mehrdimensionalen Parameter mappen.

Für das Mapping der Aktionsparameter wird nicht der Entitätscode erfasst.

Die Webserviceparameter, deren Wert stets aus demselben Kontext stammt, können direkt im Aktionsmapping per Angabe der Entität belegt werden.

Beispiel: Zur Übergabe einer Benutzeranmeldekennung könnte diese direkt dem Feld AUSERCODE der Entität ASESSION zugeordnet werden, anstatt die Kennung als Aktionsparameter zu deklarieren.

Mapping der Rückgabeparameter

Anlage von zwei XTEND-Entitäten aus den von X3 zurückgegebenen Daten:

AXTDFRMHEAD, um die Listenfelder zu speichern
AXTDFRMPARAM (ggf. mehrere), um die Felder des Tabellenblocks zu speichern, der die Parameter umfasst

Die Entitäten vom Typ Aktion werden während der gesamten Benutzernutzungsdauer im Speicher gehalten.

Sie werden bei jedem Aktionsaufruf automatisch erneut angelegt.

Aktion Entitäten löschen

Wenn die Anzeige mit einem bedingten Block verwaltet werden soll, müssen die Entitäten bei der erstmaligen Anzeige der Seite gelöscht werden (bei Klick auf den <dynamic link>-Token ADLKCONTACT in der Auswahlliste links).

Dafür wird eine AXTDFRMRESET-Aktion angelegt, deren einzige Aufgabe im Löschen der Entitäten AXTDFRMHEAD und AXTDFRMPARAM besteht.

Diese Aktion ist dem Token ADLKCONTACT zugeordnet.

Typ
Standard

Schnittstelle
Keine

4. Schritt – Anlage des dynamischen Links

Der dynamische Link ADLKXTDFRMCREATE ist das Token, das in den Formularanlagebutton eingefügt wird.

Mit diesem Link können die Zielseite (aktuelle Seite) definiert, die Aktion AXTDFRMCREATE zugeordnet und die Parameter belegt werden.

Allgemeine Parameter

Rückmeldung Aktivität
Ja: damit jeder Klick auf den Link in der Protokolldatei geführt wird

HTTP-Post-Modus erzwingen
Nein: Da dem dynamischen Link eine Aktion mit Parametern zugeordnet ist, wird die Abfrage automatisch im POST-Modus gesendet.

Aktuelle Seite
Ja: Das Ergebnis (Meldung oder erstelltes Formular) wird auf der aktuellen Seite angezeigt

Aktion
Code der anzustoßenden Aktion

Prüfung Webfelder
Ja: für die Prüfung der Webparameter (siehe Abschnitt 'Aktion')

Aktionsparameter

Hier werden sämtliche Parameter der Aktion deklariert und angegeben, ob diese belegt werden sollen.

Feld TYP
Konstante: Der Typ des Formulars ist stets Vertrag (CON)

Felder TTL, MAICOD
'Chp Web Oblig': Mussfeld.

Felder CMT, PARCOD, PARVAL
'Champ web': Kannfeld.

Cste/Attrib. web
Enthält den Namen des <input>-Tags (Attributname)

Die Eingabeprüfung ist nur aktiv, wenn das Kontrollkästchen 'Allgemein/Prüfung Webfelder aktiviert ist.

Die Abfrage wird nur unter folgenden Bedingungen an den XTEND-Server gesendet:

Der Benutzer hat sämtliche Mussfelder belegt
In den Feldern vom Typ Datum sowie in der numerischen Feldern wurden korrekte Werte erfasst

Die Prüfung wird von der JavaScript-Bibliothek von XTEND durchgeführt.

Token für die Seitenanzeige

Mit dem Token ADLKCONTACT kann die Erstellungsseite des Formulars aus der Auswahlliste im linken Maskenbereich heraus angezeigt werden.

Um die Anzeige mit dem bedingten Block ACNDXTDFRMHIDE zu verwalten, müssen die Formularentitäten bei der erstmaligen Anzeige gelöscht werden.

Dieser Vorgang wird realisiert, indem die Aktion AXTDFRMRESET dem Token ADLKCONTACT zugeordnet wird.

Mit diesem Token kann die Seite auch im abgesicherten Modus angezeigt werden (HTTPS). Die Daten des Benutzers werden dann verschlüsselt.

Rückmeldung Aktivität
Ja

Post-Modus erzwingen
Ja: um den in der aktuellen Seite gespeicherten XTEND-Kontext zu behalten.
Der HTTP-GET-Modus wird nur bei Links vom Typ Anker verwendet, die zu den Suchmaschinen (Webcrawlern) kompatible sein müssen.

Aktuelle Seite
Nein/AXTDFRMCREATE: Zielseite

Aktion
AXTDFRMRESET: Löschen der Formularentitäten

5. Schritt – Anlage der <block>-Token

Die <block>-Token ABLKFRMHEAD und ABLKFRMPARAM werden für die Anzeige der Entitäten AXTDFRMHEAD und AXTDFRMPARAM verwendet, die für die Daten eines XTEND-Formulars stehen.

Kopfzeilendaten

Typ
Einzelner Datensatz: Lesen der Entität AXTDFRMHEAD und Positionieren der Daten oben (Top) auf dem Stapel der Kontextdaten, dann Ausführung der abgeleiteten Token.

Keine Daten
Nichts anzeigen: Wenn die Entität AXTDFRMHEAD nicht existiert, werden Block und abgeleitete Token ignoriert.

Entität
AXTDFRMHEAD: Code der anzuzeigenden Entität

Parameterblock

Typ
Mehrere Datensätze: Iteration über alle AXTDFRMPARAM-Entitäten und Positionierung derselben oben (Top) auf dem Stapel der Kontextdaten, dann Ausführung der abgeleiteten Token.

Keine Daten
Nichts anzeigen: Wenn die Entität AXTDFRMPARAM nicht existiert, werden Block und abgeleitete Token ignoriert.

Entität
AXTDFRMPARAM: Code der anzuzeigenden Entität

Zeilen pro Block
10: Auf der Seite werden maximal 10 AXTDFRMPARAM-Entitäten angezeigt.

Zellen pro Zeile
1: Pro Zeile wird eine AXTDFRMPARAM-Entität angezeigt.

Stil pro Zeile
Keiner: in der Datei 'my.css' für die farbliche Hervorhebung der Zeilen zu definierenden Stile.

Es können keine Auswahlkriterien für Blöcke definiert werden, in denen im Speicher des XTEND-Servers gehaltene Entitäten selektiert werden (d. h. Entitäten vom Typ Sitzung oder Aktion). Im Block werden automatisch sämtliche Entitäten ausgewählt.

Die Auswahlkriterien beziehen sich lediglich auf Entitäten vom Typ 'Datenzugriff'.

6. Schritt – Anlage des Tokens für bedingte Blöcke

Hier wird die Anwendung von bedingten Blöcken erläutert.

Das Token ACNDXTDFRMHIDE wird verwendet, um den Seiteninhalt je nach Existenz eines Formulars zu ändern.

Ist die Entität AXTDFRMHEAD vorhanden (Block ABLKFRMHEAD nicht leer), wurde ein Formular angelegt, das nun angezeigt werden muss
Ist die Entität AXTDFRMHEAD nicht vorhanden (Block ABLKFRMHEAD leer), müssen die Eingabefelder angezeigt werden

Anzeige
Nicht aktiviert: Der Tokeninhalt (HTML und abgeleitete Token) wird maskiert, wenn die Bedingung erfüllt ist.

Kriterientyp
Leerer Block: Die Anzeige- / Markierungsbedingung basiert darauf, ob der betreffende Block Daten enthält oder nicht

Block
ABLKFRMHEAD: Code des zu testende Blocks.

Damit die Eingabefelder bei der erstmaligen Seitenanzeige auch dann angezeigt werden, wenn zuvor ein Formular erstellt wurde, haben wir die Aktion AXTDFRMRESET zum Löschen der Formularentitäten angelegt.

Diese Aktion wird von dem Token für dynamische Links ADLKCONTACT aufgerufen, welches die Erstellungsseite für ein Formular per Klick in die Auswahlliste links anzeigt.

7. Schritt – Seitenanlage

Anlage der Website AXTDFRMCREATE.

Standardseite
Zuordnung der Datei contact.html.
Die Datei muss auf dem X3-Server liegen und mit der Taste F12 selektiert worden sein.

Protokoll
HTTPS: Verschlüsselung der Daten der HTTP-Abfrage (siehe HTTPS-Konfiguration).

Hauptblock und Hintergrundblock
Keiner

Zugriff geschützt
Nein: Auf die Seite kann frei (anonym) zugegriffen werden.

Rückmeldung Aktivität
Ja: damit jede Seitenanzeige in der Protokolldatei geführt wird.

8. Schritt – Freigabe der Website

Nach der Änderung von X3-Parametern wird empfohlen, die gesamte Website über die Funktion freizugeben, damit das Dictionary des XTEND-Servers über die Funktion Freigabe Website (AYTFCYGEN) neu aufgebaut wird.

Es ist zu prüfen, ob die XTEND-Website veröffentlicht wurde, also ob das Feld 'Website veröffentlicht' auf dem Datenblatt 'Website' aktiviert ist.

HTML-Seite

Link zur Seite

Einfügen des <dynamic link>-Tokens ADLKCONTACT in die Auswahlliste links zur Seitenanzeige und zum Löschen des letzten erstellten Formulars.

<TD class="button"><A adx="ADLKCONTACT">Kontakt</A></TD>

Anzeigeverwaltung

Mit dem Token für bedingte Blöcke CNDXTDFRMHIDE kann das Formular erfasst werden, sofern kein XTEND-Formular gefunden wurde. Wurde ein XTEND-Formular gefunden, wird dessen Inhalt angezeigt.

<!adx="ACNDXTDFRMHIDE">

<!adx="ACNDXTDFRMHIDE">
<!adx="ACNDXTDFRMHIDE:xNot">


<!adx="ACNDXTDFRMHIDE">

Kopfzeilenerfassung

Anlage der <input>-Felder mit dem Token adx="FeldName".

Wird in keinem <input>-Tag ein Name-Attribut angegeben, wird automatisch eines mit dem Namen des adx-Tokens generiert.
Der Parameter xrc(<input adx="TokenName:xrc">) wird verwendet, den letzten erfassten Wert erneut anzuzeigen, falls vom XTEND-Server oder von der X3-Anwendung ein Erfassungsfehler ermittelt wurde.
So gehen die erfassten Daten nicht verloren.

<H1>Kontakt</H1>
<table>
   <tr>
      <td><b><b>E-Mail:</b></td>
      <td>
          <input type="text" adx="MAICOD:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b><b>Betreff:</b></td>
      <td>
          <input type="text" adx="TTL:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b>Nachrichtentext:</b></td>
      <td>
          <textarea adx="CMT:xrc" rows="5" cols="75"></textarea>
      </td>
   </tr>
</table>

Optionserfassung

Anlage der <input>-Feld-Tupel (Schlüssel, Wert). Diese werden auf zwei Spalten eines Tabellenblocks oder auf zwei N-dimensionale Parameter eines Unterprogramms gemappt.

PARVAL enthält den vom Benutzer erfassten Wert
PARDOC enthält den unsichtbaren ('verborgenen') Code

Das Mapping der Tupel (PARCOD, PARVAL) auf die Parameter des Webservice wird in der Reihenfolge der Anlage der Felder in der HTML-Seite durchgeführt.

<tr>
    <td><b>Unternehmen:</b></td>
    <td>
        <input type="Text"   adx="PARVAL:xrc" size="50">
        <input type="hidden" name="PARCOD" value="Unternehmen">
    </td>
</tr>
<tr>
    <td><b>Aktivität:</b></td>
    <td>
        <select adx="PARVAL">
            <option value="">Spezifizieren:</option>
            <option value="Handwerker" >Handwerker</option>
        </select>
        <input type="hidden" name="PARCOD" value="Aktivität">
    </td>
</tr>
<tr>
    <td><b>PLZ:</b></td>
    <td>
        <input type="text"   value="" adx="PARVAL:xrc" size="10">
        <input type="hidden" name="PARCOD" value="PLZ">
    </td>
</tr>

Anlagebutton

Anlage einer Eingabe vom Typ "Button" mit Attribut adx. Dieser Button enthält den Code des dynamischen Links.

Alle <input type="button">-Buttons, die adx-Token enthalten, müssen vom Typ Button sein.
Der Typ 'submit' darf nicht verwendet werden.

Eine Benutzeraktion wird als gültig betrachtet, wenn der Aufruf des Webservice keine Fehlermeldung zurückgibt.

Fehlermeldungen werden in 4GL mit dem Unterprogramm ADDMESSERR (Call ADDMESSERR("Message") From AWEB) ausgegeben.

Die Anzeige der X3-Meldungen wird mit dem Token AXUSERMSG ausgeführt.

Beispiel: <span id="userMsg" class="userMsg" adx="aMsgUser"></span>

Automatische Eingabeprüfung

Da die Felder MAICOD und TTL als obligatorische Webfelder definiert sind, wird die Prüfung automatisch ausgeführt und setzt keinen weiteren JavaScript-Code voraus.

Im Fehlerfall werden die Meldungen AJSWEBFLDMANDAT (Mussfeld) oder AJSWEBFLDBADVAL (Formatfehler) ausgegeben.

Zusätzliche Prüfungen in JavaScript

In JavaScript können weitere Prüfungen der Webparameter hinzugefügt werden. Hierfür ist in die HTML-Seite eine JavaScript-Funktion namens xtdWebParamCheckValue einzufügen.

Findet die XTEND-Bibliothek diese Funktion, wird sie wie folgt aufgerufen:

aWebParamOutl'objet = Parameter

aWebParamOut .setValue(String) = Parameterbelegung
aWebParamOut .getValue() = Rückgabe des Parameterwertes

aInputFieldName = Parametercode
aInputFieldIndex = Index, sofern der Link sich in einem Block befindet
aInputFieldValue = Parameterwert

Die Funktion gibt True oder False zurück.

Im Fehlerfall wird die Meldung AJSWEBFLDBADVAL angezeigt.

Auf der Beispielseite haben wir eine Funktion hinzugefügt, mit der bei E-Mails eine Formatprüfung vorgenommen wird.

Mit der Funktion xtdWebParamCheck werden die zu prüfenden Felder gefiltert.

Die Funktionsweise folgt demselben Prinzip wie die der Funktion xtdWebParamCheckValue.

Kopfzeilenanzeige

Mit dem Block ABLKFRMHEAD kann der Datenkontext positioniert werden.

Die Felder werden mit einem in ein HTML-Tag eingefügten adx-Token angezeigt.

<table width="90%" border="0" cellspacing="2" cellpadding="4">
<!adx="ABLKFRMHEAD">
    <tr>
        <td><b>Email:</b></td>
        <td adx="MAICOD"></td>
    </tr>
    <tr>
        <td><b>Betreff:</b></td>
        <td adx="TTL"></td>
    </tr>
    <tr>
        <td><b>Message:</b></td>
        <td><pre adx="CMT"></pre></td>
    </tr>
<!adx="ABLKFRMHEAD">
</table>

Optionsanzeige

Mit dem Block ABLKFRMPARAM wird über die Formularoptionen iteriert. Es wird für jede Option eine <tr>-Zeile angelegt.

Zu jeder Option positioniert XTEND einen Datenkontext. Damit kann der Wert der in den HTML-Tags platzierten adx-Token PARCOD und PARVAL ausgewertet werden.

<!adx="ABLKFRMPARAM">
    <tr>
        <td><b adx="PARCOD"></b></td>
        <td adx="PARVAL"></td>
    </tr>
<!adx="ABLKFRMPARAM">

JavaScript

Mit dem Eingabepunkt pageDoMyDlk kann eine Verarbeitung per Benutzerklick hinzugefügt werden. Weiterhin kann der laufende Prozess abgebrochen werden, wenn der Wert False zurückgegeben wurde.

Beispiel: Bestätigungsanforderung vor dem Formularversand an den XTEND-Server.

//Asks user to confirm creation of a new form if user clicks on ADLKCONTACTNEW dynamic link
function pageDoMyDlk(aDomOut)
{
    if (aDomOut.isDlk("ADLKCONTACTNEW"))
        return confirm('Formularerstellung bestätigen\nErstellung bestätigen');
    return true;
}

Der Eingabepunkt xtdWebParamCheckValue gehört zur Prüfung der XTEND-Webfeldwerte (Webparameter der XTEND-Aktionen).

Wenn die Funktion xtdWebParamCheckValue in der HTML-Seite definiert ist, wird sie von der XTEND-Bibliothek zwecks 'Webfeldprüfung' aufgerufen.

In unserem Beispiel wird der Wert des Feldes MAICOD (E-Mail) mit der XTEND-Funktion xtdCheckEmail geprüft.

//This function is used to customized control on web parameters values
function xtdWebParamCheckValue(aWebParamOut,aInputFieldName,aInputFieldIndex,aInputFieldValue){
    // Check input email value
    if (aInputFieldName=="MAICOD"){
        var wEmail=xtdCheckEmail(aInputFieldValue);
        if (wEmail && wEmail!=aInputFieldValue)
            aWebParamOut.setValue(aInputFieldIndex,wEmail);
        return wEmail!=null;
    }
    return true;
}