Introduction

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

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 HomePage Item).

Form Script Syntax

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

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 a HomePage Item). 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 HomePage Item), 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.

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.

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.

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
• hidden – the field will be permanently hidden – useful in some more complex forms, usually if you need to include a pre-calculated value ready to use in other calculations
vValue [hidden default `daysbetween(DateField,today())`]
• 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:

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
• collapsed – the section will initially be displayed collapsed i.e. show the section title only. The user can click on the title to expand the section (as with all form sections, which can be collapsed/expanded at will). This is useful if you have a section of the form containing advanced or optional fields, and don’t wish to take up too much screen real-estate (and user attention) unnecessarily.
  SECTION My First Section …fields… SECTION My Section Heading [show `vQuantity > 0`] …fields… SECTION Advanced Settings [collapsed] …fields…

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

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.

Evaluating the Form Results

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