Command Types
Description
An explanation of each of the different types of commands and their properties.
The command types and their properties are:
Data Field
The Data Field command type (also called the Field command type) specifies a form field to be displayed in the form.
A Field can be any of a number of different types of fields, differentiated by their Field Type. There are many different field types to facilitate different types of input and data.
The most basic field type is Text. This displays the field value (if any) directly as it is in the data, along with a title above the value. Tapping on the field in the Form Filler will bring up the device keyboard in a separate screen.
The types of Data Fields are: Text, Number, Integer, Currency, Phone number style, Signed decimal, Date, Date/Time, Time Now, Stopwatch, Photo, Audio, Signature, Scanner, Location, Button List, and List.
The Number, Integer, Currency, Phone number style, and Signed decimal types behave like the Text type, but have appropriate keypads displayed when entering values. The Integer type also adds buttons on the form itself for increasing and decreasing the value.
The Date and Date/Time styles have spinners for entering values, as well as a Today or Now button.
The Time Now and Stopwatch styles have buttons to access the current time. The Time Now style enters the current date and time. The Time Now style can also optionally start a Countdown Timer which will notify the user when a specified amount of time has passed. The Stopwatch style enters the number of seconds between a start and stop tap on a button.
The Photo type displays a photo, or the words "Tap to capture image" instead of a textual value. Instead of a keypad, there is a menu with buttons to capture or recapture an image with the device camera or copy it from the device photo album, with buttons underneath to zoom, etc. Double-tapping resets to no zoom. Swipe works if no zoom. Two-finger pinch zooms. After capturing the image, the user may also annotate the image by drawing on the screen with their finger or a stylus. The drawing capability may be disabled by the form designer.
The Scanner type provides use of the device's camera for decoding barcodes to set the field value.
The Location type displays the latitude/longitude and a map if connected, or nothing if not set. Instead of a keypad, there is a button to query the device for the location.
The Signature type displays the signature with a timestamp under it and a yellow background, or the words "Tap to sign" instead of a textual value. Instead of a keypad, there is an area to sign, as well as buttons at the bottom to accept or clear.
The Audio type displays the words "Tap to record" or the words "Tap to play" instead of a textual value. Instead of a keypad, there are buttons to record, pause, play, rewind/fast forward, etc., with a button underneath to delete the recording. Swipe works if not recording or playing.
The Button List type shows a series of buttons, with the selected one, if any, indicated. Button Lists may be set to allow just a single selection (the default) or multiple selections, akin to radio buttons and checkboxes, respectively.
The List type displays the field value but provides a list of choices to choose from when tapped. Lists may be set to allow just a single selection (the default) or multiple selections, akin to radio buttons and checkboxes, respectively. Lists may also be set to include a textbox for searching, or searching and adding custom values.
The properties are:
Field Type
Click the Field Type property to display a list of the available types. Click on an item in that list to change the field to the specified type.
Title
The value of the Title property is displayed in the form as the title of the field. If the Title is not set, the Field property values will be displayed. (To not display a title, set the Display Variant property to "No Title".)
Short Title
The value of the Short Title property, if present, is displayed in the form as the title of the field for situations where a shorter title will be more appropriate. For example, the Short Title is used when a field is tapped in the Form Filler app and an editing screen is displayed. It is also used in the Management Console app as the default name of a field in the listing.
Field Name
This property is described in the Command Properties Screen Help topic.
List Items
This property is used to specify the choices in a List field or a Button List field. The textbox shows up to 10 of the choices, with the value produced by the choice shown in parentheses.
Clicking on the textbox will display a bigger textbox. Each choice to be displayed is represented by a line of text. A "|" character is used to separate what is displayed (to the left of the "|") from the value stored in the form instance data (to the right of the "|"). If no "|" is present, then the value will be the same as the displayed choice. Click Done to save the specified choices.
There is a dropdown below the Done/Cancel buttons for replacing the text with some predefined list choices.
Note that for fields that allow for multiple choices the value to be stored in the form must not include the "," character. This is because a comma is used to separate the selected choices in the field's value.
Choices Allowed
The Choices Allowed property is displayed for List and Button List Field Types. It is used to specify whether the field may accept just a single selected choice as the value (the default) or whether the field allows for multiple selected choices at once to make up the resulting value.
Search/Add
The Search/Add property is displayed for List Field Types. It is used to specify whether or not a header is displayed with the list to let the user type in a search value to filter the list (the filtering is based upon the text displayed). Optionally, it can specify that, in addition to searching, the searched-for value may be added to the list as a custom value if there are no matches. The default is to have no header at all.
Input lines
Text fields usually are entered with a single-line input control. This property lets you specify that a larger, multi-line input control should be used and that pressing "Return" will insert a line break instead of ending input when entering data into the field.
Timer Message
The value of the Timer Message property, if present, is displayed in the Countdown Overlay when a Countdown Timer is running.
Required Field
This property lets you specify whether or not the field, if displayed, must have a non-empty value. If a field is required and is has no value, an error indication will appear in the Form Filler.
Read-only
If a field is specified as read-only, the user will not be able to change its value. This can be used, for example, to keep a value, like a date/time, set by initialization from being changed.
Display Variant
The Display Variant property chooses among a variety of different ways to display the field in the form. The default is "Normal". "Medium Title" and "Large Title" show different size title text. The "No Title" variant suppresses the display of the title on the form.
Photo Resolution
The Photo Resolution property is available for Photo fields. It selects among Small (the default), Large, and Original. These indicate whether images selected when using the Form Filler app are to be resized to no more than 512 pixels in either dimension, 2048 pixels, or not resized, respectively. The user of the Form Filler app can also explicitly request no resizing for a given image.
Allow Drawing, Drawing Mode, Pen Color, Pen Thickness
These properties are available for Photo fields. They are used to control whether or not a photo may be modified by drawing on it, and, if so, what the initial settings for that drawing functionality should be.
Canned Images: Path of Default Canned Image, Canned Images Only, Show List If Blank, List of Canned Images For Field
These properties are available for Photo fields. The Canned Images textbox summarizes the values. Clicking the Canned Images textbox brings up a dialog for setting the values. Once property values are set, the Done button in the dialog must be clicked to save the values. The Cancel button reverts to the original values when the textbox was clicked.
The Path of Default Canned Image value sets the path within the folder hierarchy of the On-Device Data to the specific image to use as the initial value when a blank Photo field is tapped by the user. Paths assume On-Device Data location to start and then have optional sub-folders with names that consist of only alphanumeric characters and "_".
The Canned Images Only value determines whether images may or may not be captured with the camera or retrieved from the album in addition to using a canned image.
The Show List If Blank property determines whether or not to display the list of canned images instead of the camera screen when a blank field is tapped.
The List of Canned Images For Field text area sets an optional list of one or more canned images that may be selected by the user. Each line of the text area consists of the text to display to the user and the path within the folder hierarchy of the image. The two parts are separated by a "|" character, in the same manner as for a List type of field.
If the Default and List values are empty, and the two other properties are No, then no canned images will be available for the field.
Include Timezone
This property is available for Date, Date/Time, and Time Now fields. If "Yes", then values will be stored in ISO 8601 Format and include the local time zone offset from GMT instead of the default "YYYY-MM-DD" and "YYYY-MM-DD HH:MM" formats. This is only needed for applications that require such information.
Countdown Color
The Countdown Color specifies the CSS color value for a Time Now Countdown button. This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default is a dark shade of blue.
Countdown Duration, Sound, Vibrate When Done
The Countdown Duration, Sound, and Vibrate When Done properties are available for Time Now Countdown fields. They specify the length of time for the associated Countdown Timer as well as the optional sound to be played when the countdown is completed and whether or not the device should vibrate at that time, too.
Help Text
Fields can have an optional "?" button that displays text to provide additional information to the user filling out the form. The Help Text property lets the form designer specify that text. If no text is provided the "?" button is not displayed.
The value of this property is treated as plain HTML. For example, you can indicate line breaks with "<br>". However, it is not a template.
Preview Value
This value is used in the Preview Screen to show how the field will look with data. The preview value is not used by IF commands. If the Preview Data Form Property is set, this value is ignored.
Heading
The Heading command type is used to display text for organizing and describing the other parts of a form. There are different Heading Types with different visual presentation.
Heading Type
Click the Heading Type property to display a list of the available types. Click on an item in that list to change the heading to the specified type.
The available types are: Group (large, with bar above), Section (medium, with bar above), Instructions (small, italic), Plain (small), Small Subhead (small, bold, with no bar above), Medium Subhead (larger, bold), Large Subhead (even larger, bold), , and Warning (small red).
Text
The Text property specifies the text to be displayed.
The text is displayed as is, with special HTML characters (like "<") escaped to appear as themselves.
As with many of the command property text values, as a special advanced feature, TransForm TPL Templating may be used to insert special values. This templating is done through special expressions enclosed in "{" and "}". Data values are accessible through special names and syntax. See the TPL Templating section of this help for more information.
An example of using the templating feature would be this text for a section-type heading:
Child #{$groupcount+1} for {#parent}It might result in the heading:
Child #2 for John Doe
Heading Color (CSS color value)
The Heading Color property specifies the color to be applied to the text when it is displayed.
This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. Illegal or blank values will usually result in gray (#666), black (#000), or red (#F00), depending upon the particular Heading Type.
Text Align
The Text Align property specifies the horizontal alignment of the text within the line. There are three choices: Left, Center, and Right. The default is Left.
Layout
Unlike fields, Sections, and other items, when displayed within a multi-column Section the default layout width of a heading is "Full", not a single column. This may be changed by using the Width setting of the Layout property.
See Form Layout for more information.
Section Start, Section End
The Section Start and Section End command types are used to indicate the start and end of a group of commands that are part of the displayed form called a Section. All fields, headings, etc., between a Section Start and Section End command are part of the group.
Sections are used to control the spatial layout of fields, headings, and other parts of the form. By default, a section causes the items within it to be displayed indented. Through various properties, a Section may: Display the items within it in columns, not have indenting, be surrounded by a border, and have a background color. See Form Layout for more information.
Nested Section Start commands may be used to have sub-groups, such as to do additional indentation, or to have a group of narrower columns within one outer column.
The additional properties for the Section Start command are:
Background Color (CSS color value)
The Background Color property specifies the color of the background of the Section.
This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default (when no value is set) is transparent. Illegal values will usually also result in a transparent background, showing the background of any containing Sections or white.
Border Color (CSS color value)
The Border Color property specifies the color of the border of the Section if the Border is enabled as part of the Layout settings. If the Border is not enabled, this property will have no effect.
This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default (when no value is set) is black (#000). Illegal values will usually result in a black border (#000).
Layout
The SectionStart command has a Layout property similar to the one for fields, headings, and other commands, but with additional settings for each size. These additional settings are: Columns, Indent, and Border.
The Columns settings control how many columns the Section is divided into at the various screen width classes. The default is 1. The Indent settings control whether or not the section is has extra space on the left side. The Border settings control whether or not the section is surrounded by extra padding and a border line.
See Form Layout for more information.
Page Start, Page End
The Page Start and Page End command types are used to indicate the start and end of a page. (See the definition of Pages in the Terminology section.)
The Page Start command is displayed in the form as a rectangle with optional special styling. The commands between the Page Start and Page End commands make up the contents of the page. Tapping the rectangle will cause the items on the page to be displayed in place of the current fields, etc.
Page Start and Page End pairs may be nested for sub-pages.
The additional properties for the Page Start command are:
Page Title
The Page Title property specifies the text to be displayed in the rectangle. For example, it usually has the name that the user would expect for the page, such as "Future Actions Needed".
Display Variant
The Display Variant property selects among the different styles of displaying the page rectangle. The choices are: Normal, Small, Big, Detail, and Major Detail. When selected, the preview display shows how the rectangle will appear.
Page Color (CSS color value)
The Page Color property specifies the color to be applied to the border of the page rectangle and the header at the top of the page when it is displayed.
This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default is a gray. Illegal values will usually result in no color.
Go To, Define Target
The Go To command is used to specify a rectangle that may be tapped to switch the display of the Form Filler app to display a specified part of the form. The Define Target command is used to specify a specific place in the displayed form that the user can "go to".
The Go To command may optionally switch to the start of the next Page or to a specific Target.
The additional properties for the Go To command are:
Go To Type
The Go To Type property specifies whether the Go To will switch to the next Page or to a specified Target.
Go To Message
The Go To Message property specifies the text to be displayed in the rectangle. For example, it usually has the name that the user would expect for the target, such as "Main Values". The default for the Go To Type Next Page is "Next Page".
Target Name
If the Go To Type property is "Target", the Target Name property specifies the name of the target to switch to when the Go To rectangle is tapped. The next Define Target command with that name encountered in the form as displayed will be used at the target of the Go To.
The target name should be simple alphanumeric text, such as "mainvalues". It need not correspond to the Text property.
Display Variant
The Display Variant property selects among the different styles of displaying the GoTo rectangle. The choices are: Normal, Small, Big, Detail, and Major Detail. When selected, the preview display shows how the rectangle will appear.
Page Color (CSS color value)
The Page Color property specifies the color to be applied to the border of the GoTo rectangle.
This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default is gray. Illegal values will usually result in no color.
The additional properties for the Define Target command are:
Label in Table of Contents
The Label in Table of Contents property specifies the text to be displayed in the Form Filler app Table of Contents for the target location in the form.
Target Name
The Target Name property specifies the name of the target being defined. There should be at least one corresponding Go To command that has the same target name.
The target name should be simple alphanumeric text, such as "mainvalues". It need not correspond to the Label in Table of Contents property.
Change Status
The Change Status command specifies that a button should be shown for changing the status of the form instance and then initiate the uploading of the form to the server to save the data. The same effect may be had by using the Change Status menu command while editing a form in the Form Filler app and then using the Upload Now button above the list of forms. This is a user-friendly way of doing both operations within a form, optionally using IF commands to set different statuses depending upon different conditions.
The Status Change Message property specifies what should be displayed on the button. The default is "Close and Upload Form". If the form already has the desired status, then the Upload-Only Message property value will be displayed. The default is "Upload Form".
The Set Status To property lets you choose the status to change to from the list of statuses available for this account.
There is a property to set the form value that will prevent the form instance (that particular record in the database) from being downloaded to the Form Filler app in the future. This is usually the default "No" for many common applications.
Countdown Timer
The Countdown Timer command specifies that a button should be shown for starting a Countdown Timer. A Countdown Timer lets you schedule a notification when a specified amount of time has passed. The timer itself does not set the value of any field nor initiate any other change to the form data. Countdown Timers are used, for example, when a user needs to capture data over a predetermined amount of time (such as counting how many items are produced by a process in a certain period) or to facilitate moving from one process to another (such as limiting form filling to a certain number of minutes).
The Title property sets the text to be displayed on the button.
The Short Title property, if present, is displayed in situations where a shorter title would be more appropriate, such as above the Countdown Timer Editor.
The Countdown Color property optionally sets the color of the button. This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default is a dark shade of blue.
The Countdown Duration property specifies, in whole seconds, the amount of time that the timer runs.
The Sound property specifies which built-in sound, if any, to play when the timer finishes. The names are descriptive.
The Vibrate When Done property specifies whether or not the device should vibrate when the timer finishes.
Action Button
The Action Button command specifies that a button should be shown that executes TPL code when tapped. This is an advanced feature that is used to provide additional functionality.
The Button Action Name property specifies the name of the TPL action to run when the button is tapped. The name must be alphanumeric, starting with a letter, with no spaces nor "_" characters. The TPL "ON *button_ButtonActionName" code block will be executed. The code for the action may be edited using the TPL Editing and Testing screen.
The Title property sets the text to be displayed on the button.
The Short Title property, if present, is displayed in situations where a shorter title would be more appropriate, such as above the Action Button Editor.
The Button Color property optionally sets the color of the button. This property must be in the form of a CSS Color Value. For example, it may be a hexadecimal RGB value, like #FF0000 or #F00 for red, or the "rgb()" function, like rgb(0,255,0) for green, or one of the standard CSS color keywords, like blue. The default is a dark shade of blue.
IF, ELSE, ELSE IF, ENDIF
The IF, ELSE, ELSE IF, and ENDIF command types enable the conditional display of other commands (such as fields and headings) depending upon the result of a test. For example, they may be used to only display a field requesting a detail if another field, a button list, has the value "Yes".
Separate IF, ELSE, ELSE IF, and ENDIF commands are used in a manner similar to most programming languages. Inserting an IF command automatically also inserts a corresponding ENDIF that may be moved as needed, or other commands may be inserted between them.
The one special property for the IF and ELSE IF commands is the Test property. This is a TPL expression that can evaluate to "true" (non-blank) or "false" ("").
TPL expressions are explained in greater detail in the TPL Expressions section of this help. (Note: In early versions of TransForm, the IF command used JavaScript expressions with a different syntax for accessing fields and other data. See Pre-TPL Syntax for more information if you are maintaining or upgrading form types that made use of this functionality.)
The TPL expressions may refer to fields at the current level using "##" followed by the field name. Top level fields may be referred to using "#" followed by the field name. You can refer to the current status ID with "$#status" and you can refer to a true/false value ("Y"/"") indicating if any problems were detected in the commands preceding (above) this one with "$#missingrequired" and "$#haserrors".
Note: TPL uses "==" to test equality and "!=" for inequality. The characters "&&" and "||" may be used for "and" and "or", respectively, and parenthesis may be used for grouping. Text values are enclosed in double-quotes (e.g., "This is text").
To make it easier to create the tests, there is an "Insert Field Name" button under the Test property textbox. Clicking it will display a list of fields at the current and top levels. Click on a row in the list to insert the appropriate text for referring to that field.
For testing through use of Preview, either use Form Preview Data (defined in JSON on the Form Properties Screen) or the Preview Value property radio buttons above the Comment property. Preview values of other fields are not used.
Examples of tests are:
##casingIntact=="Yes" #quantity>20 len(#array1)>0 && #array1[0].b=="bee"
The first example is true if the field "casingIntact" has the value "Yes". The second example is true if the top level field "quantity" has a value greater than 20. The last example is true if the top level data group with field name "array1" has at least one item and the first item's "b" value is "bee".
Data Group Start, Data Group End
A Data Group is the term used to describe an array of separate groups of fields. It is the way you get a parent-child, one-to-many relationship, such as invoices with line items -- the invoice is the parent and the line items (each with a product and quantity field) are the children.
The Data Group Start and Data Group End command types are used to bracket the commands in the Commands List for the fields that make up an element in that array. That is, the Field commands between the Data Group Start and Data Group End may be repeated over and over, once for each element (or "item") in the array, when the form is displayed. In the Commands List itself, command between the Start and End are displayed indented.
Data Groups may be nested. That is, there may be parent-child-grandchild relationships.
When displayed in a form along with form instance data, the Data Group is seen as the Field, Heading, and other commands in the group. It also is seen as a button after the group for adding additional items (sets of those fields) to the group. Optionally, after each item in the group, there is a button to delete that item.
The Data Group End command type has only common properties. The properties of the Data Group Start command type are:
Name
The name is similar to being the title of the group. It is sometimes used by the Form Filler to indicate to the user that a field is in a Data Group. It is also used to help create the default New Message property for the Data Group.
New Message
Immediately following the last item in the Data Group (if any), a button will be displayed with a "+" followed by the New Message text. Example text would be: "Add another photo". If no New Message is provided, a default message will be created, using the Name property if present.
Delete Message
Immediately following the each item in the Data Group (if any), a button will be displayed with an "x" followed by the Delete Message text followed by the character "#" and the index of the item (#1, #2, etc.). If there is no Delete Message text, the button will not appear.
Array Name
The Array Name property specifies the name to use in the Form Instance JSON for the attribute/value pair that contains the array object that holds the Data Group data. This is similar to a Field property in a Field command.
For example, in the Parent/Child example used in this Help for Form Instance JSON Data, "children" would be the Array Name property of the Data Group Start command that specifies the Data Group with "name" and "age" fields for each child.
In general, the array name should not include any characters other than letters and numbers and should not start with a numeric digit. Names are case-sensitive, but, for best compatibility with other applications, array names and field names should not differ only in the case of letters. While names with special characters (such as space, "_", or "-") may work for displaying and gathering data on the form (and may be needed when creating or reading JSON for an existing application outside of this system) they may cause issues in this app or others reading the data, such as in TPL code.
Initialization
The Initialization property is similar to the Initialization Commands Form Property. When a Data Group array item is first created by the user in the Form Filler app by tapping the "+ Add" button, values in fields by default are all undefined (blank). They may be given initial values by providing commands in the Initialization property textbox. Only top-level fields within the Data Group (that is, fields not within a nested Data Group within the Data Group with this property) may be initialized using this textbox.
An initialization command consists of a line of text, one line for each field being initialized. There are several forms:
fieldname:text,value fieldname:date fieldname:time fieldname:datewithzone fieldname:timewithzone
The field type (i.e. "text", "date", "time", "datewithzone", and "timewithzone") must be lowercase.Fieldname is the name of the field (e.g., "field1", not the Title "User Name"). Value is the text to use as the initial value. The second and third forms set the value to the text value of the current date (e.g., "2017-01-10") or the current date and time (e.g., "2017-01-10 09:55:05").
HTML
The HTML command type is similar to the Heading command, except that there is no built-in formatting. The text is treated as HTML and is not escaped. That is, the text "<b>bold</b>" will be a word in bold. This gives the form designer further control over the presentation of the form and accompanying text. There is only one property, the Text property.
Note that the HTML is processed and only certain syntax, tags, and attributes are allowed. Only double-quotes are allowed for quoting attribute values, not single quotes. Attribute names (like "style") must be immediately followed by equal and double quote. Links (<a> tags) and most attributes that take a URI are either not allowed or restricted. The <input> tag is not allowed. All open tags must be closed in the HTML text of the command (that is, no <div> without a corresponding </div>), and void tags must have closing "/>" (e.g., <br/>). Basic SVG is allowed. <img ... /> tags are allowed with certain white-listed on-device data asset and external URL specifiers (not documented here).
You can test HTML text using the Preview of the form to check if a desired construct is allowed.
TPL Templating is supported in the same manner as the Heading command.
For a full listing of supported HTML tags and attributes see Supported HTML Markup.
Set Error Indicator
The Set Error Indicator command type adds an error to the list of current problems for the form instance data. A red star is added to the Form Tab and an entry is added to the form instance "Problems List" in the Form Filler app. This feature may be used to flag data validation errors or other conditions using IF commands.
If a Set Error Indicator command is skipped (as the result of an IF or IF ELSE test evaluating to "false" or being in a Data Group that has no items) then no addition is made to the list of current problems.
If a Set Error Indicator command is executed, the content of the Error Text property is used as the text to be displayed in the list of problems. In addition, if there is text in the Optional Message property, that text will be displayed in a bold red font in the form at that point. Alpha Anywhere Templating is supported in the Optional Message property in the same manner as the Text in the Heading command.