Ctrlk
Visit our websiteTry a DemoPricingContact
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Zingy API For Page Flow

Function: $zn.dom.dataDesignElementSel

Description

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

Parameters

This function needs the following 4 parameters:

templateId (String)

Name of the Data Design element containing the template design.

elName (String)

Name of the desired element. Note that this is not the element's ID as for dynamically added elements, the ID is also dynamic.

id1 (String)

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 $zn.dom.setEventListener function.

id2 (String)

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.

Return Information

Return Value Type

This function returns a value of type: Object

Return Value Description

The return value of function $zn.dom.dataDesignElementSel is described below:

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 Zingy API and is not a DOM node or a Jquery object.

Function: $zn.dom.elementIdSel

Description

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

Parameters

This function needs the following 1 parameters:

id (String)

Identifier of the element.

Return Information

Return Value Type

This function returns a value of type: Object

Return Value Description

The return value of function $zn.dom.elementIdSel is described below:

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 Zingy API and is not a DOM node or a Jquery object.

Function: $zn.dom.getAttr

Description

Returns the value of the HTML attribute for an element.

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

attrName (String)

The HTML attribute to get the value of.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.dom.getAttr is described below:

The value of the attribute if present.

Function: $zn.dom.setAttr

Description

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

Parameters

This function needs the following 3 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

attrName (String)

The HTML attribute to set the value of.

attrVal (String)

The new value of the attribute.

Return Information

This function does not return any value

Function: $zn.dom.setHtml

Description

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

Parameters

This function needs the following 3 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

opType (String)

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

contentStr (String)

The HTML or text content.

Return Information

This function does not return any value

Function: $zn.dom.getHtml

Description

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

Parameters

This function needs the following 1 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.dom.getHtml is described below:

The HTML or text content.

Function: $zn.dom.setCss

Description

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

Parameters

This function needs the following 3 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

cssProperty (String)

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

value (String)

The value of the property.

Return Information

This function does not return any value

Function: $zn.dom.modClasses

Description

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

Parameters

This function needs the following 3 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

classesToAdd (String)

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

classesToRemove (String)

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

Return Information

This function does not return any value

Function: $zn.dom.setVal

Description

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

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

value (String)

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

Return Information

This function does not return any value

Function: $zn.dom.getVal

Description

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

Parameters

This function needs the following 1 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.dom.getVal is described below:

The current value of the element as a String.

Function: $zn.dom.setProp

Description

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

Parameters

This function needs the following 3 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

propName (String)

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

value (Any)

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.

Return Information

This function does not return any value

Function: $zn.dom.getProp

Description

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

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

propName (String)

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

Return Information

Return Value Type

This function returns a value of type: Any

Return Value Description

The return value of function $zn.dom.getProp is described below:

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

Function: $zn.dom.setCheckedState

Description

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

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

value (Boolean)

The true or false value to set.

Return Information

This function does not return any value

Function: $zn.dom.getCheckedState

Description

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

Parameters

This function needs the following 1 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.dom.getCheckedState is described below:

The true or false value.

Function: $zn.dom.setDisabledState

Description

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

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

value (Boolean)

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

Return Information

This function does not return any value

Function: $zn.dom.getDisabledState

Description

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

Parameters

This function needs the following 1 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.dom.getDisabledState is described below:

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

Function: $zn.dom.setFeedback

Description

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

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

type (String)

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

Return Information

This function does not return any value

Function: $zn.dom.setEventListener

Description

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

Parameters

This function needs the following 3 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

eventName (String)

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

cbFn (Function)

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. - element: JQuery event's currentTarget value. - name: The element name for events from dynamically added elements generated using $zn.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.

Return Information

This function does not return any value

Function: $zn.dom.initDataDesignCheckbox

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

This function needs the following 4 parameters:

designId (String)

Name of the Data Design element containing the template design.

elName (String)

The name of the desired Toggle Switch or Checkbox element.

id1 (String)

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

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.

Return Information

This function does not return any value

Function: $zn.content.fromDataDesign

Description

Generates HTML content string from a Data Design template and replaces place-holder fields with actual information from the provided data parameter e.g. a database record. You can use the function repeatadly to create multiple instance of the template with different data e.g. elements of an array

Parameters

This function needs the following 4 parameters:

designId (String)

Name of the Data Design element containing the template design.

id1 (String)

Primary identifier to use for the generated elements. Provide a value that can be used to uniquely identify this generated instance of the template. This can be the record identifier, or an array index, etc for example.

id2 (String)

Specifies a secondary identifier for elements or an empty string.

data (Object)

Object containing properties with values for the actual information to be filled in for the place-holder fields. Note: The property name needs to exactly match the name of the place-holder field name.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.content.fromDataDesign is described below:

HTML string that can be added to the page or form using the $zn.dom.setHtml function.

Function: $zn.content.badgedText

Description

Generates HTML content for the Badged text element, which is based on the Bootstrap 4 Badge component.

Parameters

This function needs the following 3 parameters:

type (String)

Use 'zn-badge-pill' for a Pill style badge or 'zn-badge-normal' for the regular shape.

color (String)

Specify 'zn-blue', 'zn-green', 'zn-gray', 'zn-red', 'zn-yellow', 'zn-teal', 'zn-dark' or 'zn-light' for standard colors or any CSS class name for a custom look.

text (String)

The text for the badge.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.content.badgedText is described below:

HTML string that can be added to the page or form using the $zn.dom.setHtml function.

Function: $zn.content.statusAnimation

Description

Generates HTML content for spinning or a pulsing status indicator. Use this when you want to indicate to the user that some processing is going on.

Parameters

This function needs the following 3 parameters:

type (String)

Use 'zn-status-spin' for a spinning indicator or 'zn-status-pulse' for the pulsing one.

color (String)

Specify 'zn-blue', 'zn-green', 'zn-gray', 'zn-red', 'zn-yellow', 'zn-teal', 'zn-dark' or 'zn-light' for standard colors or any CSS class name for a custom look.

size (String)

zn-size-small for a small size indicator or empty string for a regular one.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.content.statusAnimation is described below:

HTML string that can be added to the page or form using the $zn.dom.setHtml function.

Function: $zn.content.alert

Description

Generates HTML content for the Alert element, which is based on the Bootstrap 4 Alert component.

Parameters

This function needs the following 3 parameters:

dismissible (Boolean)

Set to true, if you want the Alert to be dismissible by the user, false otherwise.

color (String)

Specify 'zn-blue', 'zn-green', 'zn-gray', 'zn-red', 'zn-yellow', 'zn-teal', 'zn-dark' or 'zn-light' for standard colors or any CSS class name for a custom look.

text (String)

The text for the alert.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.content.alert is described below:

HTML string that can be added to the page or form using the $zn.dom.setHtml function.

Function: $zn.system.queryParameterValue

Description

Returns the value of the specified URL query parameter.

Parameters

This function needs the following 1 parameters:

name (String)

The name of the query parameter to get the value of.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.system.queryParameterValue is described below:

The value of the query parameter or an empty string

Function: $zn.system.navigateToUrl

Description

Navigates the page to the provided URL.

Parameters

This function needs the following 1 parameters:

url (String)

The URL to navigate to.

Return Information

This function does not return any value

Function: $zn.system.createTimer

Description

Creates a timer for the specified interval in milliseconds. After the interval is elapsed, then provided callback function will be called. Note that the timer is a one-shot and needs to be explicitly rearmed using the $zn.system.reArmTimer function.

Parameters

This function needs the following 3 parameters:

interval (Number)

The interval in milliseconds.

cbFn (Function)

The function to invoke, after the timer elapses. The function will be passed two parameters: - Reference to an object representing the timer which can be used to all th $zn.system.reArmTimer function. - The context object provided in the cbContext parameter

cbContext (Object)

A context object to be passed to the callback function. Can be null.

Return Information

This function does not return any value

Function: $zn.system.reArmTimer

Description

Rearms the timer created with $zn.system.createTimer with the same interval and callback function.

Parameters

This function needs the following 1 parameters:

timerObj (Object)

The timer to rearm.

Return Information

This function does not return any value

Function: $zn.system.log

Description

Logs the provided message to the console along with timestamp and optional meta information specified in the categry and level parameters.

Parameters

This function needs the following 3 parameters:

message (String)

The message to log.

category (String)

A category e.g. "ERROR" or "INFO" or "WARNING". Can be any text including empty string.

level (Number)

A number that specifies the level or severity of the log.

Return Information

This function does not return any value

Function: $zn.system.execCloudFlowWebHook

Description

Communicate with a defined Zingy Cloud Flow web-hook endpoint in your app. Please note that currently this function only supports HTTP POST type web-hooks and does not support HTTP GET webhooks.

Parameters

This function needs the following 2 parameters:

webHookName (String)

The name of the webhook endpoint. To create a Webhook endpoint refer to: https://docs.zingy.ai/app-editor/cloud-flow#web-hook

data (Object)

The object representing the data to be sent in the request. If the web-hook does not need any data, you can set this to null.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.system.execCloudFlowWebHook is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an object representing the data returned by the web-hook, null otherwise. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.system.connectionCommand

Description

Invoke a supported command/operation on a defined connection of your app.

Parameters

This function needs the following 4 parameters:

serviceName (String)

The name of the connection's service. Please see the Zingy connections documentation for all supported services and their names e.g. "apicall", "sendgrid", "twilio" and others.

connectionName (String)

The name of the connection for this service defined in your app. To add a new connection, refer to: https://docs.zingy.ai/app-editor/connections#adding-a-connection

command (String)

The service specific command to invoke.

commandParams (Object)

An object containing properties matching parameters required by the command. Please see the Zingy connections documentation for details about the parameters required by this service's command.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.system.connectionCommand is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an object representing the data object representing command's result/return value or null otherwise.Please see the Zingy connections documentation for details about the information returned by the service's command. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.system.waitForAuthInfo

Description

Use this function to wait for authentication information to be retrieved from your Zingy's app backend. Once completed successfully, the functions $zn.system.getCurrentUser and $zn.system.queryGroupMembership can be used.

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.system.waitForAuthInfo is described below:

A Promise that resolves to a Boolean value: true if successful or false otherwise

Function: $zn.system.getCurrentUser

Description

Returns the current authenticated user's username. This function returns valid values only after the authentication information is retrieved successfully from your Zingy's app backend. See the $zn.system.waitForAuthInfo function.

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.system.getCurrentUser is described below:

The username for the currently authenticated user or an empty string.

Function: $zn.system.queryGroupMembership

Description

Use this function to check if the current logged in user belongs to the specified group with the provided role level.

Parameters

This function needs the following 2 parameters:

groupId (Number)

Integer representing the Zingy app group identifier, which can be: - 0: Public User Group (no password) - 1: All Users Group - 2-11: App custom Groups - 12: Admin

roleLevel (Number)

Integer representing the Zingy app role level, which can be: - 0: Staff Level 1 - 1: Staff Level 2 - 2: Supervisor - 3: Manager - 4: Dept Lead

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.system.queryGroupMembership is described below:

true if the user has role level greater than or equal to the specified one for the group, false otherwise

Function: $zn.system.getFlowShareData

Description

Use this function to retrieve any data (objects or values) shared between a page or form, especially when the form is being shown as a popup modal. This allows you to access context-sensitive data passed from the parent flow, such as pre-filled fields or configuration settings.

Parameters

This function needs the following 1 parameters:

name (String)

The property name of the shared data (object or value)

Return Information

Return Value Type

This function returns a value of type: Any

Return Value Description

The return value of function $zn.system.getFlowShareData is described below:

Returns the shared data (object or value) associated with the provided name, or null if the shared data does not exist.

Function: $zn.system.isTestMode

Description

This function checks if the current execution context of your app is running in the Zingy Page Editor's preview functionality. It is useful for determining whether certain logic or features should be run only during development and testing, and not in the live production environment. This can help to isolate testing behavior from production use cases.

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.system.isTestMode is described below:

Returns true if the logic is being executed in the Zingy Page Editor's preview mode. Returns false if it is being run in a published or production environment.

Function: $zn.ui.showFormModal

Description

Presents a Form as a modal dialog/popup, with options for editing existing records or data or adding a new one.

Parameters

This function needs the following 8 parameters:

formSlug (String)

The identifier of the Form or it's URL slug (if different).

editData (Object)

If a valid object is provided, the Form will be initialized for editing the existing record. Note that this should not be used as means to pre-populate the form's input fields. If that is required, then it needs to be done using the sharedData parameter, and the form would need logic to use this to pre-populate the input.

title (String)

A title for the modal dialog/pop-up e.g. Add New Item or Edit Customer, etc.

sharedData (Object)

Use this to share information from the current page with the form. This information is available to the Form's Page Flow logic via the $zn.system.getFlowShareData function. Can be set to null if no shared information is needed.

mdlOptions (Object)

Use this to customize the look and feel of the modal dialog/popup. Can be null. See https://docs.zingy.ai/app-editor/page-flow/references/popup-customization for the supported customization properties.

cbFnSaveSuccess (Function)

Callback function that is invoked when the Form is saved successfully prior to the form being closed. Hence this function will be called before the callback to the cbFnCloseSuccess parameter. Set this to null if you do not want to provide a callback. NOTE: One can choose to close the modal during this callback by using the $zn.ui.closeModal function.

cbFnCloseSuccess (Function)

Callback function that is invoked when the Form is closed after the data was saved or submitted successfully. Hence this function will be called before the callback to the cbFnSaveSuccess parameter. Set this to null if you do not want to provide a callback. The callback function is passed an object similar to the one described for the cbFnSaveSuccess callback function.

cbFnCloseFail (Function)

Optional. Callback function that is invoked when the Form is closed after the data was not saved or submitted successfully. Set this to null if you do not want to provide a callback. The callback function is passed an object similar to the one described for the cbFnSaveSuccess callback function, except that the passed object will only contain a property named err containing the error information.

Return Information

This function does not return any value

Function: $zn.ui.showInfoModal

Description

Presents a modal dialog/popup displaying an informative message with a button for the user to close it.

Parameters

This function needs the following 3 parameters:

title (String)

A title for the modal dialog/pop-up e.g. There was an error submitting your request.

message (String)

The message to display.

mdlOptions (Object)

Use this to customize the look and feel of the modal dialog/popup. Can be null. See https://docs.zingy.ai/app-editor/page-flow/references/popup-customization for the supported customization properties. e.g. you can customize the label of the button using the okBtnText property.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.ui.showInfoModal is described below:

This function returns a Promise that resolves without any relevant return value after the modal is closed.

Function: $zn.ui.showConfirmModal

Description

Presents a modal dialog/popup displaying an message asking the user for permission to proceed by pressing the OK button or press the Cancel button to not proceed with the operation. It will return a Promise that resolves to a true value if the user pressed the OK button and false otherwise.

Parameters

This function needs the following 3 parameters:

title (String)

A title for the modal pop-up e.g. Confirmation needed.

message (String)

The message to display. HTML strings are supported. e.g. Ths will delete the record. Are you sure ?

mdlOptions (Object)

Use this to customize the look and feel of the modal popup. Can be null. See https://docs.zingy.ai/app-editor/page-flow/references/popup-customization for the supported customization properties. e.g. you can customize the label of the OK button using the okBtnText property and the cancel button using the cancelBtnText.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.ui.showConfirmModal is described below:

This function returns a Promise that resolves to true if the user selected the OK button or false if the user selected the Cancel button.

Function: $zn.ui.closeModal

Description

Use this function to close a modal automatically from inside the cbFnSaveSuccess callback of the $zn.ui.showFormModal function.

Parameters

This function does not need any parameters

Return Information

This function does not return any value

Function: $zn.ui.controlCollapsibleArea

Description

Based on the opType parameter, Expands, Collapses or Toggles the given Collapsible Area element.

Parameters

This function needs the following 2 parameters:

elemSel (Object)

Element selector object obtained using $zn.dom.elementIdSel or $zn.dom.dataDesignElementSel functions.

opType (String)

Use the following values to control the behavior: - 'zn-expand': Show the Collapsible Area element in its expanded state - 'zn-collapse': Show the Collapsible Area element in its collapsed state - 'zn-toggle': Toggle the state of Collapsible Area element

Return Information

This function does not return any value

Function: $zn.ui.showMenu

Description

Displays a context menu with specified options at the specified screen location. If the menu is being shown in the context of an event handler using the $zn.dom.setEventListener function, the xpos and ypos properties of the event information object can be used for the screen location.

Parameters

This function needs the following 4 parameters:

menuOptions (Array)

Array of Strings of options to be displayed in the context menu.

x (Number)

The position relative to the left edge of the document.

y (Number)

The position relative to the top edge of the document.

cbFn (Function)

The callback function that will be called when the user makes a selection from the menu. The function is passed the following parameters: menuText: The exact string from the menuOptions array that was passed. menuIndex: The 0 based index of the selection based on the menuOptions array that was passed.

Return Information

This function does not return any value

Function: $zn.ui.embedResize

Description

This function is used when an app's page is embedded in an iframe on another web page. If the web page includes the https://<>/runner/embed.js file automatically generated for your app, this function allows the parent page to resize the iframe dynamically to fit the content of the embedded page properly, ensuring that scrollbars do not appear unnecessarily.

Parameters

This function does not need any parameters

Return Information

This function does not return any value

Function: $zn.db.uniqueDsName

Description

Generates a unique dataset name for use with database operations.

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.db.uniqueDsName is described below:

Returns a string containing a unique dataset name.

Function: $zn.db.lookup

Description

Lookup a database table record using the provided matching criteria for the table. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 3 parameters:

tableName (String)

The name of the database table to be read.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

matchCriteria (Array)

Contains elements corresponding to the unique or primary key fields that allow looking up a record from the table. The array elements are arranged in the order of the primary key fieldss in the table's definition. If the table does not have any unique fields, this function may not return desired results and we recommend using the $zn.db.lookupById function instead for such cases.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.lookup is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an object representing the first record that was read. The _id property represents the record's identifier. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.lookupById

Description

Initiates a database lookup operation using the provided record identifier. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 3 parameters:

tableName (String)

The name of the database table to be read.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

recordId (String)

The record identifier.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.lookupById is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an object representing the first record that was read. The _id property represents the record's identifier. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.read

Description

Initiates a simple database read operation without any match, sort or field selection criteria. Hence this will read the first page of records without criteria and use the default sorting order. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 3 parameters:

tableName (String)

The name of the database table to be read.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

perPage (Number)

The maximum records to be read in a page. Please note that server side default limits apply if the provided value exceeds supported limits or is invalid.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.read is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.readQuery

Description

Initiates a database read operation using an already defined query for the table. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 5 parameters:

tableName (String)

The name of the database table to be read.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

perPage (Number)

The maximum records to be read. Please note that server side default limits apply if the provided value exceeds supported limits or is invalid.

queryId (String)

The query identifier to use for the read operation.

queryInput (Array)

Array containing values for the criteria inputs used by the query. The order of the criteria inputs is based on the definition of the query.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.readQuery is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.readNext

Description

Initiates the read for the next page of records after an existing call to $zn.db.readPrev, $zn.db.readNext, $zn.db.read or $zn.db.readQuery completes successfuly for the same dataset and table. The query input parameters (in case of $zn.db.readQuery) and the perPage value is retained from the previous initiation. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 2 parameters:

tableName (String)

The name of the database table to be read.

dsName (String)

The dataset name. This should be the same as the name used in the previous successful calls to the $zn.db.readPrev, $zn.db.readNext, $zn.db.read $zn.db.readQuery functions

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.readNext is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.readPrev

Description

Initiates the read for the previous page of records after an existing call to $zn.db.readPrev, $zn.db.readNext, $zn.db.read or $zn.db.readQuery completes successfuly for the same dataset and table. The query input parameters (in case of $zn.db.readQuery) and the perPage value is retained from the previous initiation. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 2 parameters:

tableName (String)

The name of the database table to be read.

dsName (String)

The dataset name. This should be the same as the name used in the previous successful calls to the $zn.db.readPrev, $zn.db.readNext, $zn.db.read $zn.db.readQuery functions

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.readPrev is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.create

Description

Initiates the addition of a new record into the database table. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 3 parameters:

tableName (String)

The name of the database table.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

recordInfo (Object)

Object with properties corresponding to the database table's fields.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.create is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: If successfull, an object representing the newly inserted record with the _id property containg the record's identifier. - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.updateById

Description

Initiates a database update operation for a record with the given identifier and data. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 4 parameters:

tableName (String)

The name of the database table.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

recordId (String)

The record identifier.

recordInfo (Object)

Object with properties corresponding to the database table's fields that need to be updated.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.updateById is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: not set - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.deleteById

Description

Initiates a database delete operation for a record with the given identifier. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 3 parameters:

tableName (String)

The name of the database table.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

recordId (String)

The record identifier.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.deleteById is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: not set - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.getFileList

Description

Returns an array of objects containing file information for the given field value. Use this function for fields with type Text and sub-type of Files.

Parameters

This function needs the following 1 parameters:

fieldValue (String)

The value of a record's field (of sub-type Files). Please note this is the value of the field in a record and not the field's name.

Return Information

Return Value Type

This function returns a value of type: Array

Return Value Description

The return value of function $zn.db.getFileList is described below:

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 - fileName: The file name - type: The file's MIME type - size: The size of the file

Function: $zn.db.clearDataset

Description

Use this function to clear the records in a dataset and free up resources and the associated memory.

Parameters

This function needs the following 2 parameters:

tableName (String)

The name of the database table.

dsName (String)

The dataset name. This should be the same as the name used in the previous successful calls to the $zn.db.readPrev, $zn.db.readNext, $zn.db.read $zn.db.readQuery functions

Return Information

This function does not return any value

Function: $zn.db.showInputModal

Description

Use this function to display a generic form as a modal dialog/popup that accepts input from the user based on the table's field information schema. Unlike $zn.ui.showFormModal which is used to show custom designed form, this function generates the form dynamically but in a generic way.

Parameters

This function needs the following 4 parameters:

title (String)

The title for the modal. If null or blank, a default value gets used.

tableName (String)

The name of the database table.

editData (Object)

If a valid object is provided, the Form will be initialized in editing the existing record. Note that this should not be used as means to pre-populate the form's input fields as for saving the user's input a database update call is used instead of a database create when this parameter is null.

cbFnSuccess (Function)

The callback function that will be called when the operation completes successfully. The function is passed an object representing the data entered by the user.

Return Information

This function does not return any value

Function: $zn.db.deleteFiles

Description

Initiates the removal of the specified files attached to the given field of a record. Returns a Promise that allows you to wait for the completion of the operation.

Parameters

This function needs the following 5 parameters:

tableName (String)

The name of the database table.

dsName (String)

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $zn.db.uniqueDsName function.

fieldName (String)

The name of the field in the table.

recordId (String)

The record identifier.

filesInfo (Array or String)

This can be an array of strings or just a string that specifies the name of the file to be deleted.

Return Information

Return Value Type

This function returns a value of type: Promise

Return Value Description

The return value of function $zn.db.deleteFiles is described below:

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successfull or false otherwise. - data: not set - err: If successfull set to null, otherwise the information about the error (usually as a string).

Function: $zn.db.getRecordId

Description

This is a utility function that returns the record identifier for a valid record information object. Essentially it returns the _id property of the provided record information object or an empty string.

Parameters

This function needs the following 1 parameters:

recordInfo (Object)

A valid record information object.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.db.getRecordId is described below:

String representing the record identifier or an empty string if recordInfo is not a valid record information object.

Function: $zn.form.setupHooks

Description

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

Parameters

This function needs the following 6 parameters:

cbFnInit (Function)

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 $zn.form.lock function to lock the form and unlock it after the task is complete.

cbFnPreValidate (Function)

This callback function is invoked after the form submission process is triggered, but before Zingy's automatic field input validation process. Use this function to implement custom or complex validation logic prior to the automatic validation process. Use the $zn.form.getFieldValue and $zn.form.setFieldValue functions to get/set the value of the fields. Use the $zn.form.setStatus function with a false value, to indicate any errors. The $zn.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 $zn.form.setStatus with a true value. Please note that you cannot execute a background task and wait for it's completion here.

cbFnPostValidate (Function)

This callback function is invoked after Zingy's automatic field input validation process but prior to data submission. Use the $zn.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 $zn.form.getFieldValue and $zn.form.setFieldValue functions is not recommended since the system has already progressed beyond the reading of field input values. Use the $zn.form.setStatus function with a false value, to indicate any errors. The $zn.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 $zn.form.setStatus with a true value. Please note that you cannot execute a background task and wait for it's completion here.

cbFnSubmit (Function)

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 $zn.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 Zingy's database (using the functions provided by $zn.db). Since submission of data is usually an asynchronous task, you need to call the $zn.form.customSubmitComplete function after your custom submission logic finishes. Prior to calling $zn.form.customSubmitComplete, you need to call $zn.form.setStatus to indicate the success or failure status. The $zn.form.setStatusMessage function can be used to indicate the outcome information. If not, he Zingy form's default success and error messages will be shown.

cbFnSuccess (Function)

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

cbFnError (Function)

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 $zn.form.setStatusMessage function can be used to override the form's default error message.

Return Information

This function does not return any value

Function: $zn.form.lock

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 Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

value (Boolean)

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

Return Information

This function does not return any value

Function: $zn.form.save

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 Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

data (Object)

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.

Return Information

This function does not return any value

Function: $zn.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 Zingy's Form type Pages.

Parameters

This function does not need any parameters

Return Information

This function does not return any value

Function: $zn.form.setStatus

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 $zn.form.setupHooks functions. NOTE: This function only works for Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

value (Boolean)

The true or false value to set.

Return Information

This function does not return any value

Function: $zn.form.setStatusMessage

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 $zn.form.setupHooks function. NOTE: This function only works for Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

message (String)

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

Return Information

This function does not return any value

Function: $zn.form.customSubmitComplete

Description

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

Parameters

This function does not need any parameters

Return Information

This function does not return any value

Function: $zn.form.setFieldValue

Description

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

Parameters

This function needs the following 2 parameters:

name (String)

The name of the database table's field.

value (String)

The value of the field.

Return Information

This function does not return any value

Function: $zn.form.getFieldValue

Description

Gets the value of the specified field. Consider this function as an alternative to $zn.dom.getVal where instead of an element selector, you provide the name of the database table field and the Zingy system automatically sets the value of the associated element. NOTE: This function only works for Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

name (String)

The name of the database table's field.

Return Information

Return Value Type

This function returns a value of type: String

Return Value Description

The return value of function $zn.form.getFieldValue is described below:

The current value of the field.

Function: $zn.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 $zn.form.setupHooks function. In the context of the cbFnPostValidate callback of the $zn.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 Zingy's Form type Pages.

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: Object

Return Value Description

The return value of function $zn.form.getFormData is described below:

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

Function: $zn.form.getUploadedFiles

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 Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

fieldName (String)

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

Return Information

Return Value Type

This function returns a value of type: Array

Return Value Description

The return value of function $zn.form.getUploadedFiles is described below:

  • 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 - fileName: The file name - type: The file's MIME type - size: The size of the file

Function: $zn.form.getUnUploadedFiles

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 Zingy's Form type Pages.

Parameters

This function needs the following 1 parameters:

fieldName (String)

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.

Return Information

Return Value Type

This function returns a value of type: Array

Return Value Description

The return value of function $zn.form.getUnUploadedFiles is described below:

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

Function: $zn.form.disableFileDelete

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 Zingy's Form type Pages.

Parameters

This function needs the following 2 parameters:

fieldName (String)

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

value (Boolean)

true for disabling and false for enabling

Return Information

This function does not return any value

Function: $zn.form.disableFileUpload

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 Zingy's Form type Pages.

Parameters

This function needs the following 2 parameters:

fieldName (String)

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

value (Boolean)

true for disabling and false for enabling

Return Information

This function does not return any value

Function: $zn.form.removeUnploadedFile

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 Zingy's Form type Pages.

Parameters

This function needs the following 3 parameters:

fieldName (String)

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

index (Number)

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

fileName (String)

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

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.form.removeUnploadedFile is described below:

true if the operation was successful or false otherwise.

Function: $zn.form.markUploadedFileForDelete

Description

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

Parameters

This function needs the following 3 parameters:

fieldName (String)

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

fileName (String)

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

value (Boolean)

true to mark for removal and false for clearing the mark

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.form.markUploadedFileForDelete is described below:

true if the operation was successful or false otherwise.

Function: $zn.form.isEditMode

Description

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

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: Boolean

Return Value Description

The return value of function $zn.form.isEditMode is described below:

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

Function: $zn.form.getOriginalEditData

Description

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

Parameters

This function does not need any parameters

Return Information

Return Value Type

This function returns a value of type: Object

Return Value Description

The return value of function $zn.form.getOriginalEditData is described below:

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

PreviousCoding in Page FlowNextReferences

Last updated