This object contains FORMCYCLE specific utility functions.

Hierarchy

  • XUtil

Index

Properties

Optional onready

onready: function

A callback that is invoked when the form is rendered and completely initialized. This property only lets you set a single callbac. You can also add multiple listeners like this:

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

Type declaration

    • Parameters

      Returns void

ready

ready: boolean

A flag that indicates whether the form is rendered and completly initialized. This is similar to the the onready callback which is invoked when the form becomes ready, but lets you query the status instead.

Methods

getDataQuery

  • Performs an AJAX request to a database query created in the FORMCYCLE backend configuration interface. If the query contains any placeholders (question marks ?), exactly that number of parameters needs to be given or the query fails.

    // Callback when the query succeeded
    function successFunc(data) {
      // Do something with the returned data in JSON format
      console.log(data);
      if (data.length > 0) {
        $('[name=tfName]').val(data[0].name);
      }
    }
    
    // Callback when the query failed
    function errorFunc(jqXHR, textStatus, errorThrown) {
      // Handle error
      console.error(errorThrown);
    }
    
    function getData(paramID, paramMail) {
      $.xutil.getDataQuery('SampleDbQueryName', [paramID, paramMail],
        successFunc, errorFunc);
    }
    
    // Run database query with parameter values taken from form fields
    getData($('[name=tfId]').val(), $('[name=tfMail]').val());

    Parameters

    • queryName: string

      Name of the database query, as set in the FORMCYCLE backend configuration interface.

    • Optional params: Stringifyable[]

      Optional parameters passed to the database query.

    • Optional success: TypeOrArray<SuccessCallback<any>>

      Callback called when the database query succeeds.

    • Optional error: TypeOrArray<ErrorCallback<any>>

      Callback called when the database query fails.

    Returns Promise<object>

    A promise that is fulfilled with the data returned by the database query. Each item in the array corresponds to one row in the database.

getFormParam

  • getFormParam(name: string, defaultValue?: string): string | undefined
  • Retrieves the value of the URL parameter for the given name. Returns the default if no such parameter exists.

    If a parameter name occurs multiple times, all values are returned, separated with a comma (,).

    If the URL is as follows:

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

    Then this function returns:

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

    Parameters

    • name: string

      Name of the URL parameter to retrieve.

    • Optional defaultValue: string

      Default value in case the URL parameter is not set.

    Returns string | undefined

    The value of the given parameter name, or the default value if no such parameter exists.

getFormUrl

  • getFormUrl(name: FormUrlType, defaultValue?: string): string | undefined
  • Finds a FORM-specific URL of a certain type. If you need to access a FORMCYCLE resource, use this function as the URLs may change in future versions.

    The following types of URLs are available:

    • attachment: Base URL for accessing attachments uploaded via upload elements.
    • context: The current context path of the web application, eg. /formcycle.
    • dataquery_db: Base URL for accessing database queries as configured in the FORMCYCLE backend.
    • dataquery_ldap: Base URL for accessing LDAP queries as configured in the FORMCYCLE backend.
    • datasource_csv: Base URL for accessing CSV data sources as configured in the FORMCYCLE backend.
    • datasource_db: (deprecated) Use dataquery_db instead.
    • datasource_json: Base URL for accessing JSON data sources as configured in the FORMCYCLE backend.
    • datasource_xml: Base URL for accessing XML data sources as configured in the FORMCYCLE backend.
    • keepalive: URL for keeping the current session alive. Similar to a ping.
    • plugin: URL for executing servlet plugins.
    • previewAction: URL for requesting a preview of a form. A preview cannot be submitted.
    • submitAction: URL to which the form data is submitted.
    // This returns "/formcycle/datenquellecsv/"
    $.xutil.getFormUrl("datasource_csv", undefined);

    Parameters

    • name: FormUrlType

      Type of the form URL to be retrieved.

    • Optional defaultValue: string

      Default value to be returned when no URL was found.

    Returns string | undefined

    The form URL of the given type. If no such type exists, the given default value.

getLdapQuery

  • Performs an AJAX request to an LDAP query created in the FORMCYCLE backend configuration interface. If the query contains any placeholders (question marks ?), exactly that number of parameters needs to be given or the query fails.

    // Callback when the query succeeded
    function successFunc(data) {
      // Do something with the returned data in JSON format
      console.log(data);
      if (data.length > 0) {
        $('[name=tfName]').val(data[0].name);
      }
    }
    
    // Callback when the query failed
    function errorFunc(jqXHR, textStatus, errorThrown) {
      // Handle error
      console.error(errorThrown);
    }
    
    function getData(paramID, paramMail) {
      $.xutil.getDataQuery('SampleDbQueryName', [paramID, paramMail],
        successFunc, errorFunc);
    }
    
    // Run LDAP query with parameter values taken from form fields
    getData($('[name=tfId]').val(), $('[name=tfMail]').val());

    Parameters

    • queryName: string

      Name of the LDAP query, as set in the FORMCYCLE backend configuration interface.

    • Optional params: Stringifyable[]

      Optional parameters passed to the LDAP query.

    • Optional success: TypeOrArray<SuccessCallback<any>>

      Callback called when the LDAP query succeeds.

    • Optional error: TypeOrArray<ErrorCallback<any>>

      Callback called when the LDAP query fails.

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

    A promise that is fulfilled with the data returned by the database query. Each item in the array corresponds to one entry in the active directory.

isStatus

  • isStatus(stateName: string | undefined): boolean
  • Helper function to check the current state of the form. States can be created and managed in the workflow configuration.

    // When the form is opened for the first time (no state set), set
    // the default value for the form element "tfMail".
    if ($.xutil.isStatus(undefined)) {
       $("[name='tfMail']").val("default@mail.com");
    }
    
    // Check for a certain state
    var isArchived = $.xutil.isStatus("Archived");

    Parameters

    • stateName: string | undefined

      Name of the state to check against the current state. You may pass undefined to check whether no state is set, ie. whether the form has not yet been submitted.

    Returns boolean

    true iff the current state of the form is the same as the given state, false otherwise.

onStatus

  • onStatus(stateName: string | undefined, callback: function): void
  • onStatus(callback: function): void
  • Helper function to run code when the form is currently in a given state. States can be created in the workflow configuration.

    // When the form is opened for the first time (no state set),
    // set the default value for the form element "tfMail"
    $.xutil.onStatus(undefined, function() {
      $("[name='tfMail']").val("default@mail.com");
    });
    
    $.xutil.onStatus('Archiv', function() {
      // Do something when form is archived
    });

    Parameters

    • stateName: string | undefined

      Name of the state to check against the current state. You may pass undefined to check whether no state is set, ie. whether the form has not yet been submitted.

    • callback: function

      Function that is executed immediately (synchronous to the caller) in case the current state of the form matches the given state.

        • (): void
        • Returns void

    Returns void

  • Helper function to run code when the form has got no state currently, ie. when it has not been submitted yet. States can be created in the workflow configuration.

    // When the form is opened for the first time (no state set), set
    // the default value for the form element tfMail.
    $.xutil.onStatus(function() {
      $("[name='tfMail']").val("default@mail.com");
    });

    Parameters

    • callback: function

      Function that is executed immediately (synchronous to the caller) in case the current state of the form matches the given state.

        • (): void
        • Returns void

    Returns void

onsubmit

  • onsubmit(isFormValid: boolean): boolean | undefined
  • A function that is called when the form is submitted. The default implementation simply returns true, so you can override this function without calling the original function. When you would like to cancel the submission of the form, return false from this method.

    $.xutil.onsubmit = function(isFormValid) {
      // Custom code to be run on submission.
      // ...
    
      // Custom logic to check whether the form submission should be cancelled.
       return isFormValid;
    };

    Parameters

    • isFormValid: boolean

      Whether the form is currently valid (eg. if all required fields have been filled out etc.)

    Returns boolean | undefined

    true to proceed with form submission, false or undefined to prevent the form's submission.

parseFloat

  • parseFloat(value: string | undefined): number
  • Parses the given value as a decimal number and returns the value. Accepts both a period and a comma as the decimal separator.

    Parameters

    • value: string | undefined

      Value to parse.

    Returns number

    The string parsed as a number, 0 if undefined was passed.