For administrators. It summarises the different types of controls/fields available for use in templates.
This document is for administrators. It summarises the different types of controls available for use in templates. Controls are sometimes referred to as fields. Those terms are sometimes used interchangeably but there is a difference, as follows:
Consider a form with a question that needs to be answered with Yes or No. You can do that by putting into the form template a question control. That provides the ability to display question text and 2 buttons: one for YES and one for NO. That is what the user sees and can interact with.
Fields provide data that comes from a control. Some controls have more than 1 field. For example the Project control has 3 fields: Project Name, Number and Address. Question controls have several fields.
Text Field is the default control. It is an area in which you can type a single line of text.
Text Area is a version of Text Field for longer text entry, it supports multiple lines of text and expands as needed to allow more text to be entered.
Recipient is a special type of Text Control for an email address. It is a system control/field that is only available in Memos. On the iPad, you can enter an email address or press the + button to select an email address from the iPad’s contacts list.
Address is a special type of Text Control for postal or street addresses. On the iPad, it includes a button that will let you insert the address of a person in your contacts list.
Readonly Text allows you to place a large body of text (anything larger than you can put into a display name) in the form to instruct whoever is filling it out. In the template editor, click the cogwheel icon to open the settings panel to edit the read-only text.
In the case where you want to have different Readonly Text on each line of a table, you can do that after turning on the setting "Different value per row".
Number Controls only allow numeric characters to be entered (as well as a minus sign and a decimal point).
Date is a control that, when selected by the user, presents a drop-down selector of dates to choose from.
Time controls allow user to select a time (in hours and minutes).
List Controls are used to provide a dropdown list from which a user can choose an item, or several items. They are a commonly-used way to make it quicker and easier for users to enter data. They also provide the benefit of standardising data by preventing misspelling and non-standard entries like abbreviations.
In the template editor, click the cogwheel icon to open the settings panel to change list settings.
By default, a list control only allows a user to select a single item (after selecting an item the list closes). To allow them to choose multiple items, turn on the setting "Multi Select".
Tip: if exporting data from multi-select lists then you can use the option "Group list items" to control whether that is exported together or over multiple rows.
The items that appear in the dropdown list can come from one of several different places. That is determined by setting the List Type:
Custom List allows the template administrator to define a list of items, which are stored within the template. Form users cannot add, edit or delete those items.
Company List draws items from the Companies List, which you can access in the web app under Admin => Companies.
Organization List draws items from an Organisation List, which you select in the control's settings. Form users can add, edit and delete items if the Org. List is not locked.
Project List draws items from a Project List, which you select in the control's settings. Form users can add, edit and delete items.
WBS Item lists draw items from the user's project's WBS Items.
This type of list is also know as a Custom WBS control.
If you don't see an option for "WBS Item" type list then please ask APE Mobile Support to turn it on.
Yes/No controls allow the user to indicate an answer to a question that can be specified by clicking on the pen tool. In the template editor, click the cogwheel icon to open the settings panel to edit the question text.
In the case where you want to have different Yes/No questions on each line of a table, you can do that after turning on the setting "Different value per row".
Yes/No/NA behaves the same as Yes/No, except that it also has an option to select N/A.
All question controls have at least 5 merge fields as follows:
The 1st merge field contains the answer as a word ("Yes", "No" or "N/A").
The 2nd merge field contains the details (which is normally the question).
The 3rd merge field contains an X if the answer is Yes (otherwise it is blank).
The 4th merge field contains an X if the answer is No (otherwise it is blank).
The 5th merge field contains an X if the answer is N/A (otherwise it is blank).
That allows flexibility in how the answer is presented within the output PDF. The 3rd, 4th and 5th merge fields are used when the answer is presented as an "X" in a suitable box or cell in a table.
They have more fields if there is an associated action.
This behaves the same as a Yes/No/NA control, except that it presents the choices as A, B, and C rather than Yes, No, and N/A.
A Signature Box controls allows the user to sign the form.
If you are not using the Add-in to insert signature merge fields then: If a user has signed the form, then the default behaviour is to insert the text “Signed in APE Mobile” into the generated PDF. To get the signature image, you need to edit the merge field to prepend “Image:” to it. For example, if your merge field is inserted into the Word document as “Signature”, then you need to change this to “Image:Signature”. For more details, see Inserting Merge Fields into a Word Document for Windows or Mac.
Table is a special control that enables you to define a table containing multiple controls, each of which is a column in the table.
In the template editor, click the cogwheel icon to open the settings panel to edit the table details.
Example view of a table on a mobile device:
When entering data, clicking a row in the table opens a dialog for entering values:
Note: You can’t put a table inside a table or an Action template. If you want to list multiple actions then use a Punch List.
Formulas are used to do calculations based upon values from fields of other controls. They work like formulas in Excel.
UPDATE: The way that fields are referred-to HAS CHANGED. The description below needs to be updated, because references like C1 and C2 have been replaced by A and B (for example) so they are more like Excel. To learn more see Formula Field Referencing.
In template editor, inside a table:
As a simple example, here is the table editor with a table that contains a formula field that adds two numbers together:
In the above example, C1 and C2 are column field references. C1 refers to the first column (First Number) while C2 refers to the second column (Second Number).
Note that, unlike Excel, you do not start formulas with an “=” sign (i.e. the correct formula is “C1 + C2”, not “=C1 + C2”.
Here’s what the table looks like on the iPad:
Clicking a row in the table opens a dialog for entering values:
The formula value is recalculated every time you change the field you are editing, or else when you hit return.
There are three types of values that are recognised by formulas:
- Numbers, which can be references to Number fields, or else numeric constants like 1, 2.5, 3004.0, etc. For example:
- C1 + C2 (where both C1 and C2 refer to numeric fields)
- 100 + 1
- C1 + 100 (where C1 refers to a numeric field)
- Times represent the time elapsed since midnight. These can be references to Time fields, or else time constants like 08:00, 17:30, etc. For example:
- C2 – C1 (where both C1 and C2 refer to Time fields)
- 17:30 – 08:00
- C1 – 12:00 (where C1 refers to a Time field)
- Strings, which are everything that is not a Number or Time (most commonly, these would be string constants or Text Fields. For example, the following uses the IF function to display different strings based on whether a number is zero or not.
You can use the following numeric operators:
- + (addition)
- - (subtraction)
- * (multiplication)
- / (division)
Note that these cannot be used with two strings.
You can use the following conditional operators:
- = (equal to)
- <> (not equal to)
- > (greater than)
- < (less than)
- >= (greater than or equal to)
- <= (less than or equal to)
UPDATE: For a full list of functions, including newly added functions, see List of Formula Functions.
This returns the absolute value of a number or time. E.g. ABS(-1) is equal to 1.
This returns the number of hours in the time value of the expression. For example, if the expression evaluated to “15:30”, then the value 15 would be returned.
126.96.36.199 IF(condition, true expression, false expression)
The IF function returns the value of the true expression if the condition is not zero, otherwise it returns the value of the false expression.
This returns the number of minutes in the time value of the expression. For example, if the expression evaluated to “15:30”, then the value 30 would be returned.
188.8.131.52 VLOOKUP(lookup_value, list_name, column_number, range_lookup)
You can use the VLOOKUP function to search the first column of a multi-column Organisation List, and then return a value from any column on the same row.
The arguments are as follows:
- lookup_value is the value to try to match.
- list_name is the name of a special multi-column Organisation List, inside double quotes “”.
- column_number specifies the Organisation List column from which to return a value if a match is found.
- range_lookup specifies how to look for a matching row. If it is zero, then VLOOKUP will only return a value if an exact match is found. If range_lookup is not zero, then VLOOKUP will return an exact match if one is found, otherwise it will return the next largest value that is less than lookup_value.
- Time and Number: This will attempt to treat the number as a time. The value of the number is treated as a number of days. E.g. 1 = 24 hour, 0.5 = 12 hours, etc. So “08:00 + 0.5” should become “20:00”.
- Time and String: This will attempt to convert the string to a time (and will return an error if this cannot be done).
- Number and String: This will attempt to convert the string to a number (and will return an error if this cannot be done). E.g. using 0+C1 in a numeric formula (instead of C1) helps to handle situations where a user inputs a non-numeric entry for C1.
8 Geolocation Controls
Geolocation controls enable site users to get their current coordinates when filling-out a Form, from their device's GPS (or other means of determining position).
Administrators can make use of the captured Geolocation data in form PDFs and Exports in different formats (decimal degrees and degrees/minutes/seconds) and also the location accuracy and capture time.
In template editor:
9 Diagram Controls
Diagram controls allows template administrators to attach an image or a PDF file to a template. Image files can be JPG or PNG format.
In template editor:
When a user is filling-out a form:
- images appear as small-size 'thumbnails'.
- PDFs appear as a hyperlink with the name of the PDF file.
The user can press (or click on) the image or hyperlink to view the full size image or PDF document.