Dieses Objekt enthält formcycle-spezifische Hilfsfunktionen.

Hierarchy

  • XUtil

Index

Properties

AjaxUploadDialog

AjaxUploadDialog: AjaxUploadDialog

Einfacher modaler Dialog zum Anzeigen ausstehender hochzuladender Dateien.

AjaxUploadManager

AjaxUploadManager: AjaxUploadManager

Hilfsmethoden für die Behandlung zum Hochladen von Dateien über AJAX.

appointmentPicker

appointmentPicker: AppointmentPickerApi

hash

hash: Hash

Hilfsfunktionen zum Arbeiten mit Prüfsummen.

inputElementCounter

inputElementCounter: InputElementCounter

The entry point for the character counter. It adds a simple character to input and textarea elements.

Optional onready

onready: function

Rückruffunktion, welche aufgerufen wird, sobald dass Formular vollständig dargestellt und initialisiert wurde. Über diese Eigenschaft kann nur eine einzelne Rückruffunktion gesetzt werden. Um mehere Rückruffunktionen zu registrieren, kann wie folgt vorgegangen werden:

$("form.xm-form").on("ready", myListener);

Type declaration

    • Parameters

      Returns void

ready

ready: boolean

Eine Flag die angibt, ob das Formular bereits vollständig dargestellt und aktualisiert wurde. Die ist ähnlich zum zur Rückruffunktion onready, welches aufgerufen wird, wenn das Formular fertig ist, lässt einen den Status aber direkt abfragen.

Methods

drawImagePreview

  • drawImagePreview(element: HTMLElement | JQuery, images: keyof PreviewImage[]): void
  • Zeichnet das Vorschaubild für ein Upload-Element.

    Parameters

    • element: HTMLElement | JQuery

      Das Datei-Eingabe-Element mit dem Formularelement zum Hochladen von Dateien.

    • images: keyof PreviewImage[]

      Liste von zu zeichnenden Bildern. Wenn leer, werden die Vorschaubilder entfernt.

    Returns void

getDataQuery

  • getDataQuery(queryName: string, params?: SingleOrArrayLike<undefined | boolean | number | string | Node | JQuery>, success?: JQuery.TypeOrArray<JQuery.Ajax.SuccessCallback<any>>, error?: JQuery.TypeOrArray<JQuery.Ajax.ErrorCallback<any>>): Promise<object>
  • Führt eine Datenbankabfrage per AJAX durch. Datenbankabfragen werden im formcycle-Backend angelegt.

    Wenn die Abfrage Platzhalter (Fragezeichen ?) enthält, muss genau diese Anzahl an Parametern übergeben werden, ansonsten schlägt die Anfrage fehl.

    // Rückruffunktion, wenn Abfrage erfolgreich war
    function successFunc(data) {
      // JSON-Daten aus Rückgabe verarbeiten
      console.log(data);
      if (data.result.length > 0) {
        $('[name=tfName]').val(data.result[0].name);
      }
    }
    
    // Rückruffunktion, wenn Abfrage nicht erfolgreich war
    function errorFunc(jqXHR, textStatus, errorThrown) {
      // Fehler auswerten
      console.error(errorThrown);
    }
    
    function getData(paramID, paramMail) {
      $.xutil.getDataQuery('BeispielAbfrageName', [paramID, paramMail],
        successFunc, errorFunc);
    }
    
    // Datenbankabfrage mit Parametern aus Formularfeldern starten
    getData($('[name=tfId]').val(), $('[name=tfMail]').val());

    Parameters

    • queryName: string

      Name der Datenbankabfrage, wie er im FORMCYCL-Backend konfiguriert wurde.

    • Optional params: SingleOrArrayLike<undefined | boolean | number | string | Node | JQuery>

      Weitere Parameter für die Datenbankabfrage. Kann ein einzelner Wert oder ein Feld von Werten sein, es werden alle angegebenen Wert als Parameter übertragen. Bei undefined wird ein leerer Wert übertragen. Bei einem String wird der String selbst übertragen. Bei Zahlen und Wahrheitswerden wird die String-Repräsentation der Zahl beziehungsweise des Wahrheitswerts übertragen. Bei einer JQuery-Instanz werden die Werte aller HTML-Elemente in der JQuery-Selektion übertragen. Bei einem HTMLElement: (1) wenn es ein Checkbox- oder Radio-Input-Element ist, wird der Wert der Checkbox oder des Radiobuttons übertragen, falls selektiert, (2) wenn es ein File-Input-Element ist, werden die Namen aller Dateien übertragen oder der leere String, falls keine Datei ausgewählt ist, (3) bei anderen Input-Elementen wird der Wert des Input-Elements übertragen, (4) wenn es ein Select- oder Textarea-Element ist, wird der Wert via $.fn.val ermittelt und übertragen, (5) bei anderen Elementen wird nach Kinderelementen vom Type input, textarea und select gesucht und deren Werte übertragen.

    • Optional success: JQuery.TypeOrArray<JQuery.Ajax.SuccessCallback<any>>

      Rückruffunktion, wenn die Datenbankabfrage erfolgreich war.

    • Optional error: JQuery.TypeOrArray<JQuery.Ajax.ErrorCallback<any>>

      Rückruffunktion, wenn die Datenbankabfrage fehlschlug.

    Returns Promise<object>

    Ein Promise, das mit dem Ergebnis der Datenbankabfrage erfüllt wird. Jeder Eintrag in dem Array entspricht einer Zeile im Ergebnis der Datenbankabfrage.

getFormParam

  • getFormParam(name: string, defaultValue?: string): string | undefined
  • Ermittelt den Wert des URL-Parameters mit dem gegebenen Namen. Falls solch ein Parameter nicht existiert, wird der gegebene Rückfallwert zurückgegeben.

    Kommt ein URL-Parametername mehrfach vor, werden alle Wert kommagetrennt (,) zurückgegeben.

    Ist die URL etwa:

    https://formcloud.de/formcycle/form/provide/9999?name=Max&preview&mode=&name=Tom

    Dann verhält sich diese Funktion wie folgt:

    $.xutil.getFormParam("name") // => "Max,Tom"
    $.xutil.getFormParam("preview"); // => undefined
    $.xutil.getFormParam("mode"); // => undefined
    $.xutil.getFormParam("owner", "anonymous"); // => "anonymous"

    Parameters

    • name: string

      Name des zu ermittelnden URL-Parameters.

    • Optional defaultValue: string

      Rückfallwert, falls der URL-Parameter nicht gesetzt ist.

    Returns string | undefined

    Der Wert des gegebenen URL-Parameters oder der Rückfallwert, falls kein solcher Parameter existiert.

getFormUrl

  • getFormUrl(name: FormUrlType, defaultValue?: string): string | undefined
  • Liefert die formcycle-spezifische URL eines bestimmten Typen zurück. Diese Funktion sollte benutzt werden, da sich die konkreten URLs ändern können.

    Die folgenden Arten von URLs gibt es derzeit:

    • attachment: Basis-URL zum Zugreifen auf angehängte Dateien, die mittels Upload-Elementen hochgeladen wurden.
    • context: Der aktuelle Kontextpfad der Anwendung, etwa /formcycle.
    • dataquery_db: Basis-URL zum Zugreifen auf in formcycle konfigurierte Datenbankabfragen.
    • dataquery_ldap: Basis-URL zum Zugreifen auf in formcycle konfigurierte LDAP-Abfragen.
    • datasource_csv: Basis-URL zum Zugreifen auf in formcycle konfigurierte CSV-Datenquellen.
    • datasource_db: (deprecated) Es sollte nun dataquery_db genutzt werden.
    • datasource_json: Basis-URL zum Zugreifen auf in formcycle konfigurierte JSON-Datenquellen.
    • datasource_xml: Basis-URL zum Zugreifen auf in formcycle konfigurierte XML-Datenquellen.
    • keepalive: URL, um die aktuelle Sitzung aufrecht zu erhalten. Eine Art von ping.
    • plugin: URL zum Ausführen von Servlet-Plugins.
    • previewAction: URL zum Erstellen einer Formularvorschau. Solch ein Formular kann nicht abgesendet werden.
    • submitAction: URL, an welche die Formulardaten gesendet werden.
    // Gibt zurück: "/formcycle/datenquellecsv/"
    $.xutil.getFormUrl("datasource_csv", undefined);

    Parameters

    • name: FormUrlType

      Art von URL, die gesucht wird.

    • Optional defaultValue: string

      Rückfallwert, falls die gesuchte URL-Art nicht existiert.

    Returns string | undefined

    Die URL der gesuchten Art. Wenn keine solche Art existiert, der Rückfallwert.

getLdapQuery

  • getLdapQuery(queryName: string, params?: SingleOrArrayLike<undefined | boolean | number | string | Node | JQuery>, success?: JQuery.TypeOrArray<JQuery.Ajax.SuccessCallback<any>>, error?: JQuery.TypeOrArray<JQuery.Ajax.ErrorCallback<any>>): Promise<Record<string, any>[]>
  • Führt eine LDAP-Abfrage per AJAX durch. LDAP-Abfragen werden im formcycle-Backend angelegt.

    Wenn die Abfrage Platzhalter (Fragezeichen ?) enthält, muss genau diese Anzahl an Parametern übergeben werden, ansonsten schlägt die Anfrage fehl.

    // Rückruffunktion, wenn Abfrage erfolgreich war
    function successFunc(data) {
      // JSON-Daten aus Rückgabe verarbeiten
      console.log(data);
      if (data.length > 0) {
        $('[name=tfName]').val(data[0].name);
      }
    }
    
    // Rückruffunktion, wenn Abfrage nicht erfolgreich war
    function errorFunc(jqXHR, textStatus, errorThrown) {
      // Fehler auswerten
      console.error(errorThrown);
    }
    
    function getData(paramID, paramMail) {
      $.xutil.getLdapQuery('BeispielAbfrageName', [paramID, paramMail],
        successFunc, errorFunc);
    }
    
    // LDAP-Abfrage mit Parametern aus Formularfeldern starten
    getData($('[name=tfId]').val(), $('[name=tfMail]').val());

    Parameters

    • queryName: string

      Name der LDAP-Abfrage, wie er im FORMCYCL-BAckend konfiguriert wurde.

    • Optional params: SingleOrArrayLike<undefined | boolean | number | string | Node | JQuery>

      Weitere Parameter für die LDAP-Abfrage. Kann ein einzelner Wert oder ein Feld von Werten sein, es werden alle angegebenen Wert als Parameter übertragen. Bei undefined wird ein leerer Wert übertragen. Bei einem String wird der String selbst übertragen. Bei Zahlen und Wahrheitswerden wird die String-Repräsentation der Zahl beziehungsweise des Wahrheitswerts übertragen. Bei einer JQuery-Instanz werden die Werte aller HTML-Elemente in der JQuery-Selektion übertragen. Bei einem HTMLElement: (1) wenn es ein Checkbox- oder Radio-Input-Element ist, wird der Wert der Checkbox oder des Radiobuttons übertragen, falls selektiert, (2) wenn es ein File-Input-Element ist, werden die Namen aller Dateien übertragen oder der leere String, falls keine Datei ausgewählt ist, (3) bei anderen Input-Elementen wird der Wert des Input-Elements übertragen, (4) wenn es ein Select- oder Textarea-Element ist, wird der Wert via $.fn.val ermittelt und übertragen, (5) bei anderen Elementen wird nach Kinderelementen vom Type input, textarea und select gesucht und deren Werte übertragen.

    • Optional success: JQuery.TypeOrArray<JQuery.Ajax.SuccessCallback<any>>

      Rückruffunktion, wenn die LDAP-Abfrage erfolgreich war.

    • Optional error: JQuery.TypeOrArray<JQuery.Ajax.ErrorCallback<any>>

      Rückruffunktion, wenn die LDAP-Abfrage fehlschlug.

    Returns Promise<Record<string, any>[]>

    Ein Promise, das mit dem Ergebnis der LDAP-Abfrage erfüllt wird. Jeder Eintrag in dem Array entspricht einem Eintrag, der vom Active Directoy zurückgeliefert wird.

isStatus

  • isStatus(stateName: string | undefined): boolean
  • Hilfsfunktion, um den aktuellen Status des Formulars zu überprüfen. Status können in der Verarbeitung des Formulars angelegt und konfiguriert werden.

    // Wird das Formular zum ersten Mal geöffnet (kein Status gesetzt),
    // setze den Default-Wert für das Formularelement "tfMail"
    if ($.xutil.isStatus(undefined)) {
     $("[data-name='tfMail']").val("default@mail.com");
    }
    
    // Auf einen bestimmten Status prüfen
    var isArchived = $.xutil.isStatus("Archiv");

    Parameters

    • stateName: string | undefined

      Name des Status, gegen den der aktuelle Status verglichen wird. undefined kann übergeben werden, um zu prüfen, ob kein Status gesetzt ist, das Formular also noch nicht abgesendet wurde.

    Returns boolean

    true, falls der aktuelle Status des Formular mit dem übergebenen übereinstimmt, ansonsten false.

load

  • Lädt gespeicherte Daten in das Formular und füllt alle Formularelemente mit den gespeicherten Werten.

    Im Vergleich zu loadFromString verwendet diese Methode das Objekt anstelle eines serialisierten Strings.

    Parameters

    Returns void

loadFromString

  • loadFromString(data: string): void
  • Lädt gespeicherte Daten in das Formular und füllt alle Formularelemente mit den gespeicherten Werten.

    Im Vergleich zu load verwendet diese Methode die serialisierte Zeichenkette anstelle eines Objekts.

    Parameters

    • data: string

      Gespeicherte Daten, wie sie von saveAsString zurückgegeben werden.

    Returns void

off

  • off<K>(event: K, eventCallback: XUtilCallbacks[K]): void
  • Removes an event callback previously added via on.

    Type parameters

    • K: keyof XUtilCallbacks

      Type of the event name for which to remove a listener.

    Parameters

    • event: K

      Name of the event to for which to remove a listener.

    • eventCallback: XUtilCallbacks[K]

      Listener to remove.

    Returns void

offSubmit

  • Entfernt eine Rückruffunktion die per onSubmit hinzugefügt wurde.

    deprecated

    Nutze $.xutil.off("submit")

    Parameters

    Returns void

on

  • on<K>(event: K, eventCallback: XUtilCallbacks[K]): Disposable
  • Register a callback function for one of the events issued during the lifecycle of a form.

    Uncaught errors in callbacks are caught, logged, and ignored otherwise.

    Type parameters

    • K: keyof XUtilCallbacks

      Type of the event name for which to register a listener.

    Parameters

    • event: K

      Name of the event to listen to.

    • eventCallback: XUtilCallbacks[K]

      Listener that is invoked when the event occurs.

    Returns Disposable

    A disposable that can be used to remove the listener.

onPrint

  • onPrint(callback: function): void
  • Registriert eine Rückruffunktion für den Druckdienst. Die Rückruffunktion wird durch den Druckdienst gerufen, bevor das Formular gedruckt wird. Diese Rückruffunktion kann verwendet werden, um das Formular für den Druck vorzubereiten. Wenn die Rückruffunktion ein Versprechen zurückliefert, wartet der Druckdienst mit dem Drucken, bis das Versprechen erfüllt wurde. Wird das Versprechen gebrochen, so wird der Fehler protokolliert, verhindert aber das Drucken nicht.

    deprecated

    Nutze $.xutil.on("print")

    Parameters

    • callback: function

      Rückruffunktion, die registriert werden soll.

        • (): void | Promise<void>
        • Returns void | Promise<void>

    Returns void

onReadyStateComplete

  • onReadyStateComplete(callback: function): void
  • Ruft die gegebene Rückruffunktion, sobald {@link document.readyState} sich zu complete ändert. Falls der Bereitschaftszustand bereits complete ist, wird die Rückruffunktion unverzüglich ausgeführt (aber immer noch asynchron in einer der nächsten Zyklen der Ereignisschleife).

    Diese Funktion ist ählich zu der Bereitsschaftszustandsfunktion von JQuery ($(function() { })). Diese Funktion verwendet aber DOMContentLoaded und führt daher die Rückruffunktion möglicherweise bereits aus, wenn der Bereitschaftszustand noch loading ist. Wenn es erforderlich, zu warten, bis das Dokument vollständig geladen ist, sollte diese Funktion verwendet werden.

    Falls beispielsweise eine Berechnung ausgeführt werden soll, die von der Höhe oder Breite eines Elements Gebrauch macht, kann das Resultat sich unterscheiden, wenn der Bereitschaftszustand des Dokuments noch loading ist, da zu diesem Zeitpunkt Gestaltungsbögen oder Schriftarten noch nicht geladen sein können.

    Parameters

    • callback: function

      Rückruffunktion, welche ausgeführt wird, sobald der Bereitschaftszustand des Dokuments sich zu complete ändert.

        • (): void
        • Returns void

    Returns void

onStatus

  • onStatus(stateName: string | undefined, callback: function): void
  • onStatus(callback: function): void
  • Hilfsfunktion, um Code auszuführen, wenn sich das Formular in einem bestimmten Status befindet. Status können in der Verarbeitung des Formulars angelegt und konfiguriert werden.

    // Wird das Formular zum ersten Mal geöffnet (kein Status gesetzt),
    // setze den Default-Wert für das Formularelement tfMail
    $.xutil.onStatus(undefined, function() {
      $("[data-name='tfMail']").val("default@mail.com");
    });
    
    $.xutil.onStatus('Archiv', function() {
    // Etwa tun, wenn Formular archiviert ist
    });

    Parameters

    • stateName: string | undefined

      Name des Status, gegen den der aktuelle Status verglichen wird. undefined kann übergeben werden, um zu prüfen, ob kein Status gesetzt ist, das Formular also noch nicht abgesendet wurde.

    • callback: function

      Funktion, die unmittelbar (synchron zum Aufruf) ausgeführt wird, falls der übergebene Statusname dem aktuellen Status des Formulars entspricht.

        • (): void
        • Returns void

    Returns void

  • Hilfsfunktion, um Code auszuführen, wenn das Formular noch keinen Status hat, also noch nicht abgesendet wurde. Status können in der Verarbeitung des Formulars angelegt und konfiguriert werden.

    // Wird das Formular zum ersten Mal geöffnet (kein Status gesetzt), setze den Default-Wert für das
    // Formularelement tfMail
    $.xutil.onStatus(function() { $("[data-name='tfMail']").val("default@mail.com"); });

    Parameters

    • callback: function

      Funktion, die unmittelbar (synchron zum Aufruf) ausgeführt wird, falls der übergebene Statusname dem aktuellen Status des Formulars entspricht.

        • (): void
        • Returns void

    Returns void

onSubmit

  • Registriert eine Rückruffunktion, wenn das Formular abgeschickt wird. Kann z.B. verwendet werden, um zusätzliche Aktionen auszuführen oder das Absenden zu verhindern.

    Die Rückruffunktion wird aufgerufen, nachdem das Formular validiert wurde, wenn der Submit-Button eine Validierung erfordert.

    $.xutil.onSubmit(() => doSomething())
    
    $.xutil.onSubmit(({submissionBlocked}) => {
      // Check if the submission is already blocked
      if (submissionBlocked) {
        return;
      }
    
      // Benutzerdefinierter Code, der bei der Übermittlung ausgeführt wird
      // Benutzerdefinierte Logik, um zu prüfen, ob die Formularübermittlung abgebrochen werden soll.
       const preventSubmission = customLogic();
    
       return { preventSubmission };
    });
    deprecated

    Nutze $.xutil.on("submit")

    Parameters

    • callback: OnSubmitCallback

      Rückruffunktion, die aufgerufen wird, wenn das Formular abgeschickt werden soll.

    Returns Disposable

    Ein Disposable, das zum Entfernen der Rückruffunktion verwendet werden kann. Dies ist gleichbedeutend mit dem Aufruf von offSubmit mit der Rückruffunktion, die an diese Methode übergeben wird.

onsubmit

  • onsubmit(isFormValid: boolean): boolean | undefined
  • Eine Funktion, welche aufgerufen wird, bevor das Formular abgesendet wird. Die Standardimplementierung dieser Funktion liefert einfach nur true zurück. Diese Funktion kann also überschrieben werden, ohne die ursprüngliche Funktion aufzurufen. Um das Absenden des Formulars zu verhindern, kann in dieser Funktion der Wert false zurückgegeben werden.

    $.xutil.onsubmit = function(isFormValid) {
      // Eigener Code vor dem Absenden.
      // ...
    
      // Eigene Logik zum Prüfen, ob das Absenden verhindert werden soll.
      return isFormValid;
    };
    deprecated

    Nutze $.xutil.on("submit")

    Parameters

    • isFormValid: boolean

      Ob das Formular derzeit valide ist (z.B. ob alle Mussfelder ausgefüllt sind).

    Returns boolean | undefined

    true um mit dem Absenden fortzufahren, false oder undefined um das Absenden abzubrechen.

parseFloat

  • parseFloat(value: string | undefined): number
  • Interpretiert die Zeichenketter als Kommazahl und liefert diese zurück. Akzeptiert sowohl einen Punkt als auch ein Komma als Dezimaltrennzeichen.

    Parameters

    • value: string | undefined

      Zeichenkette, die als Zahl interpretiert werden soll.

    Returns number

    Die Zeichenkette interpretiert als Zahl, 0 falls undefined übergeben wurde.

save

  • Erzeugt ein Objekt mit allen Daten aus dem aktuellen Formular, einschließlich aller wiederholten Formularfelder und aller hochgeladenen Dateien.

    Im Vergleich zu save wird hier ein Objekt statt einer serialisierten Zeichenkette zurückgegeben.

    Returns LegacyFormSaveData

    Ein Objekt mit den Formulardaten.

saveAsString

  • saveAsString(): string
  • Erzeugt eine Zeichenkette mit einer serialisierten Darstellung aller Daten aus dem aktuellen Formular, einschließlich aller wiederholten Formularfelder und aller hochgeladenen Dateien.

    Im Vergleich zu save wird hier eine serialisierte Zeichenkette anstelle eines Objekts zurückgegeben.

    Returns string

    Eine serialisierte Zeichenkette mit den Formulardaten.

trigger

  • trigger<K>(event: K, eventData: Parameters<XUtilCallbacks[K]>): ReturnType<XUtilCallbacks[K]>[]
  • Fires an event of the given types, invoking all listeners that were registered via on.

    Type parameters

    • K: keyof XUtilCallbacks

      Type of the event name to trigger.

    Parameters

    • event: K

      Name of the event.

    • eventData: Parameters<XUtilCallbacks[K]>

      Data to pass to the event listeners.

    Returns ReturnType<XUtilCallbacks[K]>[]