Simple modal overlay dialog that shows the pending uploads.
Manager for handling AJAX uploads, i.e. upload elements where the selected files are uploaded automatically in the background.
The API of the appointment picker, which contains several functions to work with appointment pickers, such as getting the currently selected date or time, or changing the selected date or time.
The API is available via $.xutil.appointmentPicker.
Utilities for working with hashes (checksums).
The entry point for the character counter. It adds a simple character to input and textarea elements.
A callback that is invoked when the form is rendered and completely initialized. This property only lets you set a single callbac. You can also add multiple listeners like this:
$("form.xm-form").on("ready", myListener);A flag that indicates whether the form is rendered and completly initialized. This is similar to the the onready callback which is invoked when the form becomes ready, but lets you query the status instead.
Given an upload element, updates the image preview with the given images.
The file input element of the upload form element.
List of preview images to draw. When empty, the preview images are all removed.
Performs an AJAX request to a database query created in the formcycle backend configuration interface. If the
query contains any placeholders (question marks ?), exactly that number of parameters needs to be given or
the query fails.
// Callback when the query succeeded
function successFunc(data) {
// Do something with the returned data in JSON format
console.log(data);
if (data.result.length > 0) {
$('[name=tfName]').val(data.result[0].name);
}
}
// Callback when the query failed
function errorFunc(jqXHR, textStatus, errorThrown) {
// Handle error
console.error(errorThrown);
}
function getData(paramID, paramMail) {
$.xutil.getDataQuery('SampleDbQueryName', [paramID, paramMail],
successFunc, errorFunc);
}
// Run database query with parameter values taken from form fields
getData($('[name=tfId]').val(), $('[name=tfMail]').val());Name of the database query, as set in the formcycle backend configuration interface.
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.
Callback called when the database query succeeds.
Callback called when the database query fails.
A promise that is fulfilled with the data returned by the database query. Each item in the array corresponds to one row in the database.
Retrieves the value of the URL parameter for the given name. Returns the default if no such parameter exists.
If a parameter name occurs multiple times, all values are returned, separated with a comma (,).
If the URL is as follows:
https://formcloud.de/formcycle/form/provide/9999?name=James&preview&mode=&name=John
Then this function returns:
$.xutil.getFormParam("name") // => "James,John"
$.xutil.getFormParam("preview"); // => undefined
$.xutil.getFormParam("mode"); // => undefined
$.xutil.getFormParam("owner", "anonymous"); // => "anonymous"Name of the URL parameter to retrieve.
Default value in case the URL parameter is not set.
The value of the given parameter name, or the default value if no such parameter exists.
Finds a FORM-specific URL of a certain type. If you need to access a formcycle resource, use this function as the URLs may change in future versions.
The following types of URLs are available:
/formcycle.dataquery_db instead.// This returns "/formcycle/datenquellecsv/"
$.xutil.getFormUrl("datasource_csv", undefined);Type of the form URL to be retrieved.
Default value to be returned when no URL was found.
The form URL of the given type. If no such type exists, the given default value.
Performs an AJAX request to an LDAP query created in the formcycle backend configuration interface. If the
query contains any placeholders (question marks ?), exactly that number of parameters needs to be given or
the query fails.
// Callback when the query succeeded
function successFunc(data) {
// Do something with the returned data in JSON format
console.log(data);
if (data.length > 0) {
$('[name=tfName]').val(data[0].name);
}
}
// Callback when the query failed
function errorFunc(jqXHR, textStatus, errorThrown) {
// Handle error
console.error(errorThrown);
}
function getData(paramID, paramMail) {
$.xutil.getDataQuery('SampleDbQueryName', [paramID, paramMail],
successFunc, errorFunc);
}
// Run LDAP query with parameter values taken from form fields
getData($('[name=tfId]').val(), $('[name=tfMail]').val());Name of the LDAP query, as set in the formcycle backend configuration interface.
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.
Callback called when the LDAP query succeeds.
Callback called when the LDAP query fails.
A promise that is fulfilled with the data returned by the database query. Each item in the array corresponds to one entry in the active directory.
Helper function to check the current state of the form. States can be created and managed in the workflow configuration.
// When the form is opened for the first time (no state set), set
// the default value for the form element "tfMail".
if ($.xutil.isStatus(undefined)) {
$("[data-name='tfMail']").val("default@mail.com");
}
// Check for a certain state
var isArchived = $.xutil.isStatus("Archived");Name of the state to check against the current state. You may pass undefined to check
whether no state is set, ie. whether the form has not yet been submitted.
true iff the current state of the form is the same as the given state, false otherwise.
Loads saved data into the form, filling all form elements with the saved values.
Compared with loadFromString, this method uses the object instead of a serialized string.
Save data as returned by save.
Loads saved data into the form, filling all form elements with the saved values.
Compared with load, this method uses the serialized string instead of an object.
Save data as returned by saveAsString.
Removes an event callback previously added via on.
Type of the event name for which to remove a listener.
Name of the event to for which to remove a listener.
Listener to remove.
Removes a callback that was added via onSubmit.
Callback to remove.
Register a callback function for one of the events issued during the lifecycle of a form.
Uncaught errors in callbacks are caught, logged, and ignored otherwise.
Type of the event name for which to register a listener.
Name of the event to listen to.
Listener that is invoked when the event occurs.
A disposable that can be used to remove the listener.
Registers a callback for the print service. The callbacks is invoked by the print service before the form is printed. You can use this callback to prepare the form for printing. When the callback returns a promise, the print service waits for the promise to fulfill before printing the form. When the promise is rejected, the error is logged, but does not prevent the print.
Callback to register.
Invokes the given callback function as soon as {@link document.readyState}
changes to complete. When the ready state is already complete, the
callback is run immediately (but still asynchronously during one of the
next event loop cycles).
This is similar to JQuery's on ready callback ($(function() { })), but
that function makes use of DOMContentLoaded and may run the callback when
the document's ready state is still loading. When you need the document to
be fully loaded, use this function.
For example, when you want to calculate the width or height of an element,
you may get the wrong result when the document's ready state is still
loading, since stylesheets or font faces inside stylesheets may not have
loaded yet.
Callback to invoke once the document's ready
state changes to complete.
Helper function to run code when the form is currently in a given state. States can be created in the workflow configuration.
// When the form is opened for the first time (no state set),
// set the default value for the form element "tfMail"
$.xutil.onStatus(undefined, function() {
$("[data-name='tfMail']").val("default@mail.com");
});
$.xutil.onStatus('Archiv', function() {
// Do something when form is archived
});Name of the state to check against the current state. You may pass undefined to check
whether no state is set, ie. whether the form has not yet been submitted.
Function that is executed immediately (synchronous to the caller) in case the current state of the form matches the given state.
Helper function to run code when the form has got no state currently, ie. when it has not been submitted yet. States can be created in the workflow configuration.
// When the form is opened for the first time (no state set), set
// the default value for the form element tfMail.
$.xutil.onStatus(function() {
$("[data-name='tfMail']").val("default@mail.com");
});Function that is executed immediately (synchronous to the caller) in case the current state of the form matches the given state.
Registers a callback for when the form is submitted. Can be used e.g. to run additional actions or to prevent the submission.
The callback is called after the form was validated, if the submit button requires validation.
$.xutil.onSubmit(() => doSomething())
$.xutil.onSubmit(({submissionBlocked}) => {
// Check if the submission is already blocked
if (submissionBlocked) {
return;
}
// Custom code to be run on submission
// Custom logic to check whether the form submission should be cancelled.
const preventSubmission = customLogic();
return { preventSubmission };
});Callback to invoke when the form is about to be submitted.
A disposable that can be used to remove the callback. This is equivalent to calling offSubmit with the callback passed to this method.
A function that is called when the form is submitted. The default implementation simply returns true, so you
can override this function without calling the original function. When you would like to cancel the
submission of the form, return false from this method.
$.xutil.onsubmit = function(isFormValid) {
// Custom code to be run on submission.
// ...
// Custom logic to check whether the form submission should be cancelled.
return isFormValid;
};Whether the form is currently valid (eg. if all required fields have been filled out etc.)
true to proceed with form submission, false or undefined to prevent the form's submission.
Parses the given value as a decimal number and returns the value. Accepts both a period and a comma as the decimal separator.
Value to parse.
The string parsed as a number, 0 if undefined was passed.
Creates an object with all data from the current form, including all repeated form fields and all uploaded files.
Compared with save, this returns an object instead of a serialized string.
An object with the form data.
Creates a string with a serialized representation of all data from the current form, including all repeated form fields and all uploaded files.
Compared with save, this returns a serialized string instead of an object.
A serialized string with the form data.
Fires an event of the given types, invoking all listeners that were registered via on.
Type of the event name to trigger.
Name of the event.
Data to pass to the event listeners.
This object contains formcycle specific utility functions.