Interface JQuery

Hierarchy

  • JQuery

Index

Methods

addStar

  • addStar(): JQuery
  • Adds the little red star icon to the label of this form field that indicates whether the form field is a required field.

    Currently this icon is a SPAN element with the class required-star. Note that this is subject to change.

    <span class="required-star">*</span>

    For example:

    // Adds a star to the label of the form field tf1.
    $('input[name="tf1"]').addStar()

    This function only changes its appearance, but does not make the form field a required field. To set whether a form field is required, use the function setRequired.

    Returns JQuery

    This JQuery instance for chaining.

autoNumeric

  • autoNumeric(options?: Partial<ValueOrSupplier<InitOptions>>): JQuery
  • autoNumeric(method: "destroy"): JQuery
  • autoNumeric(method: "get"): string
  • autoNumeric(method: "getArray"): object[]
  • autoNumeric(method: "getSettings"): InitOptions
  • autoNumeric(method: "getString"): string
  • autoNumeric(method: "init", options?: Partial<ValueOrSupplier<InitOptions>>): JQuery
  • autoNumeric(method: "set", number: string | number): JQuery
  • autoNumeric(method: "update", options: Partial<ValueOrSupplier<InitOptions>>): JQuery
  • Initializes autoNumeric. Must be run before other methods can be called. This method should only be used with text input fields.

    autoNumeric is a JavaScript library for entering and formatting numbers in a language and country dependent way. This library is already included in all forms and may be used directly in the JavaScript tab of the designer. See the official web presence for more information.

    First you need to select an input field with jQuery. Then you can pass the desired options to autoNumeric as follows:

    $("[name=tfWeight]").autoNumeric("init", {
      aDec: '.', // Use a period as a decimal separator
      aSep: '', // No separator for thousands
      aSign: ' kg', // Unit kg
      pSign: 's', // Place the unit after the number
      vMin: 1, // Must enter at least a value of 1
      vMax: 100, // Must enter a value less than 100
      mDec: 3, // At most 3 digits after the period
      aPad: false // May be less than 3 decimal digits
      // more options...
    });

    Now the user can enter a number like 3,99 in the text field tfGewicht. This is then displayed as 3,99 kg. autoNumeric ensures that only valid number can be entered.

    Some common options include:

    • aDec: Decimal separator
    • aSep: Separator for thousand (such as 12,658)
    • aSign: Unit to show before or after the number, such as EUR or ¥.
    • pSign: Whether the unit should be place at the beginning (value s) or at the end (value p)
    • vMin: Smallest allowed numerical value
    • vMax: Largets allowed numerical value
    • mDec: Maximum number of digits after the period
    • aPad: When set to true, always pad the decimal digits with 0s (such as 2,3400)

    Parameters

    Returns JQuery

    This JQuery instance for chaining.

  • Stops autoNumeric.

    Parameters

    • method: "destroy"

    Returns JQuery

    This JQuery instance for chaining.

  • Retrieves the actual numerical value, irrespective of the current formatting options.

    Parameters

    • method: "get"

    Returns string

    The current value, formatted as nnnn.nn with the period as the decimal point.

  • This basically uses jQuery's `serializeArray method which returns a JavaScript array of objects, ready to be encoded as a JSON string.

    Parameters

    • method: "getArray"

    Returns object[]

    The values, always formatted as 'nnnn.nn' with the period as the decimal point.

  • Parameters

    • method: "getSettings"

    Returns InitOptions

    The autoNumeric settings for this field. You may find this helpful when developing a page.

  • This basically uses jQuery's .serialize() method which creates a text string (URL-encoded notation) from a set of form elements that is ready for submission. The extra step taken here is the string is split and iterated through and the formatted values are replaced with unformatted values. The string is then joined back together and returned.

    Parameters

    • method: "getString"

    Returns string

    The values, always formatted as 'nnnn.nn' with the period as the decimal point.

  • Initializes autoNumeric Must be run before other methods can be called.

    Parameters

    Returns JQuery

    This JQuery instance for chaining.

  • Sets the given number on this field, and formats it according to the current options.

    Parameters

    • method: "set"
    • number: string | number

      The new number to be set on this field.

    Returns JQuery

    This JQuery instance for chaining.

  • Updates autoNumeric's settings.

    Parameters

    Returns JQuery

    This JQuery instance for chaining.

autocompleteDB

  • autocompleteDB(queryName: string, label?: string, onSelect?: function): JQuery
  • autocompleteDB(queryName: string, label: string, value: string, onSelect?: function, params?: Stringifyable[]): JQuery
  • Should be used only on text input fields.

    Sets up autocompletion for this text input field, with the available options taken from a database query. The user is then shown a list of possible options as they type.

    The database query is run by making an AJAX request. Database queries are configured within the XIMA FORMCYCLE backend.

    The specified column name is used as the label for the option that is displayed to the user; and also as the value that is transmitted when the user submits the form. This function restricts the query to the specified column. This reduces the amount of data that needs to be transmitted and speeds up loading when dealing with large database tables.

    The database query must contain exactly one free parameter specified by a question mark ?. This parameter is replaced with the text the user types in the input field. Please note that you do not need to use quotation marks or escape sequences, as the database query uses prepared statements.

    Example with countries

    Assume a database query was created in the backend named CountryByName. The query might look like this:

    SELECT code, en FROM demo.countries where en like concat('%',?,'%');

    You can use this query with a text input field named tfCountry:

    $('[name="tfCountry"]').autocompleteDB("CountryByName", "en");

    Now, for example, when the user enters the text An, the database query returns all countries with a name that starts with An. The user is presented with the matching options and can choose one of Andorra, Angola, Anguilla, Antarctica, or Antigua and Barbuda.

    Example with callback

    function setCode(event, ui){
      $('[name=tfCountryCode]').val(ui.item.code)
    }
    $('[name=tfCountries]').autocompleteDB("CountryByName", "en", setCode);

    As in the previous example, autocomplete gets initialised with a list of countries. In addition, a function is called each time when the user selects a country. This function accesses the selected element (ui.item) and reads the value of the column code (ui.item.code). This value corresponds to the code column of the database query. Finally, this country code is written to the input field named tfCountry and is now available for further processing.

    Parameters

    • queryName: string

      Name of the database query. Database queries can be created in the backend of XIMA FORMCYCLE.

    • Optional label: string

      Name of a database column. This is used as the label displayed to the user.. This is used as both the displayed label and the value that is transmitted when the form is submitted.

    • Optional onSelect: function

      The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.

        • (this: JQuery, event: Event, ui: object): void
        • Parameters

          • this: JQuery
          • event: Event
          • ui: object
            • item: object
              • optionLabel: string
              • optionValue: string

          Returns void

    Returns JQuery

    This JQuery instance for chaining.

  • Should be used only on text input fields.

    Sets up autocompletion for this text input field, with the available options taken from a database query. The user is then shown a list of possible options as they type.

    The database query is run by making an AJAX request. Database queries are configured within the XIMA FORMCYCLE backend.

    You can specify two column names. One column is used as the label for the option that is displayed to the user. The other column is used as the value that is transmitted when the user submits the form. This function restricts the query to the two specified column. This reduces the amount of data that needs to be transmitted and speeds up loading when dealing with large database tables.

    The database query must contain exactly at least one free parameter specified by a question mark ?. This parameter is replaced with the text the user types in the input field. Please note that you do not need to use quotation marks or escape sequences, as the database query uses prepared statements. If the query contains more parameters, the remaining parameters must be given or the query fails.

    Example with countries

    Assume a database query was created in the backend named CountryByName. The query might look like this:

    SELECT code, en FROM demo.countries where en like concat('%',?,'%');

    You can use this query with a text input field named tfCountry:

    $('[name="tfCountry"]').autocompleteDB("CountryByName", "en");

    Now, for example, when the user enters the text An, the database query returns all countries with a name that starts with An. The user is presented with the matching options and can choose one of Andorra, Angola, Anguilla, Antarctica, or Antigua and Barbuda.

    Example with callback

    function setCode(event, ui){
      $('[name=tfCountryCode]').val(ui.item.code)
    }
    $('[name=tfCountries]').autocompleteDB("CountryByName", "en", setCode);

    As in the previous example, autocomplete gets initialised with a list of countries. In addition, a function is called each time when the user selects a country. This function accesses the selected element (ui.item) and reads the value of the column code (ui.item.code). This value corresponds to the code column of the database query. Finally, this country code is written to the input field named tfCountry and is now available for further processing.

    Parameters

    • queryName: string

      Name of the database query. Database queries can be created in the backend of XIMA FORMCYCLE.

    • label: string

      Name of a database column. This is used as the label displayed to the user.

    • value: string

      Name of a database column. This is used as the value that is transmitted.

    • Optional onSelect: function

      The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.

        • (event: Event, ui: object): void
        • Parameters

          • event: Event
          • ui: object
            • item: object
              • optionLabel: string
              • optionValue: string
            • this: JQuery

          Returns void

    • Optional params: Stringifyable[]

      Additional parameters for the database query.

    Returns JQuery

    This JQuery instance for chaining.

autocompleteLDAP

  • autocompleteLDAP(queryName: string, label?: string, onSelect?: function): JQuery
  • autocompleteLDAP(queryName: string, label: string, value: string, onSelect?: function, params?: Stringifyable[]): JQuery
  • Should be used only on text input fields.

    Sets up autocompletion for this text input field, with the available options taken from an LDAP (Lightweight Directory Access Protocol) query. The user is then shown a list of possible options as they type.

    The LDAP query is run by making an AJAX request. Database queries are configured within the XIMA FORMCYCLE backend.

    The specified LDAP property is used as the label for the option that is displayed to the user; and also as the value that is transmitted when the user submits the form. This function restricts the query to the specified properties. This reduces the amount of data that needs to be transmitted and speeds up loading.

    The LDAP query must contain exactly one free parameter specified by a question mark ?. This parameter is replaced with the text the user types in the input field.

    Example

    Assume an LDAP query was created in the backend named Employees. The query might look like this:

    BaseDN: ou="employees", ou="company", dc="company", dc="com"
    Query : (userPrincipalName=*?*)

    Then, to use this query with a text input field named tfEmployees:

    $('[name="tfEmployees"]').autocompleteLDAP("Employees", "name.full");

    Now when the user enters the text John, the LDAP query returns all employees whose name contains John; and the user is presented with these options: John Smith, John Davis, John Brown.

    Parameters

    • queryName: string

      Name of the LDAP query. LDAP queries can be created in the backend of XIMA FORMCYCLE.

    • Optional label: string

      Name of an LDAP property. Defaults to label. This is used as both the label displayed to the user and the value that is transmitted when the form is submitted. To specify a nested property, separate the keys with a period, eg. name.full or location.city.

    • Optional onSelect: function

      The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.

        • (this: JQuery, event: Event, ui: object): void
        • Parameters

          • this: JQuery
          • event: Event
          • ui: object
            • item: object
              • optionLabel: string
              • optionValue: string

          Returns void

    Returns JQuery

    This JQuery instance for chaining.

  • Should be used only on text input fields.

    Sets up autocompletion for this text input field, with the available options taken from an LDAP (Lightweight Directory Access Protocol) query. The user is then shown a list of possible options as they type.

    The LDAP query is run by making an AJAX request. Database queries are configured within the XIMA FORMCYCLE backend.

    You can specify two LDAP properties. One property is used as the label for the option that is displayed to the user. The other property is used as the value that is transmitted when the user submits the form. This function restricts the query to the two specified properties. This reduces the amount of data that needs to be transmitted and speeds up loading.

    The LDAP query must contain exactly at least one free parameter specified by a question mark ?. This parameter is replaced with the text the user types in the input field. If the query contains more parameters, the remaining parameters must be given or the query fails.

    Example

    Assume an LDAP query was created in the backend named Employees. The query might look like this:

    BaseDN: ou="employees", ou="company", dc="company", dc="com"
    Query : (userPrincipalName=*?*)

    Then, to use this query with a text input field named tfEmployees:

    $('[name="tfEmployees"]').autocompleteLDAP("Employees", "name.full", "accountName");

    Now when the user enters the text John, the LDAP query returns all employees whose name contains John; and the user is presented with these options: John Smith, John Davis, John Brown. The user is shown the full name of the employee, their account name is used when the form is submitted.

    Parameters

    • queryName: string

      Name of the LDAP query. LDAP queries can be created in the backend of XIMA FORMCYCLE.

    • label: string

      Name of an LDAP property. This is used as the label displayed to the user. To specify a nested property, separate the keys with a period, eg. name.full or location.city.

    • value: string

      Name of an LDAP property. This is used as the value that is transmitted. To specify a nested property, separate the keys with a period, eg. name.full or location.city.

    • Optional onSelect: function

      The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.

        • (this: JQuery, event: Event, ui: object): void
        • Parameters

          • this: JQuery
          • event: Event
          • ui: object
            • item: object
              • optionLabel: string
              • optionValue: string

          Returns void

    • Optional params: Stringifyable[]

      Additional parameters for the LDAP query.

    Returns JQuery

    This JQuery instance for chaining.

clear

  • clear(): JQuery
  • Clears the value of this form field. For text input fields, the entered text is removed. For select fields, all selected options are deselected.

    The form field will not be validated when cleared. In case the form field is required, no errors will be shown. Validation can be triggered immediately with the function validate().

    // Changes the text of the input field to 'Hello world!'
    // This is what the user usually does.
    $('[name="tf1"').val("Hello world!");
    
    // Clears the text.
    $('[name="tf1"').clear();
    
    // Validates the input field. If the field is required, an error message is now shown.
    $('[name="tf1"').validate() ;

    Returns JQuery

    This JQuery instance for chaining.

cob2auto

  • cob2auto(): JQuery
  • This function can be used with select elements displayed as a combobox. It converts the select element to a text input field and displays a list of possible options as the user types. Currently this uses the jQueryUI widget autocomplete.

    You can also activate this option directly in the designer. To do so, select a select element and click on the checkbox in the base settings section of the property panel.

    // Turns the form field with name "sel1" into an autocomplete field.
    $("[name='sel1']").cob2auto();

    Returns JQuery

    This JQuery instance for chaining.

dynamic

  • dynamic(options?: Partial<DynamicOptions>): JQuery
  • dynamic(method: "addRow"): JQuery
  • dynamic(method: "removeRow", rowIndex?: number): JQuery
  • dynamic(method: "getRowSize"): number
  • dynamic(method: "setRowSize", rowSize: number): JQuery
  • Makes a form element or container repeatable, so that the user can create multiple copies of it. This could be used, for example, on a email input field to let the user enter one or many email addresses.

    To select repeated elements that were created dynamically, use the attribute org_name instead of name, eg:

    // Makes form field named tf1 repeatable.
    $("[name='tf1']").dynamic();
    
    // Access the value of the first repeated form field.
    $("[org_name='tf1']").first().val();

    Each repeatable element that is created gets wrapped inside a DIV container with the class dynamic-row. It is this container that will be passed to the callback functions afterAdd, afterDel, beforeAdd, beforeDel, and changeRowSize). In case you need to initialize a form field with JavaScript, such as with the function cob2auto or errorFunc, initialization must be done after the element was created:

    // Make the select field "selPeople" repeatable
    $("[name='selPeople']").dynamic({
        // Callback whenever a new select field is created
        afterAdd: function(_, item) {
            // Select the actual form field inside the DIV container.
            var element = item.find('.XItem');
            // Now the select field can be initialized, eg:
            element.cob2auto();
        }
    });

    You can also make elements repeatable directly in base settings section of the property panel of the designer. This also lets you set the minimum and maximum number of repeated items, as well as a trigger element. For more advanced use cases, initialize repeatable elements with this JavaScript method.

    Parameters

    • Optional options: Partial<DynamicOptions>

      Options to customize how many items are allowed, how to determine the number of repeated items, etc.

    Returns JQuery

    The JQuery instance for chaining.

  • For a repeatable element: Increases the number of repeated elements by one. That is, create a new form element and add it to the end of the existing repeated form elements. Same effect as clicking on the add (plus icon) button.

    // Make input field "tfMail" repeatable
    $("[name='tfMail']").dynamic();
    // ...
    // Create a new email input field
    $("[name='tfMail']").dynamic("addRow");

    Parameters

    • method: "addRow"

    Returns JQuery

    This JQuery instance for chaining.

  • For a repeatable element: Removes a repeated form field. Same effect as clicking on the delete (minus icon) button next to the repeated element.

    // Make input field "tfMail" repeatable
    $("[name='tfMail']").dynamic();
    // ...
    // Remove the first email input field
    $("[name='tfMail']").dynamic("removeRow", 0);

    Parameters

    • method: "removeRow"
    • Optional rowIndex: number

      Index of the row to delete, starting at 0. If not given, deletes the last row.

    Returns JQuery

    This JQuery instance for chaining.

  • For a repeatable element: Determines the current number of repeated elements.

    // Make input field "tfMail" repeatable
    $("[name='tfMail']").dynamic({minSize: 3});
    
    // Number of repetitions is initially 3
    var repetitions = $("[name='tfMail']").dynamic("getRowSize");

    Parameters

    • method: "getRowSize"

    Returns number

    The current count of repeated elements.

  • For a repeatable element: sets the number of repeated elements by adding or removing the appropriate number of repeated elements.

    // Make the form field "tfMail" repeatable
    $("[name='tfMail']").dynamic();
    // Set the number of dynamically created items to 5.
    $("[name='tfMail']").dynamic("setRowSize", 5);

    Parameters

    • method: "setRowSize"
    • rowSize: number

      The number of rows to set, ie. how many repeated items should exist.

    Returns JQuery

    This JQuery instance for chaining.

error

  • error(errorMessage: string): JQuery
  • error(): JQuery
  • Marks the form field as invalid by calling the function setError() and displays an error message by calling the function validate().

    Note that the setError function by itself only marks a form field as invalid without triggering the validation process. This means that an error message is only shown later when the user either attempts to submit the form or triggers a blur event on the field afterwards.

    // Writes the error message "Invalid value" to the element named "tfIdNumber"
    $("[name='tfIdNumber'").error("Invalid value");

    Parameters

    • errorMessage: string

      The error message to be shown. Must not be the empty string.

    Returns JQuery

    This JQuery instance for chaining.

  • Marks the form field as valid and removes the error message.

    Note that the setError function by itself only marks a form field as valid without triggering the validation process. This means that the error message is only removed later when the user triggers a blur event on the field.

    // Removes the error message from the element namend "tfIdNumber"
    $("[name='tfIdNumber'").error();

    Returns JQuery

    This JQuery instance for chaining.

errorFunc

  • errorFunc(validatorFunction: function): JQuery
  • Adds a validator function to the form element. The validator function is called each time the form field needs to be validated. This can be used to implement custom validation logic.

    If multiple validator functions were added, all of them are called during validation; and all error messages will be shown.

    Please note that data validation and required fields are different. If a field is required, validation first checks whether a value was entered. An error message is shown in case it is empty. It is only when the field is non-empty that the validatior function is called. In other words, an error will be shown for required fields that are empty, irrespective of the given validator function.

    // The datatype of the field 'tfEmail' was set to 'email'
    // We add an additional validation rule to require that the host must be either 'example.com' or 'example.de'
    $('[name="tfEmail"]').errorFunc(function() {
       var value = this.val() || "";
       var hostIndex = value.indexOf("@");
       var host = hostIndex >= 0 ? value.substr(hostIndex + 1) : "";
       if (host === "example.com" || host === "example.de") return "";
       return "The host must be either example.de or example.com";
    });

    Parameters

    • validatorFunction: function

      Function called upon form field validation. Returns a string representing the error message. To indicate that the form field is valid, return the empty string.

        • (this: JQuery): string
        • Parameters

          • this: JQuery

          Returns string

    Returns JQuery

    This JQuery instance for chaining.

getContainer

  • getContainer(): JQuery
  • Every form field consists of multiple elements, such as labels, input fields, container elements etc. Each form field is wrapped inside a container element. This function returns that container.

    Container elements are DIV elements with the CSS class xm-item-div and the attribute xn set to the name of the form element.

    Given a text input field named tfName, the call to $("[name='tfName']") might return the following HTML element:

    <input id="xi-tf-16" name="tfName" class="XItem XTextField" title type="text">

    And finding the contain via $("[name='tfName']").getContainer() might return

    <div class="xm-item-div label-top" cn="XTextField" xi="xi-tf-16" xn="tfName">
      ...
      <input id="xi-tf-16" name="tfName" class="XItem XTextField" title type="text">
      ...
    </div>

    Returns JQuery

    The container element of this form field. When the element is not a form element, or an element without a container, an empty JQuery instance is returned.

getLabel

  • getLabel(): JQuery
  • Every form field consists of multiple elements, such as labels, input fields, container elements etc. Input fields such as text input fields or select elements have got a label, this function returns that label.

    // Returns the label text for the text field tfMail, eg. "Your email address"
    $('[name=tfMail').getLabel().text();
    
    // Returns the label text of the second instance of a repeat
    // input field names "tfEmployees", eg. "Name of 2nd employee"
    $($('[org_name=tfEmployees]').get(1)).getLabel().text();

    Returns JQuery

    The label element for each given form field.

hasAttr

  • hasAttr(name: string): boolean
  • Checks an HTML attribute with the given name is set on the element.

    Assume the HTML look as follows:

    <input name="tfMail" placeholder></input>

    Then this function return the following values:

    $("[name='tfMail']").hasAttr("name"); // true
    $("[name='tfMail']").hasAttr("placeholder"); // true
    $("[name='tfMail']").hasAttr("id"); // false

    Parameters

    • name: string

      Name of the attribute to check for.

    Returns boolean

    Whether this element has the given attribute set.

jSignature

  • jSignature(options?: Partial<Settings>): JQuery
  • jSignature(method: "init", options?: Partial<Settings>): JQuery
  • jSignature(method: "reset" | "clear"): JQuery
  • jSignature(method: "destroy"): JQuery
  • jSignature(method: "getData", dataFormat?: "default"): string
  • jSignature(method: "getData", dataFormat: "native"): object[]
  • jSignature(method: "getData", dataFormat: "base30" | "image/jSignature;base30"): string[]
  • jSignature(method: "getData", dataFormat: "svg" | "image/svg+xml"): ["image/svg+xml", string]
  • jSignature(method: "getData", dataFormat: "svgbase64" | "image/svg+xml;base64"): ["image/svg+xml;base64", string]
  • jSignature(method: "getData", dataFormat: "image" | "image/png;base64"): ["image/png;base64", string]
  • jSignature(method: "getData", dataFormat: string): any
  • jSignature(method: "setData" | "importData", dataObject: object[], dataFormat: "native"): JQuery
  • jSignature(method: "setData" | "importData", dataObject: string[], dataFormat: "base30" | "image/jSignature;base30"): JQuery
  • jSignature<T>(method: "setData" | "importData", dataObject: [T, any], dataFormat?: T): JQuery
  • jSignature(method: "setData" | "importData", dataObject: any, dataFormat: string): JQuery
  • jSignature(method: "listPlugins", category: "import" | "export"): string[]
  • jSignature(method: "disable"): JQuery
  • jSignature(method: "enable"): JQuery
  • jSignature(method: "isModified"): boolean
  • jSignature(method: "getSettings"): Settings
  • jSignature<K>(method: "updateSettings", name: K, value: Settings[K], applyImmediately?: boolean): Settings[K]
  • Converts an input or textarea element to a jSignature field. This lets the user draw their signature by using their mouse or a stylus with a touch-sensitive screen.

    Parameters

    • Optional options: Partial<Settings>

      Optional settings for JSignature.

    Returns JQuery

    This JQuery instance for chaining.

  • Converts an input or textarea element to a jSignature field. This lets the user draw their signature by using their mouse or a stylus with a touch-sensitive screen.

    Parameters

    • method: "init"
    • Optional options: Partial<Settings>

      Optional settings for JSignature.

    Returns JQuery

    This JQuery instance for chaining.

  • Just clears the signature pad, data store (and puts back signature line and other decor).

    Parameters

    • method: "reset" | "clear"

    Returns JQuery

    This JQuery instance for chaining.

  • Destroy the instance and restores the original input or textarea element.

    Parameters

    • method: "destroy"

    Returns JQuery

    This JQuery instance for chaining.

  • Returns the current stroke data.

    The data format is that produced natively by Canvas - data-url-formatted, base64 encoded (likely PNG) bitmap data that looks like this: data:image/png;base64,i1234lkj123;k4;l1j34l1kj3j....

    This export call returns a single data-url-formatted string.

    Parameters

    • method: "getData"
    • Optional dataFormat: "default"

    Returns string

    The current signature.

  • Returns the current stroke data.

    This data format is a custom representation of drawing strokes as an array of objects with the properties x and y, each of which is an array. This JavaScript objects structure is the actual data structure where each of the drawing strokes is stored in jSignature. The structure is designed specifically for speed and efficiency of collecting strokes data points. (Although it is a bit counter-intuitive, octopus-looking structure, it (a) allows to pile up two-axis coordinates fast without a need to create a Point objects for each data point and (b) provides for very easy loop-based processing of data.) Although you could JSONify that, pass it around, parse, render from this, it may not be the most efficient way to store data, as internal format may change in other major versions of jSignature. I recommend looking at base30 format as a direct, but compact equivalent to "native"-as-JSON. What this data is good for is running stats (size, position of signature on the canvas) and editing strokes (allowing for undo last stroke, for example).

    Parameters

    • method: "getData"
    • dataFormat: "native"

    Returns object[]

    The current signature.

  • Returns the current stroke data.

    This data format is a Base64-spirited compression format tuned for absurd compactness and native URL-compatibility. It is a native data structure compressed into a compact string representation of all vectors. One of possible ways of communicating the data to the server is JSONP, which has a practical URL length limit (if IE is supported) of no more than 2000+ characters. This compression format is natively URL-compatible without a need for re-encoding, yet will fit into 2000 characters for most non-complex signatures.

    Parameters

    • method: "getData"
    • dataFormat: "base30" | "image/jSignature;base30"

    Returns string[]

    The current signature.

  • Returns the current stroke data.

    This data format produces the signature as an SVG image (SVG XML text). All strokes are denoised and smoothed. This format is a good medium between "easy to view" and "hightly scalable." Viewing SVGs is natively supported in majority of today's browsers and, yet, this format can be infinitely scaled and enhanced for print. Data is textual, allowing for easy storage and transfer.

    Parameters

    • method: "getData"
    • dataFormat: "svg" | "image/svg+xml"

    Returns ["image/svg+xml", string]

    The current signature.

  • Returns the current stroke data.

    This is same as "svg" plugin, but the SVG XML text is compressed using base64 encoding. Although many browsers now have built-in base64 encoder ( btoa() ), some, like Internet Explorer do not. This plugin has its own (short and efficient) copy of software-based base64 encoder which is invoked on the browsers lacking btoa().

    Parameters

    • method: "getData"
    • dataFormat: "svgbase64" | "image/svg+xml;base64"

    Returns ["image/svg+xml;base64", string]

    The current signature.

  • Returns the current stroke data.

    This data format is essentially same as native format, but parsed apart so that mimetype and data are separate objects in an array structure similar to that produced by "svg" export. Example (shortened) ["image/png;base64","i123i412i341jijalsdfjijl234123i..."]. Because image export filter depends on (somewhat flaky) browser support and picks up needless data, recommend using this only for demonstration and during development.

    Parameters

    • method: "getData"
    • dataFormat: "image" | "image/png;base64"

    Returns ["image/png;base64", string]

    The current signature.

  • Returns the current stroke data.

    Parameters

    • method: "getData"
    • dataFormat: string

      Data format according to which the returned value is formatted.

    Returns any

    The current signature.

  • Parameters

    • method: "setData" | "importData"
    • dataObject: object[]

      The signature to be set.

    • dataFormat: "native"

    Returns JQuery

    This JQuery instance for chaining.

  • Parameters

    • method: "setData" | "importData"
    • dataObject: string[]

      The signature to be set.

    • dataFormat: "base30" | "image/jSignature;base30"

    Returns JQuery

    This JQuery instance for chaining.

  • Type parameters

    • T: string

    Parameters

    • method: "setData" | "importData"
    • dataObject: [T, any]

      The signature to be set. The data format is taken from the first entry in the array. The second entry represents the actual data.

    • Optional dataFormat: T

      Optional. If given, must be the same as the first entry in the data object array.

    Returns JQuery

    This JQuery instance for chaining.

  • Parameters

    • method: "setData" | "importData"
    • dataObject: any

      The signature to be set. It must be formatted according to the given data format.

    • dataFormat: string

      Data format of the given data object.

    Returns JQuery

    This JQuery instance for chaining.

  • List all plugins that support importing / exporting data.

    Parameters

    • method: "listPlugins"
    • category: "import" | "export"

      The category of plugins to return.

    Returns string[]

    A list of plugins for the given category.

  • Makes the canvas read-only and disable the jSignature buttons

    Parameters

    • method: "disable"

    Returns JQuery

    This JQuery instance for chaining.

  • Makes the canvas writable again and enables the jSignature buttons.

    Parameters

    • method: "enable"

    Returns JQuery

    This JQuery instance for chaining.

  • Checks whether any signature was drawn since the signature input field was initialized.

    Parameters

    • method: "isModified"

    Returns boolean

    true iff the jSignature was modified, false otherwise.

  • Parameters

    • method: "getSettings"

    Returns Settings

    The settings of the jSignature instance.

  • Updates the given setting with a new value.

    This allows you to update certain settings like lineWidth or line color and with the third argument you can make the change apply to the existing strokes. At present, updating change to existing strokes only works with a few settings like color.

    Type parameters

    • K: keyof Settings

    Parameters

    • method: "updateSettings"
    • name: K

      Name of the setting to modify.

    • value: Settings[K]

      New value of the setting.

    • Optional applyImmediately: boolean

      Pass true iff the change should affect current signature or future strokes.

    Returns Settings[K]

    The updated value.

on

  • on(event: "addRow", callback: function): JQuery
  • on(event: "delRow", callback: function): JQuery
  • Must be called directly on the form element (FORM.xm-form).

    This allows you to register a global callback that is notified when a row was added to a repeatable element. A repeatable element is a form field of which the user can create multiple copies of, eg. for entering multiple email addresses.

    Compared with the callback that can be registered with the function dynamic, this is a global callback that is called whenever a row is added to any repeatable element within the form. It is useful when you repeat an element in the designer and not via JavaScript.

    // Intialize newly added rows with the cob2auto function (autocomplete)
    $('FORM.xm-form').on("addRow", function(_, data) {
       data.container.find(".XSelect").cob2auto();
    });

    Parameters

    • event: "addRow"

      The name of the event, ie. addRow.

    • callback: function

      Callback for the add row event. It receives the container containing the newly created element.

        • (this: HTMLElement, event: Event, data: object): void
        • Parameters

          • this: HTMLElement
          • event: Event
          • data: object
            • container: JQuery

          Returns void

    Returns JQuery

    This JQuery instance for chaining.

  • Must be called directly on the form element (FORM.xm-form).

    This allows you to register a callback that is notified when a row was removed from a repeatable element. A repeatable element is a form field of which the user can create multiple copies of, eg. for entering multiple email addresses.

    Compared with the callback that can be registered with the function dynamic, this is a global callback that is called whenever a row is removed from any repeatable element within the form. It is useful when you repeat an element in the designer and not via JavaScript.

    // Compute shipping costs again when an element was removed
    $('FORM.xm-form').on("delRow", function(_, data) {
      recalculateShippingCosts();
    });

    Parameters

    • event: "delRow"

      The name of the event, ie. delRow.

    • callback: function

      Callback for the row deletion event. It receives the container containing the deleted repeatable element. Note that it was already removed from the DOM.

        • (this: HTMLElement, event: Event, data: object): void
        • Parameters

          • this: HTMLElement
          • event: Event
          • data: object
            • container: JQuery

          Returns void

    Returns JQuery

    This JQuery instance for chaining.

removeStar

  • removeStar(): JQuery
  • Removes the little red star icon next to the label of the form field that indicates whether the form field is a required field.

    Currently this icon is a SPAN element with the class required-star. Note that this may be subject to change:

    <span class="required-star">*</span>

    For example:

    $('input[name=tf2]').removeStar() // Removes the star from the label of the form field tf2.

    This function only changes its appearance, but does not make the form field a required field. To set whether a form field is required, use the function "setRequired".

    Returns JQuery

    This JQuery instance for chaining.

replaceParams

  • replaceParams(): JQuery
  • Takes the HTML of the given element (the innerHTML) and replaces certain patterns with the values from the URL parameters. This uses the URL parameters of the URL that was used to open the form.

    The following patterns are replaced. KEY represents the name of the URL parameter:

    {KEY}

    For each URL parameter, the first occurence of the above pattern is replaced with the value of the URL parameter named KEY. For example, assume a form is accessed via the following URL:

    http://localhost/formcycle/form/provide/1?name=world

    The form contains a text input field with the name tfGreeting and the Hello, {name}!:

    // Takes the innerHTML of the container element and replaces "{name}" with "{world}"
    $("[xn='tfGreeting']").replaceParams();

    The label of the input field now becomes Hello, world!.

    Returns JQuery

    This JQuery instance for chaining.

setDataType

  • setDataType(dataType: FormVruleType | string): JQuery
  • setDataType(): JQuery
  • Sets the data type of a text input field (input or textarea). The following data types are available:

    • onlyLetterSp: Allows only letters and spaces.
    • onlyLetterNumber: Allows only letters, numbers, and spaces.
    • integer: Allows only integer, that is number without a decimal point, eg. 3, 0, or -21.
    • posinteger: Allows only positive integers, eg. 0, 3, oder 123.
    • number: Allows only numbers, including numbers with a decimal point, eg. 0.03, -99.2, or 42.
    • money: Requires the input to be a valid amount of money, ie. a number with exactly two decimal digits, eg. 2,00, -3,95, 0,00 or 897345,38.
    • posmoney : Requires the input to be a valid amount of money, not including negative numbers, eg. 0,00 or 2,34.
    • posmoneyOptionalComma: Requires the input to be a valid positive amount of money, with the decimal digits being optional, eg. 0,00, 0, 3,4, or 3.
    • email: Allows only valid (international) email addresses, eg. james@john.org or θσερ@εχαμπλε.ψομ.
    • dateDE: Allows only German-style dates (DD.MM.YYYY), eg. 22.05.1990.
    • dateEN: Allows only British-style dates (DD/MM/YYYY), eg. 22/05/1990.
    • time: Requires the input to be a valid time, in the format hh:mm, eg. 22:05 or 03:42.
    • plzDE: Allows only postal code from Germany, ie. exactly 5 digits, eg. 02349. Does not check whether such a code is actually registered within Germany.
    • phone: Allows only valid phone numbers, eg. 0234995483 or +49 351 4459654.
    • url: Allows only URLs, including the protocol, eg. http://example.com or https://www.james.org.
    • ipv4: Allows only IP4 addresses, eg. 127.0.0.1 or 10.42.42.13.

    For example:

    // Checks whether a valid mail address was entered.
    $('[name="tfMail"').setDataType("email")

    When the data type was set to date, a calendar for picking a date will be shown. If you later decide to change the datatype with this function, the calendar still shows up. If, on the other hand, you set the datatype to another value in the designer and later decide to change it to date with this function, no calendar will show up. Use the jQuery.fn.datepicker method to enable or disable the calendar when necessary.

    The data type can also be set in the contraints section of the properties panel of the designer.

    Currently this uses the HTML attribute type and vdt, but this is subject to change.

    Parameters

    • dataType: FormVruleType | string

      The new data type for the input text field.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the data type of an input text field. This allows any value to be entered, not checking anymore whether it is a valid number, ZIP code etc.

    For example:

    // Removes the check for whether a valid mail address was entered.
    $('[name="tfMail"').setDataType()

    Returns JQuery

    This JQuery instance for chaining.

setError

  • setError(errorMessage: string): JQuery
  • setError(): JQuery
  • Marks a form field as invalid and sets the given error message.

    The error message does not appear immediately, but only once the user interacts with the form element, ie. when a blur or change event is triggered on the form field, or validation gets triggered otherwise, such as by submitting the form. Use the function validate to trigger validation immediately and show the error message.

    // Marks input field "tfName" as invalid and sets the error message.
    $('[name="tfName"').setError("Wrong name.");
    // Validates the input field and displays the error message.
    $('[name="tfName"').validate();

    Currently this uses the HTML attribute error, but this is subject to change.

    Parameters

    • errorMessage: string

      The error message to shown on the element.

    Returns JQuery

    This JQuery instance for chaining.

  • Marks the form field as valid and removes the error message so that no error is shown anymore.

    The error message does not disappear immediately, but only once the user interacts with the form element, ie. when a blur or change event is triggered on the form field. Use the function validate() to trigger validation immediately and show the error message.

    Returns JQuery

    This JQuery instance for chaining.

setGroupReq

  • setGroupReq(groupreq: string): JQuery
  • setGroupReq(): JQuery
  • Sets the required group of a form element. The form element is valid if at least one form element of the required group is non-empty. It validates as invalid when no form element of the required group contains a value.

    This function only changes the required group, it does not change whether the form element itself is required. To illustrate this, assume the input field tf1 has already been marked as a required field in the XIMA FORMCYCLE Designer, and no options have been set for input field tf2 yet. Both input fields are now added to the required group group1 by this function. An error will appear even when tf1 is empty and tf2 contains a value. To get the expected result, the required field marker for tf1 must be removed with setRequired.

    // Add the input field "tf1" to the required group "group1"
    $('[name=tf1]').setGroupReq("group1");
    
    // Add the input field "tf2" to the required group "group1"
    $('[name=tf2]').setGroupReq("group1");
    
    // Marks the input field "tf1" as an optional field
    $('[name=tf1]').setRequired(false);

    You can also set the required group in the options panel of the designer as well. Note that this option only shows up when the form field has been marked as required.

    Currently, required groups use the attribute vgr, but this is subject to change.

    Parameters

    • groupreq: string

      Arbitrary name of the required group for the input element.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the required group of a form element.

    If you also want to mark the form element itself as required, use the function setRequired.

    Returns JQuery

    This JQuery instance for chaining.

setMaxCheckBox

  • setMaxCheckBox(maxCheckBox: number): JQuery
  • setMaxCheckBox(): JQuery
  • Sets the maximum allowed number of the selected options of a select element.

    This limit can also be set directly in the contraints section of the designer.

    // At most three checkboxes or radiobuttons can be selected for the field "sel1"
    $('[name=sel1').setMaxCheckBox(3)

    Currently this function uses the HTML attribute vcmx, but this is subject to change.

    Parameters

    • maxCheckBox: number

      The maximum number of checkboxes that can be checked.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the restriction on the maximum allowed number of selected options of a select element.

    Returns JQuery

    This JQuery instance for chaining.

setMaxLength

  • setMaxLength(maxLength: number): JQuery
  • setMaxLength(): JQuery
  • Sets the maximum length (number of characters) of the text that can be entered into an input field.

    // User cannot enter more than 9 characters in the field "tf1"
    $('[name="tf1"').setMaxLength(9)

    This option can be set directly in the contraints section of the designer as well.

    Currently this uses the HTML attribute vmxl, but this is subject to change.

    Parameters

    • maxLength: number

      Maximum (inclusive) number of characters allowed.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the maximum length (number of characters) of the text that can be entered into an input field.

    Returns JQuery

    This JQuery instance for chaining.

setMaxValue

  • setMaxValue(maxValue: number): JQuery
  • setMaxValue(): JQuery
  • For an input text field with numeric input, sets the largest allowed number.

    // The value of the field "tf1" must be equal to or less than 9.
    $('[name="tf1"').setMaxValue(9)

    This option can be set directly in the constraints section of the designer as well.

    Currently this uses the HTML attribute vmx, but this is subject to change.

    Parameters

    • maxValue: number

      The largest (inclusive) value allowed for the input field.

    Returns JQuery

    This JQuery instance for chaining.

  • For an input text field with numeric input, removes the restriction on the largest allowed number.

    Returns JQuery

    This JQuery instance for chaining.

setMinCheckBox

  • setMinCheckBox(minCheckBox: number): JQuery
  • setMinCheckBox(): JQuery
  • Sets the minimum allowed number of the selected options of a select element.

    // At least one checkbox or radiobutton must be selected for the field "sel1"
    $('[name=sel1').setMinCheckBox(1);

    This limit can also be set directly in the contraints section of the designer.

    Currently this function uses the attribute vcmn, but this is subject to change.

    Parameters

    • minCheckBox: number

      The minimum (inclusive) number of checkboxes that can be checked.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the restriction on the minimum allowed number of selected options of a select element.

    Returns JQuery

    This JQuery instance for chaining.

setMinLength

  • setMinLength(minLength: number): JQuery
  • setMinLength(): JQuery
  • Sets the minimum length (number of characters) of the text that can be entered into an input field.

    // User must enter at least one character in the field "tf1".
    $('[name="tf1"').setMinLength(1);

    This option can be set directly in the contraints panel of the XIMA FORMCYLE designer as well.

    Currently this uses the HTML attribute vmnl, but this is subject to change.

    Parameters

    • minLength: number

      Minimum (inclusive) number of characters allowed.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the minimum length (number of characters) of the text that can be entered into an input field.

    Returns JQuery

    This JQuery instance for chaining.

setMinValue

  • setMinValue(minValue: number): JQuery
  • setMinValue(): JQuery
  • For an input text field with numeric input, sets the smallest allowed number.

    // The value of the field "tf1" must be equal to or greater than 1.
    $('[name="tf1"').setMinValue(1);

    This option can be set directly in the constraints section of the designer as well.

    Currently this uses the HTML attribute vmn, but this is subject to change.

    Parameters

    • minValue: number

      The smallest (inclusive) value allowed for the input field.

    Returns JQuery

    This JQuery instance for chaining.

  • For an input text field with numeric input, removes the restriction on the smallest allowed number.

    Returns JQuery

    This JQuery instance for chaining.

setMustEqual

  • setMustEqual(name: string): JQuery
  • setMustEqual(): JQuery
  • Sets the name of the form field whose value must be the same as the value of this form field. Assume there are two field tf1 and tf2

    An error message is displayed when the value of this form field is not the same as the value of the other field.

    This option can also be set in the constraints section of the designer as well.

    Currently this uses the attribute veq, however, this is subject to change.

    // User must confirm the email address by entering it again, it must be equal to the previously entered email.
    $('[name=tfMailRep]').setMustEqual("tfMail");

    Parameters

    • name: string

      Name of the referenced form field this field must equal.

    Returns JQuery

    This JQuery instance for chaining.

  • Removes the restriction that the form field needs to equal another form field.

    Returns JQuery

    This JQuery instance for chaining.

setRequired

  • setRequired(required: boolean): JQuery
  • Changes whether the form field is a required form field and must be filled out.

    // The user must enter a value into the form field "tf1".
    $('[name=tf1').setRequired(true);

    This option can also be set directly in constraints section of the designer.

    Currently this uses the attribute vr, but this is subject to change.

    Parameters

    • required: boolean

      If true, marks the form field as required. If false, the form field must not be filled out.

    Returns JQuery

    This JQuery instance for chaining.

setRequiredIf

  • setRequiredIf(name: string, test?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | number, value?: string | number): JQuery
  • setRequiredIf(): JQuery
  • You can setup a form field so that is required or optional depending on the value of another form field. This function allows you to change that dependency.

    For example, assume you want an input field for an address that is required only when a country has been selected:

    // Field named tfAddress is required iff field with name selCountry has a value.
    $('[name="tfAddress"]').setRequiredIf("selCountry", 0);

    This option can also be set in the constraints section of the designer.

    Currently this uses the HTML attributes vrif_c and vrif_v. Note that this is subject to change.

    The following values are available for the type of test:

    • 0 (has a value) This form field is a required field when the other field is non-empty.
    • 1 (equals) This form field is a required field when the value of the other field equals the given value.
    • 2 (not equals) This form field is a required field when value ofthe the other field does not equal the given value.
    • 3 (regular expression) This form field is a required field when the other field matches the regular expression. As given by the parameter value.
    • 4 (lower than) This form field is a required field when the other field's value is lower than the given value.
    • 5 (greater than) This form field is a required field when the other field's value is greater than the given value.
    • 6 (between) This form field is a required field when the other field's value is between the given values. The parameter value must be a range in the format x-y, eg. 2-37.
    • 7 (lower or equal to) This form field is a required field when the other field's value is lower than or equal to the given value.
    • 8 (greater or equal to) This form field is a required field when the other field's value is greater than or equal to the given value.
    • 9 (has no value) This form field is a required field when the other field does not have a value.

    Parameters

    • name: string

      The name of the form field this field should depend on.

    • Optional test: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | number

      The type of of dependency, ie. how the values of the depending field is checked to determine whether this field should be required. If not given, defaults to 0. See above for the allowed values.

    • Optional value: string | number

      Value for the comparison. If not given, defaults to the emtpy string.

    Returns JQuery

    This JQuery instance for chaining.

  • You can setup a form field so that is required depending on the value of another form field. This function removes that dependency.

    Returns JQuery

    This JQuery instance for chaining.

sum

  • sum(): number
  • Takes the value of all form fields and interprets them as numbers. The sum of these numbers is then returned. This method should only be used on input fields or textareas. It is especially useful for repeated input fields when you want to add them together. Please note that for repeated form fields, you should select the individual input fields with the attribute org_name instead of name:

    // Returns the sum of all dynamically created copies of the input field named "tfPayment"
    var sum = $("[org_name='tfPayment']").sum();

    Returns number

    The (numerical) sum of the values of the selected form fields.

validate

  • validate(): boolean
  • Validates the form field and all fields it contains (when it is a container or fieldset). An error message is displayed for elements that are invalid. Invalid form fields are required form fields without a value as well as form fields with a restriction (such as the data type email).

    By default, validation only triggers on a blur or change event, ie. when the user switches to another form field or clicks anywhere else on the page. One use case for this function is to validate the input as the user types. Note however, that this requires more processing power and may be slow for very long forms.

    // Validates the field "tf1" every time the user types a character.
    $("[name='tfId']").on("keydown", function(event) { $(this).validate(); });
    
    // Validates the entire form
    var isFormValid = $(".xm-form").validate();

    Returns boolean

    Whether the form field and all form fields it contains are valid.

visible

  • visible(show: boolean): JQuery
  • Shows or hides the form field. This function should be preferred over the JQuery functions hide and show, as it updates some XIMA FORMCYCLE specific attributes correctly.

    A form field that is hidden or invisible cannot be invalid and as such never prevents the form from being submitted.

    Please note: This method only changes the visibility state of the element on which it is called. For example, if you want to hide an entire container with the input field and the corresponding label, you can use:

    // Make the form field "tf1" invisible, including the label
    $("[name='tfFirstName']").getContainer().visible(false);

    Parameters

    • show: boolean

      If true, shows the form field. If false, hides the form field.

    Returns JQuery

    This JQuery instance for chaining.