Item form expressions

Make item forms dynamic and reactive to user input

An expression is a sequence of values and functions that outputs a final value.

Each control on an item form has several configurable properties (e.g. Read-only, Required). By setting a property to target an expression (instead of a static value), that property becomes context-sensitive, and will change depending on the expression's output. As expressions can read and react to the properties of all controls on the form, this makes some cool stuff possible! 😎

For example...

By targeting an expression, you can:

• make an optional control required if another control is populated

• make a read-only control writeable if a Checkbox control is checked

• limit the accepted values of one Date control based on another, e.g. an End Date control that can only be set within 30 days of a Start Date control

• sort and filter items in a Link attribute's lookup list, based on another control's value, e.g. after choosing a Team, the Team Member control only shows corresponding users

• set the default value of a control based on others, e.g. if a Priority control is set to "High", the Target Date control defaults to 7 days after the Start Date control value

In this way, you can use expressions to regulate user input, filter the available controls on the form, and set dynamic values.

Note

Expressions are currently unsupported on Alloy Mobile and will go unprocessed if present.

Manage a form's expressions

When editing an item form, any expressions defined within the form are displayed on the left.

Select an expression to edit it, or select to create a new one.

Note

Developers can also include an expressions array in their JSON code when using the Alloy API to create/edit an item form.

The Item Form Expression Builder

This appears whenever you create or edit an item form expression.

1 Name

Select to edit the name of the expression. We recommend making it a clear description of what the expression does, so it can be easily picked from a list when someone configures a control property.

2 Node types

Nodes are the building blocks of your expression. Each type represents a function or a value. Values can be static, or dynamically linked to a control property on the item form, or dynamically linked to a global Alloy variable, e.g. the current user's name.

Select a node type in the top toolbar to add a node to the canvas.

• ​ Conditionals - logical functions that test inputs from other nodes and produce corresponding output.

• ​ Finals - the expression's output, which will be applied to any control property that targets it.

• ​ Globals - references to the dynamic value of a control property or a global Alloy variable.

• ​ Literals - static values that you input yourself.

• ​ Transforms - functions that modify an input value, producing a new value.

• ​ Dates - functions for creating or manipulating date values.

• ​ Date Times - functions for creating or manipulating date and time values.

To see the full list of node types, see Item form expression nodes.

3 Tools

Select a tool in the top toolbar:

• ​ Delete - delete the currently selected node or link.

• ​ Organise - automatically arrange nodes into formation based on how they're linked.

4 Added nodes

Nodes appear on the canvas as blue boxes, displaying their type and a helpful description of what they do. You can drag them around and use their bottom-right corner to resize them.

To set the value of a node, select its icon and then its Value field.

If it's a Global node, a list of global Alloy variables and compatible control properties will appear. Choose one to link to.

Global Alloy variables

Variable	Description	Global node type
User Alloy ID	The ID of the current user	Alloy ID Array
Item ID	The ID of the item being create/edited	Alloy ID Array
Parent item ID	The IDs of any parent items that link to the item being created/edited	Alloy ID Array
Create mode	Is the item form being used to create an item?	Boolean
Edit mode	Is the item form being used to edit an item?	Boolean
Date Now	The current date	Date
Date Time Now	The current date and time	Date Time
Username	The username of the current user	String
First name	The first name of the current user	String
Last name	The last name of the current user	String
Email	The email address of the current user	String
Customer name	The name of the current customer project	String
Item form name	The name of the current item form	String
Item form context	The context of the current item form	String
Design name	The design name of the item being created/edited	String
Design context	The design context of the item being created/edited	String
Item icon	The icon code of the item being created/edited	String
Item signature	The signature of the item being edited (changes with every edit)	String
Item collection	The Guc of the collection of the item being created/edited	IsTriggering
Item form code	The Guc of the current item form	IsTriggering
Design code	The Guc of the design of the item being created/edited	IsTriggering

If it's a Literal node, you can then provide a value. Depending on the node type, this may involve typing directly into the field, choosing a value from a picker, using the AQS Builder, or enabling/disabling the field to indicate true or false.

5 Links

Define your expression by linking the inputs and outputs of different nodes on the canvas.

Each node has one or more input circles on their left side. They're labelled to help you understand the type of input expected.

Each node has one output circle on their right side (except for final nodes).

To join two nodes together, select an output circle on the first node, and then select an input circle on the second node. When you select a circle, only compatible circles will remain undimmed, so you can only create valid links!

Note

All possible execution branches within the expression should end with a final node.

6 Save button

When you're finished, select Save to save your expression and return to the Item Form Builder. To leave without saving, select in the top-right corner.

Targeting an expression

When editing an item form, selecting a control will display its properties on the right.

To make a property target an expression, select its icon and then choose a saved expression from the list. The value of that property now depends on the output of the expression, which may change as the user interacts with the item form.

Examples

To learn more about building different types of expression, here are some step-by-step examples:

1. Example 1 - Simple boolean check

2. Example 2 - Cascading lookup list