Form Scripts

Introduction

Form Scripts are used to construct a form that is presented to the user e.g. as part of a Step or an App Step.

A Form is usually constructed in the context of a specific record, known as the owning record (e.g. where a Step is acting on an existing record), although may also be in the context only of a specific Record Type e.g. where a Form is used for adding a new record (e.g. in a Step that is set-up as the ‘add record’ step for that Record Type).

What does in the context of actually mean here? It means that all Calculations described below will be evaluated on that record, and any form fields specified by name only will refer to available fields of that record.

Elements of a Form

A Form can have:

  1. Instructions – any instruction text will be shown in a box at the top of the form. Instruction text is always evaluted as a Template Script so can include any field values and calculations from the owning record of the Form.
  2. Sections – subsequent fields and any comment blocks are included in separate html FieldSet boxes with their own headings. Sections can be expanded or hidden by clicking on the headings, and the display of a whole section can be governed by a Calculation
  3. Fields – each form field is specified on a separate line. It can either be the name of an existing Field of the owning record, or given its own unique name, in which case its value will be available as a variable of that name when used in the Action Script that operates on the form results (usually stored with the Form Script in a Step or App Step).

Form Script Syntax

In general, the syntax of a form script looks like this:

— START Instructions This is the help that goes at the top of the form. It carries on until we hit a section line — END Instructions SECTION My Section Heading 1 KnownFieldName vMyVariableDate [date default `today()`] My Title Override vMyCheckbox [logical] Click this to show the second section vProduct [product show `vMyCheckbox`] Product SECTION My Second Section Heading [show `vMyCheckbox`] START COMMENT This is the comment that is specific to this second section It carries on until the END COMMENT line. END COMMENT vPrice [currency calc `vProduct:Price`] Price vQuantity [number default `1`] Quantity vValue [currency calc `vPrice * vQuantity`] Value SET ActionText="Create Order Line"

The example above will create a form with an instructions box then two sections.

The first section has three fields visible initially; the fourth field (vProduct) will not be shown initially because its show calculation (`vMyCheckbox`) will evaluate false until that checkbox is ticked. Note that the first field, KnownFieldName, is an existing field name of the record to which the form relates (assuming that this form is on a Step, not an App Step). When using an existing field, it is not necessary to include the extra details of type, title etc., as PYXI already knows these and will use them to display the field.

The second section has three fields but starts hidden from view because of the same show calculation as just discussed. The second section has an additional comments box before the fields. The Action button will have the text Create Order Line.

Some of the behaviour of the form is governed by additional options, all of which will be explained in detail below. In summary, however, clicking checkbox will result in the Product selector being shown (on the assumption that Product has been set-up as a Record Type on this account), and the whole second section is also shown. Within the second section, both the price and the value are calculated fields. The price is populated when the Product is selected, taking the value in the Price field on the Product record.

Field Line Syntax

In general, each Field Line refers to an individual field / input control on the form. A Field Line refers to either an existing field of the record to which the form relates, or to a variable – a value which will be used in an Action Script associated with the form (e.g. on a Step or an App Step), but which is not itself one of the fields of the record.

When referring to an existing field, the syntax is simply to state the field name e.g.

KnownFieldNameOfOwningRecord

Alternatively, to specify a variable, it is also necessary to tell the form more information, including at minimum, the type of the field and a display title.

vMyFieldName [type parameters] My Display Text

type can be any of the standard Field Types (e.g. text, number, logical etc.), or can be a Record Type Name. If a Record Type Name is specified, then the field will be a link to that Record Type, and will display as a drop-down selector.

The type can also be option if you need to show radio-buttons – in this case, the text immediately after option is the value of the field if that option is selected. Note that radio-buttons are grouped simply by giving them the same field name. E.g.

vMyVariable [option firstvalue] My First Choice vMyVariable [option secondvalue] My Second Choice vMyVariable [option thirdvalue] My Third Choice

Please note that a variable made up of options radio-buttons will be considered required unless all options are also flagged optional

parameters can be zero or more of the following. Note that wherever a calculation parameter is offered, separate the command from the calculation with a space and wrap the calculation in back-ticks (`). All calculations are re-evaluated every time any field on the form is updated. Calculations can refer to any form field value as well as the Fields on the owning record.

  • optional – note that a field is considered required unless this is set
  • vMyVariable [text optional] My Variable
  • required optionally followed by a Calculation – this is used only for logical fields that do not default to required (which wouldn’t normally make sense for a checkbox!) – it can be used to force the user to tick a checkbox e.g. as part of recording acknowledgement of a message or confirming a particularly key process step.
  • vAcknowledge [logical required] Tick to acknowledge
  • default followed by a Calculation – the calculation will be evaluated and the result used to populate the initial value of the field
  • vMyDate [date default `today()`] Transaction Date
  • calc followed by a Calculation – the field will not be available for input (it will be disabled), but will be updated with the result of the calculation whenever any field is updated on the form
  • vValue [currency calc `vPrice * vQuantity`] Transaction Value
  • checked followed by a Calculation – for logical fields, the calculation determines whether this field is checked initially
  • vOption [logical checked `DateField>today()`] Suggested Option
  • show followed by a Calculation – the field will be shown or hidden depending on whether the calculation evaluates true or false
  • vValue [show `vQuantity > 0`] Value
  • multiline – signifies that a text field should be a multi-line input (an html textarea)
  • vComment [text multiline] Enter your comment

Naming Conventions – note that we have named variables in the examples above starting with lower-case ‘v’ to distinguish them from field names of the owning object. This is entirely optional – however you are recommended to follow this naming convention as best-practice.

Section Heading Syntax

Section syntax is as follows:

SECTION My Section Name [options]

Anything after the word SECTION and before the opening square bracket will be used as the displayed title of the section.

options (all of which are optional!) are as follows:

  • show followed by a Calculation – the section will be shown or hidden depending on whether the calculation evaluates true or false
  • SECTION My First Section …fields… SECTION My Section Heading [show `vQuantity > 0`] …fields…

Within a section, you can add comment boxes that provide additional help to the user. Syntax is:

START COMMENT Any text on lines between the START COMMENT and END COMMENT lines will be included in the box. It can include template strings such as {dateformat(MyDateField)} END COMMENT

General Script Syntax

The following variables can also be set to provide additional customisation, as follows:

  • Heading – optional template text used to generate the heading at the top of the page
  • Icon – optional icon name being the icon displayed in the heading
  • IconColour – optional colour of the Icon displayed in the heading
  • Instructions – optional template text for instructions that will be displayed at the top of the form
  • ActionText – optional text override for the Action (Save) button
  • CancelText – optional text override for the Cancel button

Note that all the general rules of Script apply. You can use IF/ELSE/END structures, and add comment lines wherever you choose. Indentation and blank lines are ignored, but use wisely to make your scripts more readable. E.g.

# Form script to demonstrate syntax # # Written by John Smith 15/9/19 — START Instructions My form instructions that include the date {dateformat(MyDateField)} on the owning record. — END Instructions IF MyDateField < today() # We only want this section to show if MyDateField is before today SECTION My First Section vMyOption [logical] My option field ELSE # Otherwise we want to show this section SECTION MY Alternative First Section vMyOption [logical required] Check this to acknowledge ENDIF SECTION Always Shown Section vAnotherField [text] Enter Text Here

Evaluating the Form Results

Your Form Results are evaluated using an Action Script, normally included in either your Step or App Step configuration along with the Form Script.

Get Started