6.4 Description Formula
The Description Formula field can be used in Form, Repeat and Link elements to customize data description in data listings and for e.g. repeat headers. You may type in static text directly in this field, but it is generally used with parameters that change every time the form or repeat is filled out. In other words, the formula picks out certain data the user has entered in the form and displays them ‘outside’ of the form, so you don’t have to open it to find important data.
Note: You can add return characters (line break) with the Enter key in the formula to format it better.
Description Formula of a form
The Description Formula property of a form is used to give each filled form a description/ summary based on its content. That way you can easily distinguish between filled forms without having to open them one by one from the Dashboard.
A description can contain any text as well as element IDs found in the form (see list of functions below). By default, it shows the first 5-7 elements of the form but it can be customized to contain any of the form’s elements.
Example
{#elementX} – {#elementY} where elementX is filled in by the user as “ABC” and elementY is filled in as “123”, will produce the description = ABC – 123
For instance, this specification …
… creates the following information shown in the form’s data listing in the Dashboard, under the heading Description:
The Description Formula will also be be used as the name for the PDF file sent automatically in email notifications, see Designing: 8.2 Automatic email notifications with PDF reports and form links.
The formula is also listed in the Zegeba app, and shows the difference between one data capture and the next. See Using: 3.6 Viewing and editing existing data.
Description Formula of a link to a repeat
A link can link to a repeat instance by setting its Reference property to e.g. “repeat://elementIdOfRepeat”. The link is a one-to-one link to a repeat instance and the heading of the repeat can be customized by the link by using the Description Formula.
Description Formula of a repeat
A repeat description is used to give each repeat instance a unique name based on some content, for instance the question that the information given in the repeat is about. Format and usage is the same as for Form Description, with the addition of a way to reference variables from within the repeat.
List of Description Formula functions and properties
| ITEM | DESCRIPTION | FORM | REPEAT | LINK |
|---|---|---|---|---|
| {#element_ID} | Reference any element ID in the form or repeat | X | X | X |
| {#element_ID|NA} | Alternative value if description is processed with an empty text as a result. The | character is an OR logical operator where NA is the result if there is no answer to the question with element ID “element_ID”. See details in section below. |
X | X | X |
| {@element_ID} | Reference the Label of any element ID in the form. Can be combined with relative references (see below) |
X | X | X |
| {@this} | Relative reference to the starting element (this or element_ID). Relative references can be nested. Examples: {@this.parent} {@this.parent.parent.parent} {@this.parent.first-child} {@this.nth-child(5)} {@this.next-sibling} {@this.nth-sibling(5)} {@this.parent.first-sibling} {@this.nth-parent(3)} Keywords that can be used for relative references: parent - references the parent element, can also use .parent.parent etc. first-sibling - gets the first sibling of the element last-sibling - gets the last sibling previous-sibling - gets the previous sibling next-sibling - gets the next sibling nth-sibling(5) - gets the sibling number 5 (first element = 1, not a zero based index) first-child - gets the first child last-child - gets the last child nth-child(5) - gets the child number 5 (first element = 1, not a zero-based index) nth-parent(3) - jumps to the third parent (used instead of parent.parent.parent) NOTE! In case the nesting fails to find the referenced element, the result of the processing of the related segment of the formula will be blank. |
X | X | |
| {§form_property} | Reference any element ID in the form or repeat. The following form properties are available: formCompletedId formDataId formDataVersionNo formHashId folderId formId formVariableName formVersionId formVersionName groupId hasAnswerChanges isValid lastEditDateTime lastEditSequenceId lastSavedDateTime needsUpload questionsAnswered state surveyId versionId |
X | X | X |
| {&loggedInUsername} | Reference the username of currently logged in user. | X | X | X |
| {$function_name} | The following function names are available: date day month time year |
X | X | X |
| {!repeatInstance.#element_ID} {!repeat.#element_ID} |
This gets an element ID from within the repeat as part of the description of a repeat instance - as opposed to just using {#element_ID} which would use the latest edited instance with that element ID. |
X | ||
| {!linkedInstance.#element_ID} {!linked.#element_ID} |
Similar to the above parameter, but referencing a linked repeat instance (e.g. parent) |
X |
Alternative value if description is processed with an empty text as a result
In some cases, a value is not always set due to e.g. rules or the state of elements of the form. When this happens, some users may want to add an alternative text e.g. “NA” if no answer is set yet.
The format is
{#element_ID|Alternative Text}
where “Alternative Text” will be shown if there is no answer to the question with the element ID “element_ID”.
