Forms

Capabilities

Capability	Support	Comment
Using form as a dashboard widget		See Form
Using form to update a collection		A form can be bound to a collection to insert/update an element of a collection. See Form
Using form to update values		See Using form to update a value value (write)
Using form to update values and collection in same time		This can be done with standard scripting, beware to the order of action and reaction to avoid conflicts
Creating custom form		See Form definition
Create conditional forms
Using (read) value in forms		A form can be bind to a value Using form linked to a value (read).
Trigger action in forms submission		Trigger an action on submission All data content will be posted to an action running a script.
Trigger both action and value in forms submission		Update destination Acts as Value and Action mixed. Values are updated and data are sent to a script through an action
Trigger request in forms submission		See Trigger an action on submission for details.
Modify elements based on the current user’s permissions.		See Rights for details.
Immediate transmission of modification		See Submission mode for details.
Manage conflicts
Retrieve data from an external api		See API service and Api service picker for details.

Concept

A form is a element of the configuration who can be used as a dashboard widget or as a element of a collection.

List of configuration files

Filename	Short description	Format	Link to documentation
dashboard.view#FormWidget	Defines the FormWidget widget global settings	json	Link

List of examples

Short description	Link to documentation
Display the elements of a collection and use a form to edit	List and update a collection
Update value to change widgets colors	Dynamic colors
Setup your configuration to gain access to collections rights	Setup your configuration to gain access to collections rights
Add rights to a form	Add rights to a form

Using form linked to a value (read)

Concept

A form can use Osp value to trigger (todo ref) conditional view or to auto-fill form.

Form widgets allow bindings (read and write) with OnSphere values. Bindings other values can be achieved by passing arguments to the form.

Bindings offers a way to link a Value to an element of the UI schema, giving a way to show and modify the content of a Value. Special case allows specifying read and write (both optional) to separate value linked for reading and for writing.

Limitations

When a value is updated:

• The value changes but the entry is already sent (like in collection) -> the value is not updated in collection

• When updating an entry (edit button), the value is re-updated with the current value.

• The value is updated automatically on the form (no refresh necessary).

Using form to update a value value (write)

Concept

A form can submit to values

Limitations

• If the value is updated elsewhere and I write a new value, the latest value is written.

• If the value is written from a form and the form is edited and saved, the values will be re-written.

• The value changes but the entry is already sent (like in collection) -> the value is not updated in collection.

• When updating an entry (edit button), the value is re-updated with the current value.

• The value is updated automatically on the form (no refresh necessary).

Usage

Each key declared in the bindings object must be present in the schema, making them accessible as a scope for any UI elements.

{
    "bindings": {
        "all": {
            "variables": {
                "accessed": {
                    "by-your-form": "root.valid.onsphere.path"
                },
                "read-or-write": {
                    "read": "root.some.path.to.read",
                    "write": "root.some.path.to.write"
                }
            }
        }
    },
    "schema": "<schema osp path>",
    "ui": {
        "type": "Group",
        "label": "Automation",
        "elements": [
            {
                "type": "Control",
                "scope": "#/properties/all/properties/variables/properties/accessed/properties/by-your-form",
                "label": "Some boolean to automate"
            },
            {
                "type": "Control",
                "scope": "#/properties/all/properties/variables/properties/read-or-write",
                "label": "Some integer to automate"
            }
        ]
    }
}

Update destination

Form submission can have one of the four following destination:

• Value: The form data is published to the values that are linked to the different UI elements through form bindings.

• Action: All data content will be posted to an action running a script. You can access the content of the form using the parameters[0] attribute (parameters is an array where the first index contains the form data).

• Mixed: Acts as Value and Action mixed. Values are updated and data are sent to a script through an action

• Request: The value of the form is sent through the collections websocket to attempt the creation/update of a collection element.

Warning

When using Mixed, the order for updating Value and executing Action is undefined ! Values may be updated after action execution. If you use an Action to trigger a script, you may have old values if you attempt to directly read a value content. You can get the up to date content of the values by using trigger.parameters[0].

Form definition

To use the Form widget, you must first create a form.web file with the following content:

• Name: The form name

• Description: Description of the form

• Bindings: Object matching bindings with leaves being reference to OnSphere root value path. Special case allows specifying read and write (both optional) to separate value reading from writing

• Rights: Define a list of rights that can be used in this form UI schema to disable/enable/hide part of the UI, based on user form rights.

• Schema: Id to a valid JSON schema describing the data form schema.ospp

• UI schema: A valid JSON UI schema describing the UI which interacts with the data

• Initial value: Set initial value for the form

• Submission: How the form is submitted

Example of a form with deferred value submission below:

{
    "moduleId": [
        "modules.web.web-1" // This depends on your web module(s)
    ],
    "name": "<Form name>",
    "description": "<Form description>",
    "rights": [],
    "bindings": {
        "all": {
            "variables": {
                "accessed": {
                    "by-your-form": "root.valid.onsphere.path"
                },
                "read-or-write": {
                    "read": "root.some.path.to.read",
                    "write": "root.some.path.to.write"
                }
            }
        }
    },
    "schema": "<schema osp path>",
    "ui": {
        "type": "Group",
        "label": "Automation",
        "elements": [
            {
                "type": "Control",
                "scope": "#/properties/all/properties/variables/properties/accessed/properties/by-your-form",
                "label": "Some boolean to automate"
            },
            {
                "type": "Control",
                "scope": "#/properties/all/properties/variables/properties/read-or-write",
                "label": "Some integer to automate"
            }
        ]
    },
    "initialValue": {
        "all": {
            "variables": {
                "accessed": {
                    "by-your-form": false
                }
            }
        }
    },
    "submit": {
        "destination": "Value",
        "type": "Deferred"
    }
}

Rights

Rights allow to modify the structure of a form depending on the user trying to access it. For each element of the UI schema, you can define an objects rights to define the level of access for a specific right. In addition, each of those rights must be defined in the rights property. Each right can be set as either :

• none: hide the element by removing it from the form

• read: allow the user to see this element and the data linked to it but doesn’t let him modify them

• write: full access to the element and the data

"rights": ["user", "admin"],
"ui": {
        "type": "Group",
        "label": "Automation",
        "elements": [
            {
                "type": "Control",
                "scope": "#/properties/all/properties/variables/properties/accessed/properties/by-your-form",
                "label": "Some boolean to automate",
                "rights": {
                  "user": "read",
                  "admin": "write"
                }
            },
            {
                "type": "Control",
                "scope": "#/properties/all/properties/variables/properties/read-or-write",
                "label": "Some integer to automate"
            }
        ]
    },

When a user request a form, we fetch the user form rights and compare them to the declared rights for each UI element. If the UI element doesn’t have any declared rights, it will be fully visible and editable for any user. Otherwise, if the element has any right defined, we compare them to the user form rights and determine the outcome:

• The user doesn’t have any of the declared rights for this UI element, then the UI element is hidden (use right level none as default).

• The user have one of the declared rights for this UI element, then we change the UI element according to this right level.

• The user have multiple of the declared rights for this UI element, then we change the UI element according to the higher right level he has.

Submission mode

The update of the values linked to a form can be either immediate or on action named deferred

• Immediate: Upon any modification in the form, the data are saved and emitted to the given destination

• Deferred: The data are saved and emitted only when a user clicks on a submit widget on which the form is subscribed to. One is created by default and is present in the form toolbar.

Trigger an action on submission

Example of form properties:

{
  "moduleId": [
      "modules.web.web-1"
  ],
  "name": "Name of form",
  "description": "",
  "schema": "root.schema",
  "submit": {
      "action": "<action osp path>",
      "script": "<script osp path>",
      "destination": "Action",
      "type": "Deferred"
  }
}

And then you can access any property declared in the schema with the following code in a script:

let triggerContent = trigger.parameters[0];
log.info("Value: " + triggerContent.led_luminosity) // Where **led_luminosity** is a property of the schema