On this page, we build on the previous video and focus on some examples of using expressions to apply values to fields.
Once you have opened the Expression Builder, you will see three tabs: Template, Assignment, and Function.
- Template – Used for building concatenations without the complexity of using operators. e.g. Full name is [[FirstName]] [[LastName]] would evaluate to Full name is Brett Lonsdale
- Assignment: Used for building calculations or expressions with operators that return a value. e.g. [[SalesTax]]+[[SubTotal]]
- Function: Used for building expressions using JavaScript. e.g. var date = new Date();return date;
Placeholders
Placeholders can be double-clicked or dragged into the expression window. The placeholders include:
- Fields within your form
- Contextual Values
- Sublists
Fields
Fields can be double-clicked in order to use the field as part of your expression. The fields can also be expanded to show ‘OriginalValue, IsChanged, or IsInvalid’. OriginalValue stores the initial, unchanged value of a data field for comparison purposes. IsChanged indicates whether the current value has been modified from the original value. IsInvalid indicates whether the current value does not meet validation criteria. The latter two are helpful when building validation rules against fields.
The outcome of your expression can be tested against a list item using the Test button at the bottom of the Expression pane.
Context
The Context placeholders enable you to retrieve properties from the context of your form. Your form is within a list, which is in a site, which is in a site collection. It is being accessed by the current user on the current page. Properties can be retrieved from each of these contextual properties:
- Form – properties about the form you are on, such as ItemID and ListID. IsDisplayForm, IsEditForm, IsNewForm, and IsSubListForm are helpful when applying conditions such as formatting or validation.
- Page – The current page properties such as CultureName, GetQueryString, Language, UICultureName and URL.
- Site – The Site Collection that you are in. GetFirstValueForQuery and GetValuesForQuery enable you to retrieve values using CAML Queries. See How to use Lightning Forms context query functions (lightningtools.com) for more details about these Context Query Functions. ServerRelativeURL and Url can bring back the URL of the current site collection.
- User – Return information about the current user such as Title, Login Name, Location, and Email. Two functions can be used to test if a user is a member of a SharePoint group or Azure Active Directory Group. These include IsMemberofGroup and IsMeberofAADGroup.
-
Web – Returns information about the current Site. e.g. Title, URL, Language and GetValues Queries.
Sublists
Using the Expression Builder, you can access sublists to get at the columns within the sublist and use a summary function against the related items, e.g., Sum, Min, Max, Count. The below example returns a sub total from the Line Total column in the Sublist to the Sub Total column on the main form.
Field Controls
Fields in Lightning Forms contain controls for configuring complex business logic. Flexibly configurable, expression-based behaviours provide an easy way to make a field or form section dynamically show or hide or become enabled or disabled depending on other inputs. Values can also be set and even recalculated while the user is entering data in the form.
Visible: Visible expression allows to change the visibility of any selectable controls at run-time based on some condition.
For example, you can hide or show form controls based on conditions. As an example, a field can be shown only when the field ‘Status’ is set to ‘Active’: =[[Status]]== ‘Active’
Enabled: Enabled expression enables or disables any selectable controls at run-time based on some condition.
For example, you can disable controls that are not allowed to be edited depending on other field values or disable a button to prevent the user from clicking it depending on his group memberships.
Initial: Initial value expression allows to assign a default value to a field. This can be a constant or a calculated expression.
For example, you can set current date as a default value: ‘= new Date()’. Other date expressions include:
| = new Date(2023, 5, 3) | Set the date to 3rd June 2023. Note: The month (2nd) parameter is 0-based, so January is 0 and December is 11. |
| = new Date().addDays(10) | Set the date to current date (and time) plus 10 days. Use addDays(-n) to subtract n days. |
| = new Date().addHours(4) | Set the date to 2 hours in future. |
| = new Date().addYears(-1) | Set the date a year ago from today. |
Calculated: Calculated expression provides a flexible way to dynamically recalculate the value while the user is entering data in the form. Whenever the value of a form field referenced in the calculated expression is changed, the expression is recalculated and the dependent field’s value set with the result.
For example, you can use it to perform a mathematical calculation – multiplying the values contained in two fields in order to produce a Total Amount in the current field: ‘=[[Price]]*[[Count]]’
You can also calculate date time fields.
| =[[SomeOtherDate]] | Get the date time field of another date time field. |
| =[[SomeOtherDate]].addDays(10) | Get the date time field of the SomeOtherDate column plus 10 days. |
| { if ([[ContractType]]==“Monthly”) return [[StartDate]].addMonths(1); else if ([[ContractType]]==“Quarterly”) return [[StartDate]].addMonths(3); else if ([[ContractType]]==“Semi-Annually”) return [[StartDate]].addMonths(6); else if ([[ContractType]]==“Annually”) return [[StartDate]].addYears(1); else return null; } |
Get a date depending on value of field ContractType and StartDate. When ContractType is “Monthly” the date is calculated as StartDate plus 1 month, when ContractType is “Quarterly” the date is calculated as StartDate plus 3 months, etc. If ContractType does not match any of the checked values no date is returned.As an example this function expression could be used as a calculated expression to set the RenewalDate field of a contract item. |
Validation and Validation Text: Validation expressions provide an easy way to define a validation rule. Even complex rules can be defined using expressions to specify required form input, and so, if the validation expression evaluates to false, the form cannot be saved.
For example, you might want to create a rule where the form can only be saved if a column called Name has a value of ‘James’. If a user enters something else, for instance, ‘John’ and tries to save the form, the form will display the validation text reminding them to update the Name column to ‘James’.
We will look at a video exploring validation within Lightning Forms and highlight other scenarios where validation can be applied. We use simple Required validation to ensure a field is completed, a simple expression validation with a specific validation message, and a regular expression validation using Javascript.
Some practical examples of regular expressions can be found below:
Valid Email Address Regular Expression
if([[Email]]!==""){ var mailformat = /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/; return mailformat.test([[Email]]); } else return true;IP Address Regular Expression
if([[IPAddress]]!==""){ var ipformat = /\b(?:(?:2(?:[0-4][0-9]|5[0-5])|[0-1]?[0-9]?[0-9])\.){3}(?:(?:2([0-4][0-9]|5[0-5])|[0-1]?[0-9]?[0-9]))\b/ig; return ipformat.test([[IPAddress]]); } else return true;MasterCard Regular Expression
if([[MasterCard]]!==""){ var mcformat = /^(?:5[1-5][0-9]{2}|222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}$/g; return mcformat.test([[MasterCard]]);
} else return true;Phone Number US Format Regular Expression
if([[WorkPhone]]!==""){ var usphoneformat = /(?:\d{1}\s)?\(?(\d{3})\)?-?\s?(\d{3})-?\s?(\d{4})/g; return usphoneformat.test([[WorkPhone]]);
} else return true;