ioLoop Docs

Appearance

$io.dom ​

Client API reference.

Functions ​

$io.dom.dataDesignElementSel ​

Returns a selector object for elements dynamically added from data design templates. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

Usage ​

js
$io.dom.dataDesignElementSel(templateId, elName, id1, id2)

Description ​

Returns a selector object for an element or multiple dynamic elements that were dynamically added from data design templates using the $io.content.fromDataDesign function. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

Parameters ​

templateId ​

Type: String

Required: Yes

Name of the Data Design element containing the template design. You may use the App Assets side-bar (on the left) to selecting the name of the template.

elName ​

Type: String

Required: Yes

Name of the desired element. Note that this is not the element's ID as for dynamically added elements, the ID is also dynamic. You may use the App Assets side-bar (on the left) to select the element from the template.

id1 ​

Type: String

Required: Yes

Primary identifier of the dynamically added element. If empty string or null, the selector may match multiple instances of the dynamically added element. You can "id" property of the event information object to identify the element in contexts like the cbFn callback function of the $io.dom.setEventListener function.

id2 ​

Type: String

Required: Yes

Specifies a secondary identifier for the dynamically added element. If empty string or null, the selector may match multiple instances of the dynamically added element.

Output ​

Type: Object

The element selector object which can be used with functions that require an element selector object as a parameter. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

$io.dom.domSel ​

Returns a selector object for a DOM selector string. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

Usage ​

js
$io.dom.domSel(selector)

Description ​

Returns a selector object for a DOM selector string. The selector is passed through to the underlying DOM operation and may match one or more elements. Prefer $io.dom.elementIdSel or $io.dom.dataDesignElementSel for normal app element targeting, and use $io.dom.domSel when you need a selector expression. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

Usage Scenarios ​

  • Target elements using a CSS selector when elementIdSel or dataDesignElementSel is not specific enough
  • Apply one ioLoop DOM operation to multiple matching elements

Parameters ​

selector ​

Type: String

Required: Yes

DOM selector string to use for the target elements. Standard CSS selector syntax is supported.

Output ​

Type: Object

The element selector object which can be used with functions that require an element selector object as a parameter. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

$io.dom.elementByName ​

Returns a DOM element by its element name.

Usage ​

js
$io.dom.elementByName(name)

Description ​

Returns the first DOM element whose element name matches the provided value. Note: This returns a DOM node (not a selector object).

Usage Scenarios ​

  • Get a DOM element by element name
  • Use an element name to update content or styles

Parameters ​

name ​

Type: String

Required: Yes

Element name as defined in the page or form.

Output ​

Type: Object

The DOM element if found, otherwise null.

$io.dom.elementIdSel ​

Returns a selector object for the specified element identifier.Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

Usage ​

js
$io.dom.elementIdSel(id)

Description ​

Returns a selector object for a specified element.Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

Parameters ​

id ​

Type: String

Required: Yes

Identifier of the element. You may use the App Assets side-bar (on the left) to copy the identifier by selecting an element.

Output ​

Type: Object

The element selector object which can be used with functions that require an element selector object as a parameter. Remember this selector object is intended for use with ioLoop API and is not a DOM node or a Jquery object.

$io.dom.getAttr ​

Returns the value of the HTML attribute for an element given a selector object

Usage ​

js
$io.dom.getAttr(elemSel, attrName)

Description ​

Returns the value of the HTML attribute for an element.

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

attrName ​

Type: String

Required: Yes

The HTML attribute to get the value of.

Output ​

Type: String

The value of the attribute if present.

$io.dom.getCheckedState ​

Gets the value of the 'checked' property of a Checkbox or Toggle Switch element given a selector object

Usage ​

js
$io.dom.getCheckedState(elemSel)

Description ​

Gets the value of an element's 'checked' HTML DOM property. This is equivalent to using the $io.dom.getProp function with the 'checked' property. Use this for Checkbox or Toggle Switch elements.

Usage Scenarios ​

  • Know if a Checkbox element is checked
  • Know if a Checkbox element is unchecked
  • Know if a Toggle Switch element is off
  • Know if a Toggle Switch element is on

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

Output ​

Type: Boolean

The true or false value.

$io.dom.getDisabledState ​

Gets the value of the 'disabled' property of an element given a selector object

Usage ​

js
$io.dom.getDisabledState(elemSel)

Description ​

Gets the value of an element's 'disabled' HTML DOM property. This is equivalent to using the $io.dom.getProp function with the 'disabled' property.

Usage Scenarios ​

  • Disable an element
  • Enable an element

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

Output ​

Type: Boolean

The true (for disabled) or false (for enabled) state of the element.

$io.dom.getHtml ​

Returns the HTML or text content of an element given a selector object

Usage ​

js
$io.dom.getHtml(elemSel)

Description ​

Returns the current HTML or text content of an element given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

Output ​

Type: String

The HTML or text content.

$io.dom.getProp ​

Gets the value of a HTML DOM node property of an element given a selector object

Usage ​

js
$io.dom.getProp(elemSel, propName)

Description ​

Gets the value of an element's HTML DOM node property given a selector object.

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

propName ​

Type: String

Required: Yes

The name of the property to get. E.g., 'checked'

Output ​

Type: Any

The value of the property. The value's type is based on the property. e.g., the 'checked' property is of type Boolean.

$io.dom.getVal ​

Gets the value of an element that accept user input given a selector object

Usage ​

js
$io.dom.getVal(elemSel)

Description ​

Gets the value of an element that accepts user's input. This works for ioLoop's Input, Dropdown and Multi-line Elements which correspond to the HTML input, select and textarea elements.

Usage Scenarios ​

  • Get input element's value given a selector object
  • Get dropdown (HTML select) element's value given a selector object
  • Get the selected option for dropdown (HTML select) element given a selector object
  • Get multi-line (HTML textarea) element's value given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

Output ​

Type: String

The current value of the element as a String.

$io.dom.initDataDesignCheckbox ​

Initialize toggle switch or checkbox elements dynamically added from data design template

Usage ​

js
$io.dom.initDataDesignCheckbox(designId, elName, id1, id2)

Description ​

When using the Toggle Switch or Checkbox element inside a Data Design template, it is important to initialize them using this function, after they have been added to the page or form. This is due to the way Bootstrap 4's custom control checkbox and toggle switch implementations require the label element's 'for' attribute to be linked to the input element's id.

Parameters ​

designId ​

Type: String

Required: Yes

Name of the Data Design element containing the template design. You may use the App Assets side-bar (on the left) to selecting the name of the template.

elName ​

Type: String

Required: Yes

The name of the desired Toggle Switch or Checkbox element. You may use the App Assets side-bar (on the left) to select the element from the template.

id1 ​

Type: String

Required: Yes

Primary identifier of the dynamically added element. Normally, you would leave this as an empty string so that all added Checkbox or Toggle Switch elements will get initialized.

id2 ​

Type: String

Required: Yes

Specifies a secondary identifier for the dynamically added element. Normally, you would leave this as an empty string so that all added Checkbox or Toggle Switch elements will get initialized.

Output ​

Type: null

This function does not return a value.

$io.dom.modClasses ​

Modifies CSS classes on an element given a selector object

Usage ​

js
$io.dom.modClasses(elemSel, classesToAdd, classesToRemove)

Description ​

Adds/Removes CSS classes from an element given a selector object

Usage Scenarios ​

  • Add CSS classes to an element given a selector object
  • Remove CSS classes from an element given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

classesToAdd ​

Type: String

Required: Yes

One or more CSS classes to be added. Multiple classes can be specified by separation with spaces.

classesToRemove ​

Type: String

Required: Yes

One or more CSS classes to be removed. Multiple classes can be specified by separation with spaces.

Output ​

Type: null

This function does not return a value.

$io.dom.setAttr ​

Sets the value of the HTML attribute for an element given a selector object

Usage ​

js
$io.dom.setAttr(elemSel, attrName, attrVal)

Description ​

Sets the value of the HTML attribute for an element given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

attrName ​

Type: String

Required: Yes

The HTML attribute to set the value of.

attrVal ​

Type: String

Required: Yes

The new value of the attribute.

Output ​

Type: null

This function does not return a value.

$io.dom.setCheckedState ​

Sets the value of the 'checked property of a Checkbox or Toggle Switch elements given a selector object

Usage ​

js
$io.dom.setCheckedState(elemSel, value)

Description ​

Sets the value of an element's 'checked' HTML DOM property. This is equivalent to using the $io.dom.setProp function with the 'checked' property. Use this for Checkbox or Toggle Switch elements.

Usage Scenarios ​

  • Check a Checkbox element
  • Un-check a Checkbox element
  • Turn on a Toggle Switch element
  • Turn off a Toggle Switch element

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

value ​

Type: Boolean

Required: Yes

The true or false value to set.

Output ​

Type: null

This function does not return a value.

$io.dom.setCss ​

Sets the value of any CSS property for an element given a selector object

Usage ​

js
$io.dom.setCss(elemSel, cssProperty, value)

Description ​

Sets the value of a CSS property for an element given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

cssProperty ​

Type: String

Required: Yes

The CSS property in camel case, e.g., 'backgroundColor' for the 'background-color' property, etc.

value ​

Type: String

Required: Yes

The value of the property.

Output ​

Type: null

This function does not return a value.

$io.dom.setDisabledState ​

Sets the value of the 'disabled' property of elements given a selector object

Usage ​

js
$io.dom.setDisabledState(elemSel, value)

Description ​

Sets the value of an element's 'disabled' HTML DOM property. This is equivalent to using the $io.dom.setProp function with the 'disabled' property.

Usage Scenarios ​

  • Disable an element
  • Enable an element

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

value ​

Type: Boolean

Required: Yes

The true (for disabled) or false (for enabled) value to set.

Output ​

Type: null

This function does not return a value.

$io.dom.setEventListener ​

Handle HTML DOM events like 'click', 'change', 'keyup' and many more on an element.

Usage ​

js
$io.dom.setEventListener(elemSel, eventName, cbFn)

Description ​

Sets a DOM event handler callback for the specified event (e.g., 'click', 'change', 'keyup', etc) on an element.

Usage Scenarios ​

  • Know when the user clicks any element like a Button or Link
  • Know when the user changes the dropdown element (HTML select) selection
  • Know when the user types in an input element
  • Know when the user types in an multi-line (HTML Text area) element

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

eventName ​

Type: String

Required: Yes

The DOM event name e.g., 'click', 'change', 'keyup', etc.

cbFn ​

Type: Function

Required: Yes

The callback function that will be called when the event occurs. Note that preventDefault has already been called and propogation is already prevented before the function is called. Passing null will remove all handlers for this event for the specified element. The function is passed an event information object with the following properties:

  • domEventInfo: JQuery event object.
  • domEvent: Native DOM event object from the JQuery event's originalEvent property, or null when unavailable.
  • element: JQuery event's currentTarget value.
  • name: The element name for events from dynamically added elements generated using $io.content.fromDataDesign and added, empty string otherwise.
  • id: The ID1 value for dynamically added elements, empty string otherwise.
  • id2: The ID2 value for dynamically added elements, empty string otherwise.
  • design: The name of the Data Design (for dynamically added elements).
  • xpos: The value of pageX in a JQuery event, which represents the mouse position relative to the left edge of the document.
  • ypos: The value of pageY in a JQuery event, which represents the mouse position relative to the top edge of the document.

Output ​

Type: null

This function does not return a value.

$io.dom.setFeedback ​

Sets the input validation feedback for an element

Usage ​

js
$io.dom.setFeedback(elemSel, type)

Description ​

Use this function to indicate the validity of the user's input. This works on elements that accept user's input.

Usage Scenarios ​

  • Show that the user entered an invalid value
  • Show that the user entered an valid value

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

type ​

Type: String

Required: Yes

  • The type of feedback to indicate:
    • 'zn-valid': Indicates a valid input feedback using a green border and check mark.
    • 'zn-invalid': Indicates an invalid input feedback using a red border and exclamation mark.
    • 'zn-cleared': Clears any current feedback.

Output ​

Type: null

This function does not return a value.

$io.dom.setHtml ​

Sets/Replaces, Appends or Prepends HTML content of an element, given a selector object

Usage ​

js
$io.dom.setHtml(elemSel, opType, contentStr)

Description ​

Changes the html content of an element. Using the opType parameter you can set, append or prepend the content.

Usage Scenarios ​

  • Set the HTML content of an element given a selector object
  • Set the text content of an element given a selector object
  • Append HTML content into an element given a selector object
  • Append text content into an element given a selector object
  • Prepend HTML content into an element given a selector object
  • Prepend text content into an element given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

opType ​

Type: String

Required: Yes

  • Use the following values to control the behavior:
  • 'zn-prepend' or 'prepend': Add the new content before existing content inside the element.
  • 'zn-append' or 'append': Add the new content after existing content inside the element.
  • 'zn-set' or 'set': Sets (i.e., replaces) the current content with the new one.

contentStr ​

Type: String

Required: Yes

The HTML or text content.

Output ​

Type: null

This function does not return a value.

$io.dom.setProp ​

Sets the value of a HTML DOM node property of elements given a selector object

Usage ​

js
$io.dom.setProp(elemSel, propName, value)

Description ​

Sets the value of an element's HTML DOM node property given a selector object.

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

propName ​

Type: String

Required: Yes

The name of the property to set. E.g., 'checked'

value ​

Type: Any

Required: Yes

The value to set. The value provided needs to be of a type that is supported by the property being used. e.g., the 'checked' property is of type Boolean.

Output ​

Type: null

This function does not return a value.

$io.dom.setVal ​

Sets the value of elements that accept user input given a selector object

Usage ​

js
$io.dom.setVal(elemSel, value)

Description ​

Sets the value of an element that accepts user's input. This works for ioLoop's Input, Dropdown and Multi-line Elements which correspond to the HTML input, select and textarea elements.

Usage Scenarios ​

  • Set input element's value given a selector object
  • Set dropdown (HTML select) element's value given a selector object
  • Set the selected option for dropdown (HTML select) element given a selector object
  • Set multi-line (HTML textarea) element's value given a selector object

Parameters ​

elemSel ​

Type: Object

Required: Yes

Element selector object obtained using $io.dom.elementIdSel, $io.dom.dataDesignElementSel, or $io.dom.domSel functions.

value ​

Type: String

Required: Yes

The value to set. Note that this parameter is of type String.

Output ​

Type: null

This function does not return a value.