ioLoop Docs

Appearance

$io.form ​

Client API reference.

Functions ​

$io.form.customSubmitComplete ​

Notifies the ioLoop system that the custom form submission has been completed

Usage ​

js
$io.form.customSubmitComplete(returnInfo)

Description ​

Notifies the ioLoop system that the custom form submission has been completed. Use this function in the context of the cbFnSubmit callback for the $io.form.setupHooks function. Begore calling this function ensure that the $io.form.setStatus and $io.form.setStatusMessage functions are called so that the user notified of the result of the submission. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

returnInfo ​

Type: Object

Required: Yes

Optional. The returnInfo object provided to the cbFnSubmit callback of $io.form.setupHooks. If supplied, completion is applied to that specific returnInfo instance; if omitted, the active/default return info is used. Useful when you store returnInfo and complete later (async).

Output ​

Type: null

This function does not return a value.

$io.form.disableFileDelete ​

Disables or Enables the ability to delete existing files

Usage ​

js
$io.form.disableFileDelete(fieldName, value)

Description ​

Disables or Enables the ability to delete existing files associated with the specified field in the file upload widget. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

fieldName ​

Type: String

Required: Yes

The name of the field. Note: fields that associate files are of type Text and sub-type Files.

value ​

Type: Boolean

Required: Yes

true for disabling and false for enabling

Output ​

Type: null

This function does not return a value.

$io.form.disableFileUpload ​

Disables or Enables the file upload widget to add or drag-n-drop new files

Usage ​

js
$io.form.disableFileUpload(fieldName, value)

Description ​

Disables or Enables the file upload widget to add or drag-n-drop new files associated with the specified field. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

fieldName ​

Type: String

Required: Yes

The name of the field. Note: fields that associate files are of type Text and sub-type Files.

value ​

Type: Boolean

Required: Yes

true for disabling and false for enabling

Output ​

Type: null

This function does not return a value.

$io.form.getFieldValue ​

Gets the value of the specified field. Only works if a bound input element is present.

Usage ​

js
$io.form.getFieldValue(name)

Description ​

Gets the value of the specified field. Consider this function as an alternative to $io.dom.getVal where instead of an element selector, you provide the name of the database table field and the ioLoop system automatically sets the value of the associated element. NOTE: Only works if a bound input element is present. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

name ​

Type: String

Required: Yes

The name of the database table's field.

Output ​

Type: Any

Returns the current value of the bound form control. The return type depends on the field type. For example, numeric fields return numbers and Boolean fields return Boolean values. This function reads the control through its field-specific getter, not from the internal form-data object. Returns an empty string if the form, field, or bound element is unavailable.

$io.form.getFormData ​

Returns an object with properties corresponding to the form's fields

Usage ​

js
$io.form.getFormData()

Description ​

Returns an object with properties corresponding to the form's fields and their values. Usage of this function is valid only in the context of cbFnPostValidate, cbFnSubmit, cbFnSuccess and cbFnError callbacks for the $io.form.setupHooks function. In the context of the cbFnPostValidate callback of the $io.form.setupHooks fnction, the object returned can be modified i.e. the value of its properties can be changed, new properties can be added, or properties can be deleted. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

This function does not require parameters.

Output ​

Type: Object

Returns an object with properties corresponding to the form's fields and their values.

$io.form.getOriginalEditData ​

Returns the original editing data provided when the form was initialized in edit mode.

Usage ​

js
$io.form.getOriginalEditData()

Description ​

Returns the original editing data provided when the form was initialized in edit mode. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

This function does not require parameters.

Output ​

Type: Object

If the form is not in edit mode, this function returns an empty object, otherwise it will return the original editing data.

$io.form.getUnUploadedFiles ​

Returns an array containing the information about the files selected by the user for uploading but not yet uploaded

Usage ​

js
$io.form.getUnUploadedFiles(fieldName)

Description ​

Returns an array containing the information about the files selected by the user for uploading but not yet uploaded. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

fieldName ​

Type: String

Required: Yes

The name of the field for which the list of unuploaded files is to be returned. Note: fields that associate files are of type Text and sub-type Files.

Output ​

Type: Array

Returns an array containing the standard Web API "File" objects.

$io.form.getUploadedFiles ​

Returns an array containing the information about currently uploaded files

Usage ​

js
$io.form.getUploadedFiles(fieldName)

Description ​

Returns an array containing the information about currently uploaded files for the given field for the current record being edited, hence this function is generally useful when the form is in edit mode. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

fieldName ​

Type: String

Required: Yes

The name of the field in the table. Note: fields that associate files are of type Text and sub-type Files.

Output ​

Type: Array

  • Returns an array containing objects representing the files uploaded and associated with the provided field. Each object contains the following properties:
    • url: The url of the file.
    • path: The full path for the file
    • prefix: The storage path prefix; prefix + fileName forms the full path.
    • fileName: The file name
    • type: The file's MIME type
    • size: The size of the file

$io.form.isEditMode ​

Returns true if the form is being used to edit existing data.

Usage ​

js
$io.form.isEditMode()

Description ​

Returns true if the form is being used to edit existing data. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

This function does not require parameters.

Output ​

Type: Boolean

A value of true is returned if the form is in edit mode.

$io.form.lock ​

Lock the form to prevent submission or unlock it

Usage ​

js
$io.form.lock(value)

Description ​

Use this function to lock or unlock the form. Locking is used to prevent the form's submission e.g. when some time consuming task is in progress. When the processing is complete, the unlock option releases the lock. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

value ​

Type: Boolean

Required: Yes

Set to true to lock the form and false to unlock.

Output ​

Type: null

This function does not return a value.

$io.form.markUploadedFileForDelete ​

Mark or un-mark existing uploaded files for removal

Usage ​

js
$io.form.markUploadedFileForDelete(fieldName, fileName, value)

Description ​

Mark or un-mark existing uploaded files for removal when the form is submitted. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

fieldName ​

Type: String

Required: Yes

The name of the field. Note: fields that associate files are of type Text and sub-type Files.

fileName ​

Type: String

Required: Yes

The name of the file. This can be the fileName property of one of the objects in the array returned by the $io.form.getUploadedFiles function.

value ​

Type: Boolean

Required: Yes

true to mark for removal and false for clearing the mark

Output ​

Type: Boolean

true if the operation was successful or false otherwise.

$io.form.removeUnploadedFile ​

Removes an un-uploaded file from the file upload widget

Usage ​

js
$io.form.removeUnploadedFile(fieldName, index, fileName)

Description ​

Removes an un-uploaded file associated with a field based on either the index or the fileName parameter. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

fieldName ​

Type: String

Required: Yes

The name of the field. Note: fields that associate files are of type Text and sub-type Files.

index ​

Type: Number

Required: Yes

Index of the file to remove based on the array returned by the $io.form.getUnUploadedFiles function. Alternatively passing -1 would make the ioLoop system determine the index using the fileName parameter instead.

fileName ​

Type: String

Required: Yes

If the index parameter is >=0, this parameter is ignored. Otherwise ioLoop system determines the index using the value of this parameter.

Output ​

Type: Boolean

true if the operation was successful or false otherwise.

$io.form.reset ​

Reset the form and clear the contents of the field input elements.

Usage ​

js
$io.form.reset()

Description ​

Use this function to clear the contents of the field input elements, including any validation error messages and validation state information. This function mimics the behavior exhibited when the user clicks the reset button on the form. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

This function does not require parameters.

Output ​

Type: null

This function does not return a value.

$io.form.save ​

Triggers a form submission using the data entered by the user or with custom data.

Usage ​

js
$io.form.save(data)

Description ​

Use this function to trigger a form submission using the data entered by the user or with custom data. This function is useful when implementing your own submit button or UI. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

data ​

Type: Object

Required: Yes

Object representing the custom data to use instead of the data entered by the user. In this case the input validation step will be skipped, and the system will directly proceed to the submission step. If the form is attached to a database table, this object must contain properties that match the fields of the table. If undefined or null, the user entered data will first be validated and then submitted.

Output ​

Type: null

This function does not return a value.

$io.form.setFieldValue ​

Sets the value of the specified field to the provided value. Only works if a bound input element is present.

Usage ​

js
$io.form.setFieldValue(name, value)

Description ​

Sets the value of the specified field to the provided value. Consider this function as an alternative to $io.dom.setVal where instead of an element selector, you provide the name of the database table field and the ioLoop system automatically sets the value of the associated element. NOTE: Only works if a bound input element is present. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

name ​

Type: String

Required: Yes

The name of the database table's field.

value ​

Type: String

Required: Yes

The value of the field.

Output ​

Type: null

This function does not return a value.

$io.form.setStatus ​

Set the form's processing status to provide feedback

Usage ​

js
$io.form.setStatus(value, returnInfo)

Description ​

Sets the form's processing status to success or error to provide feedback. Use this function in the context of cbFnPreValidate, cbFnPostValidate, and cbFnSubmit callbacks of the $io.form.setupHooks functions. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

value ​

Type: Boolean

Required: Yes

The true or false value to set.

returnInfo ​

Type: Object

Required: Yes

Optional. The returnInfo object provided to the cbFnPreValidate, cbFnPostValidate, or cbFnSubmit callbacks of $io.form.setupHooks. If supplied, the status is applied to that specific returnInfo instance; if omitted, the active/default return info is used. Useful when you store returnInfo and set status later (async).

Output ​

Type: null

This function does not return a value.

$io.form.setStatusMessage ​

Set the form's processing status message to provide feedback

Usage ​

js
$io.form.setStatusMessage(message)

Description ​

Sets the form's processing status message to provide feedback. Use this function in the context of cbFnPreValidate, cbFnPostValidate, and cbFnSubmit callbacks for the $io.form.setupHooks function. NOTE: This function only works for ioLoop's Form type Pages.

Parameters ​

message ​

Type: String

Required: Yes

The message to set. This can also be an HTML string. e.g. you can use the string generated from $io.content.alert to display your message in a prominent way.

returnInfo ​

Type: Object

Required: Yes

Optional. The returnInfo object provided to the cbFnPreValidate, cbFnPostValidate, or cbFnSubmit callbacks of $io.form.setupHooks. If supplied, the status message is applied to that specific returnInfo instance; if omitted, the active/default return info is used. Useful when you store returnInfo and set status later (async).

Output ​

Type: null

This function does not return a value.

$io.form.setupHooks ​

Sets up callback hooks for various events in ioLoop Forms including initialization, input validation, data submission, etc.

Usage ​

js
$io.form.setupHooks(cbFnInit, cbFnPreValidate, cbFnPostValidate, cbFnSubmit, cbFnSuccess, cbFnError)

Description ​

Sets up callback hooks for various events in ioLoop Forms including initialization, input validation, data submission, etc.

Parameters ​

cbFnInit ​

Type: Function

Required: Yes

This callback function will be called during the initialization process of the form. If you plan on adding logic that takes time to complete (i.e. executes in the background), we recommend using the $io.form.lock function to lock the form and unlock it after the task is complete.

cbFnPreValidate ​

Type: Function

Required: Yes

This callback function is invoked after the form submission process is triggered, but before ioLoop's automatic field input validation process. Use this function to implement custom or complex validation logic prior to the automatic validation process. Use the $io.form.getFieldValue and $io.form.setFieldValue functions to get/set the value of the fields for which input elements are present. Use the $io.form.setStatus function with a false value, to indicate any errors. The $io.form.setStatusMessage function can be used to specify the actual error to the user. If there are no pre-validation errors, you do not need to call $io.form.setStatus with a true value. Please note that you cannot execute a background task and wait for it's completion here.

cbFnPostValidate ​

Type: Function

Required: Yes

This callback function is invoked after ioLoop's automatic field input validation process but prior to data submission. Use the $io.form.getFormData function to retrieve the object representing the data that will be submitted. You can modify the object's properties or add new properties to this object as required. At this stage of the form's submission use of $io.form.getFieldValue and $io.form.setFieldValue functions is not recommended since the system has already progressed beyond the reading of field input values. Use the $io.form.setStatus function with a false value, to indicate any errors. The $io.form.setStatusMessage function can be used to specify the actual error to the user. If there are no post-validation errors, you do not need to call $io.form.setStatus with a true value. Please note that you cannot execute a background task and wait for it's completion here.

cbFnSubmit ​

Type: Function

Required: Yes

This callback function is invoked only in the case of custom forms which are not attached to any database table. Implement your own form data submission logic here. The $io.form.getFormData function can be used retrieve the object representing the data to be submitted. The data can be sent to HTTP/REST API calls, webhooks or any other destination including ioLoop's database (using the functions provided by $io.db). Since submission of data is usually an asynchronous task, you need to call the $io.form.customSubmitComplete function after your custom submission logic finishes. Prior to calling $io.form.customSubmitComplete, you need to call $io.form.setStatus to indicate the success or failure status. The $io.form.setStatusMessage function can be used to indicate the outcome information. If not, he ioLoop form's default success and error messages will be shown.

cbFnSuccess ​

Type: Function

Required: Yes

This callback function is called after the form's data has been submitted succesfully. The $io.form.getFormData function can be used retrieve the object representing the data that was submitted. The $io.form.setStatusMessage function can be used to override the form's default success message.

cbFnError ​

Type: Function

Required: Yes

This callback function is called if there is an error submitting the form's data. The function is passed a String parameter that contains any error information if available.The $io.form.setStatusMessage function can be used to override the form's default error message.

Output ​

Type: null

This function does not return a value.