HTML5-Formulare geben XFA-Vorlagen im Browser im HTML5-Format aus. In HTML5-Formularen werden Bibliotheken von jQuery, Backbone.js und Underscore.js für die Darstellung und Skripterstellung verwendet. Die Formulare verwenden auch die Architektur von jQuery UI Widgets für alle interaktiven Elemente (beispielsweise Felder und Schaltflächen) im Formular. Alle Widget-Elemente in den XFA-Feldelementen haben ein zugeordnetes jquery-Widget. Durch diese Architektur stehen Formularentwicklern eine umfangreiche Auswahl von jQuery-Widgets und -Plug-Ins in Formularen zur Verfügung. Sie können ebenfalls XFA-spezifische Logik beim Erfassen von Benutzerdaten implementieren, wie etwa „leadDigits/trailDigits“-Einschränkungen, oder Bildklassen implementieren. Formularentwickler können benutzerdefinierte Widgets erstellen und verwenden, um die Datenerfassungserfahrung zu verbessern und sie benutzerfreundlicher zu gestalten.

Dieser Artikel richtet sich an Entwickler mit genügend Wissen zu jQuery und jQuery-Widgets. 

Um ein Widget in HTML5-Formulare einzubinden, sind folgende Voraussetzungen nötig: 

  • HTML5-Formulare stellen einen Optionssatz für alle Widgets eines Felds bereit. Diese Optionen sind Schlüssel-Wert-Paare und in zwei Kategorien unterteilt: „Allgemeine Optionen“ und „Feldtypspezifische Optionen“.
  • Das Widget löst als Teil des Kontrakts eine Reihe von XFA-Ereignissen wie „enter“, „exit“ und so weiter aus.
  • Das Widget muss einen Satz Funktionen implementieren; einige der Funktionen sind allgemein und einige sind feldtypspezifisch.

Allgemeine Optionen

Im Folgenden die globalen Optionen. Diese Optionen sind für jedes Feld verfügbar. 

Eigenschaft Beschreibung
nameGibt einen Bezeichner an, mit dem dieses Objekt oder Ereignis in Skriptausdrücken angegeben wird. Diese Eigenschaft gibt beispielsweise den Namen der Host-Anwendung an.
valueTatsächlicher Wert des Felds. In der XFA-Terminologie ist die Eigenschaft „value“ das „rawValue“ des Felds.
displayValueDer Wert des Felds wird angezeigt. In der XFA-Terminologie ist die Eigenschaft „displayValue“ das „formattedValue“ des Felds.
screenReaderTextBildschirmlesehilfen verwenden diesen Wert, um Informationen über das Feld vorzulesen. Das XFA-Formular gibt den Wert an. Sie können diesen Wert überschreiben.
tabIndexDie Position des Felds in der Tab-Abfolge des Formulars. Überschreiben Sie den tabIndex nur, wenn Sie die Standardreihenfolge der Registerkarten im Formular ändern möchten.
roleRolle des Elements, z. B. Überschrift oder Tabelle.
heightHöhe des Widgets. Die Höhe wird in Pixeln angegeben. 
widthBreite des Widgets. Die Höhe wird in Pixeln angegeben.
accessSteuert den Benutzerzugriff auf den Inhalt eines Containers, beispielsweise ein Teilformular.
paraStylesPara-Eigenschaft eines XFA-Elements für das Widget
dirTextrichtung. Mögliche Werte sind: ltr (links nach rechts) und rtl (rechts nach links).

Zusätzlich zu diesen Optionen stehen in HTML5-Formularen einige weitere Optionen zur Verfügung, die je nach Typ des Felds variieren. Die Details zu den feldspezifischen Optionen sind unten aufgeführt.

Interaktion mit HTML5-Formularen

Um mit HTML5-Formularen zu interagieren, löst ein Widget einige Ereignisse aus, die das Formularskript aktivieren. Wenn das Widget diese Ereignisse nicht erzeugt, dann funktionieren einige der Skripte nicht, die im Formular für dieses Feld eingegeben wurden.

Auszulösende Ereignisse

Ereignis Beschreibung
XFA_ENTER_EVENT
Das Ereignis wird ausgelöst, wenn das Widget im Fokus ist. Dadurch kann Skript „eingegeben“ werden, der im Feld ausgeführt wird. Die Syntax zum Auslösen des Ereignisses ist
(Widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_ENTER_EVENT)

XFA_EXIT_EVENT
Dieses Ereignis wird ausgelöst, wenn der Benutzer das Widget verlässt. Dadurch kann die Engine den Wert des Feldes festlegen und ihr „exit“-Skript ausführen. Die Syntax zum Auslösen des Ereignisses ist
(Widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_EXIT_EVENT)

XFA_CHANGE_EVENT
Das Ereignis wird ausgelöst, damit die Engine ihr „change“-Skript ausführen kann, das für das Feld eingegeben wurde. Die Syntax zum Auslösen des Ereignisses ist
(Widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)

XFA_CLICK_EVENT
Das Ereignis wird ausgelöst, wenn das Widget angeklickt wird. Dadurch kann die Engine das „click“-Skript ausführen, das für das Feld eingegeben wurde. Die Syntax zum Auslösen des Ereignisses ist
(Widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

Zu implementierende APIs

HTML5-Formulare rufen einige Funktionen des Widgets auf, die in den benutzerdefinierten Widgets implementiert sind. Die folgenden Funktionen werden durch das Widget implementiert:

FunktionBeschreibung
focus : function()Fokus wird auf das Widget gelegt.
click : function()Fokus wird auf das Widget gelegt und XFA_CLICK_EVENT wird aufgerufen.

markError:function(errorMessage, errorType)

erorrMessage: string steht für den Fehler
errorType: string (“warning”/”error”)

Diese Funktion sendet Fehlermeldung und Fehlertyp an das Widget. Das Widget zeigt den Fehler an.
clearError: function()Wenn die Fehler im Feld behoben sind, wird diese Funktion aufgerufen. Das Widget ist dafür zuständig, den Fehler auszublenden.

Optionen je nach Feldtyp

Alle benutzerdefinierten Widgets sollten mit den oben genannten Spezifikationen übereinstimmen. Um die Funktionen von verschiedenen Feldern zu nutzen, muss das Widget den Richtlinien des jeweiligen Felds entsprechen.

TextEdit: Text Field

OptionBeschreibung
multiLine„True“, wenn das Feld die Eingabe eines Zeilenumbruchzeichens unterstützt, andernfalls „false“.
maxCharsMaximale Anzahl der Zeichen, die in das Feld eingegeben werden können.
limitLengthToVisibleAreaGibt das Verhalten des Textfelds an, wenn die Textbreite die Breite des Widgets überschreitet.

ChoiceList: DropDownList, ListBox

OptionBeschreibung
value
Array der ausgewählten Werte.
items
Array von Objekten, die als Optionen angezeigt werden sollen. Jedes Objekt enthält zwei Eigenschaften:
„save“ (zu speichernder Wert), „display“ (anzuzeigender Wert).

editable
„True“: Die Eingabe von benutzerdefiniertem Text im Widget wird aktiviert.
displayValue
Anzuzeigendes Werte-Array.
multiselect
„True“, wenn Mehrfachauswahlen zulässig sind, andernfalls „false“.

API

FunktionBeschreibung

addItem: function(itemValues)
itemValues: Objekt, das die Werte für „display“ und „save“ enthält
{sDisplayVal: , sSaveVal: }

Fügen Sie einen Artikel zur Liste hinzu.
deleteItem: function(nIndex)
nIndex: Index des Elements, das aus der Liste entfernt werden soll


Eine Option aus der Liste löschen.
clearItems: function() Alle Optionen aus der Liste löschen.

NumericEdit: NumericField, DecimalField

OptionenBeschreibung
dataTypeString, der, der den Datentyp des Felds darstellt (ganze Zahl/Dezimalzahl/Feld).
leadDigitsMaximale führende Ziffern der Dezimalzahl.
fracDigitsMaximale Bruchzahlen in der Dezimalzahl.
zeroDie Zeichenfolgendarstellung von Null im Gebietsschema des Felds.
decimalDie Zeichenfolgendarstellung von Dezimalzahlen im Gebietsschema des Felds.

CheckButton: RadioButton, CheckBox

OptionenBeschreibung
Werte

Werte-Array(an/aus/neutral).

Werte-Array für die verschiedenen Statusangaben des CheckButton. Wert[0] steht für den Status AN, Wert[1] steht für den Status AUS,
Wert[2] steht für den Status NEUTRAL. Die Länge des Werte-Arrays entspricht dem Wert der Status-Option.

statesZahl der zulässigen Zustände. 3, wenn neutral zulässig ist, andernfalls 2.
stateAktueller Status des Elements (0: an, 1: aus, 2: neutral).

DateTimeEdit: (DateField)

OptionBeschreibung
Tage Lokalisierte Tagesnamen für dieses Feld.
months Lokalisierte Monatsnamen für dieses Feld.
zero Der lokalisierte Text für die Zahl 0.
clearText Der lokalisierte Text für die Schaltfläche „Löschen“.

Registrieren von benutzerdefinierten Widgets mit XFA Scripting Engine

Wenn der benutzerdefinierte Widget-Code fertig ist, registrieren Sie das Widget bei der Skriptengine, indem Sie die registerConfig -API für Form Bridge verwenden. Als Eingabe ist „widgetConfigObject“ erforderlich.

 

window.formBridge.registerConfig("widgetConfig" , widgetConfigObject);

widgetConfigObject

Die Widget-Konfiguration wird als JSON-Objekt bereitgestellt (eine Sammlung von Schlüssel-Wert-Paaren), bei dem der Schlüssel die Felder identifiziert und der Wert für das Widget steht, das mit den Feldern verwendet werden soll. Eine Beispielkonfiguration sieht wie folgt aus:

{

“identifier1” : “customwidgetname”,
“identifier2” : “customwidgetname2”,
..
}

Hierbei ist der Bezeichner „identifier“ ein jQuery CSS-Selektor, der für ein bestimmtes Feld, eine Gruppe von Feldern eines bestimmten Typs oder alle Felder steht. Im Folgenden ist der Wert des Bezeichners in verschiedenen Fällen aufgeführt:

Typ des BezeichnersBezeichner Beschreibung
Bestimmtes Feld mit Name „fieldname“Bezeichner:"div.fieldname"Alle Felder mit dem Namen „fieldname“ werden mithilfe des Widgets gerendert.
Alle Felder des Typs „type“ („type“ ist hier NumericField, DateField usw.):Bezeichner: "div.type"Für „TimeField“ und „DateTimeField“ ist der Typ „textfield“, da diese Felder noch nicht unterstützt werden.
Alle FelderBezeichner: "div.field"

Dieses Werk unterliegt den Bedingungen der Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.  Twitter™- und Facebook-Beiträge fallen nicht unter die Bedingungen der Creative Commons-Lizenz.

Rechtliche Hinweise   |   Online-Datenschutzrichtlinie