This JQuery instance for chaining.
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).
this for chaining.
Retrieves the currently selected slot for the first element in the current selection.
The method to invoke on the appointment picker.
The currently selected slot, or undefined when no slot is selected. The promise is rejected when the current selection is empty.
Retrieves the currently selected slot for the first element in the current selection, in a synchronous fashion, i.e. by returning the slot directly instead of a promise. For consistency, all methods returns promises, use this method only when you need to access the slot synchronously, such as when working with APIs that do not support asynchronous callbacks.
The method to invoke on the appointment picker.
The currently selected slot, or undefined when no slot is selected.
Fetches all available slots of a given month and year for the first element in the selection.
The method to invoke on the appointment picker.
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.
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.
The method to invoke on the appointment picker.
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.
The method to invoke on the appointment picker.
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.
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.
The method to invoke on the appointment picker.
Day to select. When a property is not given, it defaults to the currently selected month or year.
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.
The method to invoke on the appointment picker.
Day to select. When a property is not given, it defaults to the currently selected date.
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']"));
The method to invoke on the appointment picker.
The slot to set, or undefined
to clear the selected slot.
Optional settings affecting how the slot is set.
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.
The method to invoke on the appointment picker.
true
to open the picker, false
to close it, undefined
to open it when closed and vice versa.
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.
The method to invoke on the appointment picker.
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.
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:
12,658
)EUR
or ¥
.s
) or at the end (value p
)true
, always pad the decimal digits with 0
s (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"
>
Optional settings for autoNumeric.
This JQuery instance for chaining.
Stops autoNumeric.
The name of the method to invoke.
This JQuery instance for chaining.
Retrieves the actual numerical value, irrespective of the current formatting options.
The name of the method to invoke.
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.
The name of the method to invoke.
The values, always formatted as 'nnnn.nn' with the period as the decimal point.
The name of the method to invoke.
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.
The name of the method to invoke.
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.
The name of the method to invoke.
Optional settings for autoNumeric.
This JQuery instance for chaining.
Sets the given number on this field, and formats it according to the current options.
The name of the method to invoke.
The new number to be set on this field.
This JQuery instance for chaining.
Updates autoNumeric's settings.
The name of the method to invoke.
New options that are to be set.
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.
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.
Name of the database query. Database queries can be created in the backend of XIMA formcycle.
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.
The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.
This JQuery 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.
Name of the database query. Database queries can be created in the backend of XIMA formcycle.
Name of a database column. This is used as the label displayed to the user.
Name of a database column. This is used as the value that is transmitted.
The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.
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.
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.
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
.
Name of the LDAP query. LDAP queries can be created in the backend of XIMA formcycle.
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
.
The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.
This JQuery 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.
Name of the LDAP query. LDAP queries can be created in the backend of XIMA formcycle.
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
.
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
.
The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.
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.
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 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.
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
.
Name of the query. LDAP and database queries can be created in the XIMA formcycle backend.
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.
The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.
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.
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
.
Name of the query. LDAP and database queries can be created in the XIMA formcycle backend.
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.
Name of the field to use as the value, e.g. the name of a database column or an LDAP property.
The callback function that is called when the user selects an option. For further details, see the help pages of jQueryUI on autocomplete.
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.
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() ;
This JQuery instance for chaining.
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();
Optional settings for the autocomplete.
This JQuery instance for chaining.
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.
Optional settings for the plugin.
This JQuery instance for chaining.
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.
Options to customize how many items are allowed, how to determine the number of repeated items, etc.
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");
The name of the method to invoke.
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);
The name of the method to invoke.
Index of the row to delete, starting at 0. If not given, deletes the last row.
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");
The name of the method to invoke.
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);
The name of the method to invoke.
The number of rows to set, ie. how many repeated items should exist.
This JQuery instance for chaining.
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");
The error message to be shown. Must not be the empty string.
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();
This JQuery instance for chaining.
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";
});
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 instance for chaining.
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>
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.
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.
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();
An array with all existing labels for the selected form fields.
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
Name of the attribute to check for.
Whether this element has the given attribute set.
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.
Optional settings for JSignature.
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.
The name of the method to invoke.
Optional settings for JSignature.
This JQuery instance for chaining.
Just clears the signature pad, data store (and puts back signature line and other decor).
The name of the method to invoke.
This JQuery instance for chaining.
Destroy the instance and restores the original input or textarea element.
The name of the method to invoke.
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.
The name of the method to invoke.
The name of the data format in which to return the data.
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).
The name of the method to invoke.
The name of the data format in which to return the data.
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.
The name of the method to invoke.
The name of the data format in which to return the data.
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.
The name of the method to invoke.
The name of the data format in which to return the data.
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().
The name of the method to invoke.
The name of the data format in which to return the data.
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.
The name of the method to invoke.
The name of the data format in which to return the data.
The current signature.
Returns the current stroke data.
The name of the method to invoke.
The name of the data format in which to return the data.
The current signature.
The name of the method to invoke.
The signature to be set.
The name of the data format in which to return the data.
This JQuery instance for chaining.
The name of the method to invoke.
The signature to be set.
The name of the data format in which to return the data.
This JQuery instance for chaining.
The name of the method to invoke.
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. If given, must be the same as the first entry in the data object array.
This JQuery instance for chaining.
The name of the method to invoke.
The signature to be set. It must be formatted according to the given data format.
The name of the data format in which to return the data.
This JQuery instance for chaining.
List all plugins that support importing / exporting data.
The name of the method to invoke.
The category of plugins to return.
A list of plugins for the given category.
Makes the canvas read-only and disable the jSignature buttons
The name of the method to invoke.
This JQuery instance for chaining.
Makes the canvas writable again and enables the jSignature buttons.
The name of the method to invoke.
This JQuery instance for chaining.
Checks whether any signature was drawn since the signature input field was initialized.
The name of the method to invoke.
true
iff the jSignature was modified, false
otherwise.
The name of the method to invoke.
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.
The name of the method to invoke.
Name of the setting to modify.
New value of the setting.
Pass true
iff the change should affect current signature or future strokes.
The updated value.
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();
});
The name of the event, ie. addRow
.
Callback for the add row event. It receives the container containing the newly created element.
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();
});
The name of the event, i.e. delRow
.
Callback for the row deletion event. It receives the container containing the deleted repeatable element. Note that it was already removed from the DOM.
This JQuery instance for chaining.
Lets you register a callback that is invoked when the form is rendered and completely initialized.
The name of the event, i.e. ready
.
A callback that is invoked when the form is rendered and completely initialized.
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".
This JQuery instance for chaining.
This method was deprecated as it makes the form vulnerable to XSS (cross-site scripting) attacks.
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!
.
This JQuery instance for chaining.
Sets the data type of a text input field (input
or textarea
). The following data types are available:
22.05.1990
.james@john.org
or θσερ@εχαμπλε.ψομ
.3
, 0
, or -21
.127.0.0.1
or 10.42.42.13
.2,00
, -3,95
, 0,00
or 897345,38
.0.03
, -99.2
, or 42
.0234995483
or +49 351 4459654
.02349
. Does not check whether such a code is actually registered within Germany.0
, 3
, oder 123
.0,00
or 2,34
.0,00
, 0
, 3,4
, or 3
.hh:mm
, e.g. 22:05
or 03:42
.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.
The new data type for the input text field.
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()
This JQuery instance for chaining.
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.
The error message to shown on the element.
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.
This JQuery instance for chaining.
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.
Arbitrary name of the required group for the input element.
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
.
This JQuery instance for chaining.
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.
The maximum number of checkboxes that can be checked.
This JQuery instance for chaining.
Removes the restriction on the maximum allowed number of selected options of a select element.
This JQuery instance for chaining.
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.
Maximum (inclusive) number of characters allowed.
This JQuery instance for chaining.
Removes the maximum length (number of characters) of the text that can be entered into an input field.
This JQuery instance for chaining.
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.
The largest (inclusive) value allowed for the input field.
This JQuery instance for chaining.
For an input text field with numeric input, removes the restriction on the largest allowed number.
This JQuery instance for chaining.
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.
The minimum (inclusive) number of checkboxes that can be checked.
This JQuery instance for chaining.
Removes the restriction on the minimum allowed number of selected options of a select element.
This JQuery instance for chaining.
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.
Minimum (inclusive) number of characters allowed.
This JQuery instance for chaining.
Removes the minimum length (number of characters) of the text that can be entered into an input field.
This JQuery instance for chaining.
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.
The smallest (inclusive) value allowed for the input field.
This JQuery instance for chaining.
For an input text field with numeric input, removes the restriction on the smallest allowed number.
This JQuery instance for chaining.
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");
Name of the referenced form field this field must equal.
This JQuery instance for chaining.
Removes the restriction that the form field needs to equal another form field.
This JQuery instance for chaining.
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.
If true
, marks the form field as required. If false
, the form field must not be filled out.
This JQuery instance for chaining.
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:
value
.value
must be a range in the format x-y
, eg. 2-37
.The name of the form field this field should depend on.
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.
Value for the comparison. If not given, defaults to the emtpy string.
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.
This JQuery instance for chaining.
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".
true
to display the star icon, false
to hide the star icon.
This JQuery instance for chaining.
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();
The (numerical) sum of the values of the selected form fields.
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();
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.
Whether the form field and all form fields it contains are valid.
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.
Name of the validation attribute to remove.
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.
Name of the validation attribute to change.
New value for the validation attribute. When undefined
, the validation attribute is removed.
This JQuery instance for chaining.
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);
If true
, shows the form field. If false
, hides the form field.
This JQuery instance for chaining.
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 classrequired-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
.