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.

appointmentPicker

  • Initializes a date and time picker for selecting an appointment. Appointments can be configured in the backend. Lets the user select a date (year, month, day) and a time (hour and minute).

    Parameters

    • Optional method: "init"

    Returns JQuery

    this for chaining.

  • Retrieves the currently selected slot for the first element in the current selection.

    Parameters

    • method: "getSlot"

      The method to invoke on the appointment picker.

    Returns Promise<IAppointmentSlot | undefined>

    The currently selected slot, or undefined when no slot is selected. The promise is rejected when the current selection is empty.

  • Fetches all available slots of a given month and year for the first element in the selection.

    Parameters

    • method: "getSlots"

      The method to invoke on the appointment picker.

    • Optional monthYear: Partial<IAppointmentLocalMonthYear>

      The month and year for which to fetch the slots. When a property is not given, it defaults to the currently selected month and year.

    Returns Promise<IAppointmentMonthSlotData>

    All available slots for the given month and year. The promise is rejected when the slots could not be fetched from the server.

  • Finds the currently selected month and the corresponding year of the first element in the current selection.

    Parameters

    • method: "getMonthYear"

      The method to invoke on the appointment picker.

    Returns Promise<IAppointmentLocalMonthYear | undefined>

    The currently selected month and year, or undefined when no month or year is selected. The promise is rejected when the current selection is empty

  • Selects a particular month in a given year and shows all days for the month for all elements in the current selection. When the date picker is closeable, you should open it first.

    Parameters

    • method: "setMonthYearDelta"

      The method to invoke on the appointment picker.

    • Optional monthYearDelta: Partial<IAppointmentLocalMonthYear>

      The month and year to select, relative to the currently selected month and year. The month defaults to 1 and the year to 0 (e.g. move to the next month). Can be negative.

    Returns Promise<IAppointmentMonthSlotData[]>

    All available slots for the selected month in the given year. The array contains one entry for each element in the current selection. The promise resolves when all month and years were set (or rejects when one could not be set).

  • Selects a particular month in a given year and shows all days for the month for all elements in the current selection. When the date picker is closeable, you should open it first.

    Parameters

    • method: "setMonthYear"

      The method to invoke on the appointment picker.

    • Optional monthYear: Partial<IAppointmentLocalMonthYear>

      Day to select. When a property is not given, it defaults to the currently selected month or year.

    Returns Promise<IAppointmentMonthSlotData[]>

    All available slots for the selected month in the given year. The array contains one entry for each element in the current selection. The promise resolves when all month and years were set (or rejects when one could not be set).

  • Selects a particular day and shows the available slots of that day for all elements in the current selection.

    Parameters

    • method: "setDate"

      The method to invoke on the appointment picker.

    • date: Promise<Partial<IAppointmentLocalDate>>

      Day to select. When a property is not given, it defaults to the currently selected date.

    Returns Promise<IAppointmentDaySlotData[]>

    All available slots for the selected day. The array contains one entry for each element in the current selection. The promise resolves when all dates were set (and rejects when a date could not be set).

  • Changes the currently selected slot to the given slot or clears the selected slot, for all elements in the current selection.

    // Selects the first slot of the current month, if any
    async function selectFirstSlot(app) {
      const {slots} = await app.appointmentPicker("getSlots");
      const firstSlot = Object.values(slots)?.[0]?.slots?.[0]?.slot;
      if (firstSlot) {
        await app.appointmentPicker("setSlot", firstSlot);
      }
    }
    selectFirstSlot($("[name='app1']"));

    Parameters

    • method: "setSlot"

      The method to invoke on the appointment picker.

    • Optional slot: IAppointmentSlot

      The slot to set, or undefined to clear the selected slot.

    Returns Promise<void>

    A promise that resolves when the slots were set, or rejects when the slots could not be set.

  • Closes or opens the appointment picker for all elements in the current selection.

    Parameters

    • method: "toggle"

      The method to invoke on the appointment picker.

    • Optional open: boolean

      true to open the picker, false to close it, undefined to open it when closed and vice versa.

    Returns Promise<boolean[]>

    Whether the picker is now opened. The array contains one entry for each element in the current selection. The promise is resolved when the picker was toggled, and rejected when either the selection is empty or the appointment picker is not closable.

  • Checks whether the appointment picker is opened or closed, for the first element in the current selection.

    Parameters

    • method: "isOpened"

      The method to invoke on the appointment picker.

    Returns Promise<boolean>

    true when the picker is open, or false otherwise. Always returns true when the picker is not closable. The promise is rejected when either the selection is empty.

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)

    Please note that instead of specifying the options via JavaScript, you can also add HTML data attributes to the input field:

    <input id="money-field"
        data-a-dec=","
        data-a-sign="kg"
        data-v-min="1"
        data-v-max="100"
        data-m-dec="3"
    >

    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?: SingleOrArrayLike<undefined | boolean | number | bigint | string | Node | JQuery>): 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.

        • Parameters

          • this: JQuery
          • event: TriggeredEvent
          • 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.

        • Parameters

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

          Returns void

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

      Additional parameters for the database query. Can be a single value or an array of values, all given values are transmitted as additional parameters. For undefined an empty value is transmitted. For a string, the string value itself is transmitted. For a number or boolean, the string representation of the number or boolean is transmitted. For a JQuery instance, the values of all elements in that JQuery selection are transmitted. For an HTML element: (1) if it is an input checkbox or radio element, transmits the value if the checkbox or radio button is checked, (2) if it is an input file element, transmits the name of each file, or an empty string if no files are selected, (3) if it an input element of another type, transmits the value of the input element, (4) if it is a textarea or select element, obtains the value via $.fn.val and transmits that value, (5) if it is any other element, searches for child elements that are input, textarea, or select elements and transmits those values.

    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?: SingleOrArrayLike<undefined | boolean | number | bigint | string | Node | JQuery>): 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.

        • Parameters

          • this: JQuery
          • event: TriggeredEvent
          • 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.

        • Parameters

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

          Returns void

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

      Additional parameters for the LDAP query. Can be a single value or an array of values, all given values are transmitted as additional parameters. For undefined an empty value is transmitted. For a string, the string value itself is transmitted. For a number or boolean, the string representation of the number or boolean is transmitted. For a JQuery instance, the values of all elements in that JQuery selection are transmitted. For an HTML element: (1) if it is an input checkbox or radio element, transmits the value if the checkbox or radio button is checked, (2) if it is an input file element, transmits the name of each file, or an empty string if no files are selected, (3) if it an input element of another type, transmits the value of the input element, (4) if it is a textarea or select element, obtains the value via $.fn.val and transmits that value, (5) if it is any other element, searches for child elements that are input, textarea, or select elements and transmits those values.

    Returns JQuery

    This JQuery instance for chaining.

autocompleteQuery

  • autocompleteQuery(url: string, queryName: string, label: string, onSelect?: function): JQuery
  • autocompleteQuery(url: string, queryName: string, label: string, value: string, onSelect?: function, params?: SingleOrArrayLike<undefined | boolean | number | bigint | string | Node | JQuery>): JQuery
  • Should be used only on text input fields.

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

    This method lets you specify a custom URL. Use JQuery.autocompleteDB or JQuery.autocompleteLDAP if you want to query database or LDAP queries defined in the XIMA FORMCYCLE backend.

    see

    JQuery.autocompleteDB

    see

    JQuery.autocompleteLDAP

    Parameters

    • url: string

      The URL of the query to execute. Normally you should use the URLs from XFC_METADATA.urls, e.g. XFC_METADATA.urls.dataquery_ldap or XFC_METADATA.urls.dataquery_db.

    • queryName: string

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

    • label: string

      Name of the field for the label and the value, such as a database column or 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.

    • 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.

        • Parameters

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

          Returns void

    Returns JQuery

  • Should be used only on text input fields.

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

    This method lets you specify a custom URL. Use JQuery.autocompleteDB or JQuery.autocompleteLDAP if you want to query database or LDAP queries defined in the XIMA FORMCYCLE backend.

    see

    JQuery.autocompleteDB

    see

    JQuery.autocompleteLDAP

    Parameters

    • url: string

      The URL of the query to execute. Normally you should use the URLs from XFC_METADATA.urls, e.g. XFC_METADATA.urls.dataquery_ldap or XFC_METADATA.urls.dataquery_db.

    • queryName: string

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

    • label: string

      Name of the field to use as the label, e.g. the name of a database column or an LDAP property. This is used as the label displayed to the user.

    • value: string

      Name of the field to use as the value, e.g. the name of a database column or an LDAP property.

    • 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.

        • Parameters

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

          Returns void

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

      Additional parameters for the query. Can be a single value or an array of values, all given values are transmitted as additional parameters. For undefined an empty value is transmitted. For a string, the string value itself is transmitted. For a number or boolean, the string representation of the number or boolean is transmitted. For a JQuery instance, the values of all elements in that JQuery selection are transmitted. For an HTML element: (1) if it is an input checkbox or radio element, transmits the value if the checkbox or radio button is checked, (2) if it is an input file element, transmits the name of each file, or an empty string if no files are selected, (3) if it an input element of another type, transmits the value of the input element, (4) if it is a textarea or select element, obtains the value via $.fn.val and transmits that value, (5) if it is any other element, searches for child elements that are input, textarea, or select elements and transmits those values.

    Returns JQuery

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.
    $('[data-name="tf1"').val("Hello world!");
    
    // Clears the text.
    $('[data-name="tf1"').clear();
    
    // Validates the input field. If the field is required, an error message is now shown.
    $('[data-name="tf1"').validate() ;

    Returns JQuery

    This JQuery instance for chaining.

cob2auto

  • 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.
    $("[data-name='sel1']").cob2auto();

    Parameters

    Returns JQuery

    This JQuery instance for chaining.

counter

  • counter(settings?: Partial<Settings>): JQuery
  • Initializes the jQuery counter plugin on an element.

    This jQuery Word and character counter plug-in allows you to count characters or words, up or down. You can set a minimum or maximum goal for the counter to reach.

    Parameters

    • Optional settings: Partial<Settings>

      Optional settings for the plugin.

    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.
    $("[data-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
    $("[data-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
    $("[data-name='tfMail']").dynamic();
    // ...
    // Create a new email input field
    $("[data-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
    $("[data-name='tfMail']").dynamic();
    // ...
    // Remove the last email input field
    $("[data-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
    $("[data-name='tfMail']").dynamic({minSize: 3});
    
    // Number of repetitions is initially 3
    var repetitions = $("[data-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
    $("[data-name='tfMail']").dynamic();
    // Set the number of dynamically created items to 5.
    $("[data-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"
    $("[data-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"
    $("[data-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(returnRepetitionContainer?: boolean): 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 $("[data-name='tfName']") might return the following HTML element:

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

    And finding the container via $("[data-name='tfName']").getContainer() would return

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

    Behavior for repeated elements

    A repeated form element is an element of which the user may create one or more copies. They are used to enter dynamic data, such as the address data of multiple persons. The xm-item-div is the container that contains all dynamically created reptitions of the form element. Each repetition in turn put inside a container with the class dynamic-row. By default, this method always returns the xm-item-div container. When the optional flag returnRepetitionContainer is set to true, this method returns the dynamic-row instead. For example, if the input text element with the name tfMail is repeated, $("[data-org-name='tfMail']).eq(1) selects the second repetition and $("[data-org-name='tfMail']).eq(1).getContainer() returns the second dynamic-row container inside the xm-item-div.

    <div class="xm-item-div label-top CXTextField ctfMail" data-cn="XTextField"
      data-xi="xi-tf-2" data-xn="tfMail" id="xi-tf-2-xc" data-name="tfMail">
    
      <div data-dynamic-row="0" class="dynamic-row" id="xi-tf-8-xc_c_0">
        <input id="xi-tf-8" name="tfMail_dyn_tfMail_0" class="XItem XTextField" type="text">
      </div>
    
      <div data-dynamic-row="1" class="dynamic-row" id="xi-tf-8-xc_c_1">
        <input id="xi-tf-8" name="tfMail_dyn_tfMail_1" class="XItem XTextField" type="text">
      </div>
    
      <!-- ... -->
    
    </div>

    Parameters

    • Optional returnRepetitionContainer: boolean

      true to return the container of an individual repetition (when the current jQuery selection is a repeated element), false to always return the main xm-item-div container. Defaults to false when not specified.

    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<JQuery<HTMLElement>>
  • 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"
    $('[data-name=tfMail').getLabel().text();
    
    // Returns the label text of the second instance of a repeat
    // input field names "tfEmployees", eg. "Name of 2nd employee"
    $($('[data-org-name=tfEmployees]').get(1)).getLabel().text();

    Returns JQuery<JQuery<HTMLElement>>

    An array with all existing labels for the selected form fields.

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:

    $("[data-name='tfMail']").hasAttr("name"); // true
    $("[data-name='tfMail']").hasAttr("placeholder"); // true
    $("[data-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
  • on(event: "ready", 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.

    // Initialize 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.

        • Parameters

          • this: HTMLElement
          • event: TriggeredEvent
          • 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, i.e. 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.

        • Parameters

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

          Returns void

    Returns JQuery

    This JQuery instance for chaining.

  • Lets you register a callback that is invoked when the form is rendered and completely initialized.

    Parameters

    • event: "ready"

      The name of the event, i.e. ready.

    • callback: function

      A callback that is invoked when the form is rendered and completely initialized.

        • (this: HTMLElement): void
        • Parameters

          • this: HTMLElement

          Returns void

    Returns JQuery

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[data-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
  • This method was deprecated as it makes the form vulnerable to XSS (cross-site scripting) attacks.

    Use $.xutil.getFormParam and JQuery methods such as $.fn.text to insert data from URL parameters into the form.

    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 occurrence 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!.

    deprecated

    This method was deprecated as it makes the form vulnerable to XSS (cross-site scripting) attacks.

    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:

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

    For example:

    // Checks whether a valid mail address was entered.
    $('[data-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.
    $('[data-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.
    $('[data-name="tfName"').setError("Wrong name.");
    // Validates the input field and displays the error message.
    $('[data-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"
    $('[data-name=tf1]').setGroupReq("group1");
    
    // Add the input field "tf2" to the required group "group1"
    $('[data-name=tf2]').setGroupReq("group1");
    
    // Marks the input field "tf1" as an optional field
    $('[data-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"
    $('[data-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"
    $('[data-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.
    $('[data-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"
    $('[data-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".
    $('[data-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.
    $('[data-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.

    The use of this function is intended for text fields and text areas only and could therefore cause errors when used with other form element types.

    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.
    $('[data-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.

showStar

  • showStar(show: boolean): JQuery
  • Adds or 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]').showStar(false) // Removes the star from the label of the form field tf2.
    $('input[name=tf2]').showStar(true) // Adds the star to 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".

    Parameters

    • show: boolean

      true to display the star icon, false to hide the star icon.

    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(silent?: boolean): 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.
    $("[data-name='tfId']").on("keydown", function(event) { $(this).validate(); });
    
    // Validates the entire form
    var isFormValid = $(".xm-form").validate();

    Parameters

    • Optional silent: boolean

      Optional, default to false. When true, do not add any error messages to invalid elements. This is useful, for example, when you only want to check whether an element is valid without alerting the user.

    Returns boolean

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

vattr

  • vattr(validationAttributeName: string): JQuery
  • vattr(validationAttributeName: string, value: unknown): JQuery
  • Removes the given validation attribute from the form field. This is a low-level method, you should use one of the more specific methods for validation attributes, such as setRequired.

    Parameters

    • validationAttributeName: string

      Name of the validation attribute to remove.

    Returns JQuery

    This JQuery instance for chaining.

  • Set the validation attribute of the form field to the given value. This is a low-level method, you should use one of the more specific methods for validation attributes, such as setRequired.

    Parameters

    • validationAttributeName: string

      Name of the validation attribute to change.

    • value: unknown

      New value for the validation attribute. When undefined, the validation attribute is removed.

    Returns JQuery

    This JQuery instance for chaining.

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