Interface JQuery

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.

throws

When the current selection is empty or does not contain an appointment picker

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"
>

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.

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.

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.

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.

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

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

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() ;

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();

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.

deprecated

Use $.xutil.inputElementCounter instead. A different library is used now.

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.

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

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

// Make input field "tfMail" repeatable
$("[data-name='tfMail']").dynamic({minSize: 3});

// Number of repetitions is initially 3
var repetitions = $("[data-name='tfMail']").dynamic("getRowSize");

// 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);

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");

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();

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";
});

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>

// 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();

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

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();
});

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();
});

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

Use $.xutil.getFormParam and JQuery methods such as {@link JQuery.text|$.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.

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

For example:

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

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.

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.

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.

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

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.

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

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

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

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

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

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");

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

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.

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

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

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();

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);