Interface XUtil

Dieses Objekt enthält FORMCYCLE-spezifische Hilfsfunktionen.

Hierarchy

  • XUtil

Index

Methods

Methods

getDataQuery

  • 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: Stringifyable[]

      Parameter, die an die Datenbankabfrage übergeben werden sollen.

    • Optional success: TypeOrArray<SuccessCallback<any>>

      Rückruffunktion, wenn die Datenbankabfrage erfolgreich war.

    • Optional error: TypeOrArray<ErrorCallback<any>>

      Rückruffunktion, wenn die Datenbankabfrage fehlschlug.

    Returns void

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

  • 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.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.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: Stringifyable[]

      Parameter, die an die LDAP-Abfrage übergeben werden sollen.

    • Optional success: TypeOrArray<SuccessCallback<any>>

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

    • Optional error: TypeOrArray<ErrorCallback<any>>

      Rückruffunktion, wenn die LDAP-Abfrage fehlschlug.

    Returns void

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)) {
 $("[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.

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() {
  $("[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() { $("[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

  • 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;
};

    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.