Action Button

TABLE OF CONTENTS

• Basic Properties
  • Data Name
  • Title Text
  • Hint Text
  • Action Buttons
  • User Interaction
• Layout & Styling
  • Background Color
  • Field Layout
  • Flexible Columns
• Validation & Behavior
  • Required
  • Visibility
  • Read Only
  • Validation Message
• Advanced Options
  • Bind to Data Source Column
  • Bind to Global Value
  • Exclude from Export/Display
  • Always Trigger on Button Press
  • Interaction Result
  • Display Result to User

This control displays up to 5 buttons that can launch the user into a number of different actions such as dialing a phone number, opening a web page, creating an email, opening another screen in the app, opening a doc or displaying a location/address on a map.

Basic Properties

Data Name

This is the name of the field that should be referenced in any form logic or API calls. Users will not see this name on the form.

Data names cannot contain spaces or any special characters other than an underscore and must begin with a letter. They are case-sensitive and must be referred to precisely whenever they are referenced.

Title Text

This is the name of the field that will be displayed to users on the app. This property is completely optional; while a field must contain a data name, a field title is optional.

The text color may be chosen with a hex code. The text may be also formatted as Bold or Italic and given a relative size -- Small, Medium (the default) or Large.

Hint Text

This optional field can be used to show secondary information to the user in the app. Consider using this to provide instruction or clarification to the user as they fill out the field.

Formatting options for this property are the same as those given available for the Title Text property.

Action Buttons

This property is used to set up the buttons you wish to appear by position on the screen. Please see the screenshot below with annotations for detail on the various settings.

1. Buttons - these are the five individual buttons able to be shown on the control. These will show in series to the user from 1 to 5, 1 being on the far left and 5 on the far right. Each button will show if any text is entered into their respective text field below (see #2 in this list below).
2. Text - this is the text showing to the user on the button. The button size will scale in relation to the length of the text string, but only to a point; text that runs too long will be obscured.
3. Font color - this is the font color of the text on the button. Bold and Italic options are also available to the right.
4. Font size - this is the size of the font on the button. The dropdown options are Small, Medium and Large.
5. Button color - this is the color of the button behind the text. Transparent can also be chosen instead by clicking the checkbox to the right.

User Interaction

This property defines the action applied when this button is tapped by the user. The actions available are listed and described below.

• Create Email To - this will send an email to the address specified in the Pass Parameters field with the app's default email program. The parameter passed can include static text or field values. Pass values from fields in the form using the {{dataname}} syntax.
  
  
• Create SMS To - this will send an SMS message to the address specified in the Pass Parameters field with the app's default messaging program. The parameter passed can include static text or field values. Pass values from fields in the form using the {{dataname}} syntax.
  
  
  
  Note that this can only be used on a device with messaging capability.
• Dial Phone Number - this will dial the phone number specified in the Pass Parameters field with the app's default phone program. The parameter passed can include static text or field values. Pass values from fields in the form using the {{dataname}} syntax. 
  
  
  
  Note that this can only be used on a device with dialing capability.
• Exit Without Saving - this will prompt the user to exit the form without saving the entry as a local draft. This essentially saves the user two keystrokes, since going back and clicking "Exit without Saving" will not be necessary.
• Exit & Save Changes - this will save the form as a local draft and exit the form without prompting the user. This essentially saves the user two keystrokes, since going back and clicking "Save and Exit" will not be necessary.
• Force Sync - this will Force Sync the local device. This is a very useful action as it saves the user several keystrokes, bypassing the need to navigate to return to the device start screen and settings page.
• Geocode Address - this will convert an address text string into decimal latitude/longitude coordinates. The address must be provided in the "Pass parameter" field below and can be either static text or a form field reference with {{dataname}} syntax and in standard address format - i.e., Street Address, City, State/Province, Postal Code, Country or {{address}}, {{city}}, {{state}}, {{postal}}, {{country}}.
  
  

  
  

  The geocoded coordinate result (if any) is populated into the field, with the result being "lat lon" - e.g., -13.3823724 153.9832837. The result will not be visible to the user unless the "Display Result to User" property is enabled (see Advanced Options further in this article).

• Jump to Form Location - this will allow the user to navigate to various parts of the form based on the target chosen in the "Target for interaction" field. These targets can be relative or specific - i.e., the next or previous page, or a specific page somewhere on the form.
  
  

  
  

  A common and recommended use for this is within repeating tables, using the Repeat Row targets to allow users to quickly add new rows or navigate to other rows without needing to leave the table.
  
  Note that although by default the app goes to the first repeat if one exists when jumping to a repeatable page, the app can instead always create a new repeat, skipping over any pre-existing repeats, if the "Always Jump to New Repeat" checkbox is enabled.
  
  
• Open Doc - this will open a document from your document library (read more about this here). The target document can be a specific reference from the drop-down or a dynamic value determined by a passed parameter. For the latter, you may pass values from form fields using {{dataname}} syntax or specify the unique ID or external ID of the Doc to open using static text or field values.
  
  
• Open Entry - this will open the form entry specified in from the "Pass parameters" field below. This parameter can be static text or dynamic reference based on a form field such as a choices field linked to the App: Entry History data source. Note that the latter will only work if previous form entries have been submitted on the local device. If none have been submitted, the user will receive an error message when opening the screen since the linked data source will be empty.
  
  
• Open Screen - this will open another screen. The target screen can be chosen in the drop-down, with parameters optionally passed in the field below. These parameters can be static text or dynamic values from the form using the {{dataname}} syntax.
  
  

  For Form targets, you can preset target fields with "dataname:value," pipe-separated.
  E.g., field1:{{city}}|field4:hello
  
  For Listing and Mapping screen targets, you can pass in a formula for filtering the target rows. Use {{target[column]}} for target columns.
  E.g., {{target[3]}} >= {{price}}
  
  For Detail and Task Details targets, pass the identifier of the target data row or Task. For data rows, the identifier must match the first column's value.
  E.g., {{mychoice}}
  
  
  Once the user has submitted or exited the target screen, they will be returned to the original form with their progress retained.

• Open Task - this will open a task as defined by the "Pass parameters" field below, where the Task ID for the target Task should be specified. Columns from the App Tasks data source can be referenced using {{this[column]}} syntax - e.g., {{this[2]}} will pass the 3rd column's value for the current selected row.
  
  

  
  Note that this will only work if open tasks are present. If none are available, the data source will be empty, and the user will receive an error message when opening the form.
  

• Open URL in App - this will load the URL specified in the "Pass parameters" field below within the app, provided the device has network connectivity. The app will be used rather than a web browser. The parameter may be static or dynamic, based on a form field reference. Pass values from fields in the form using {{dataname}} syntax -- e.g., http://www.example.com?val1={{city}}.
  
  
• Open Link in Web Browser - this will load the URL specified in the "Pass parameters" field below within the app's default web browser, provided the device has network connectivity. The parameter may be static or dynamic, based on a form field reference. Pass values from fields in the form using {{dataname}} syntax -- e.g., http://www.example.com?val1={{city}}.
  
  
• Show Address on Map - this will show a map featuring the address specified in the "Pass parameters" field below. The address can be either static text or a form field reference with {{dataname}} syntax and in standard address format - i.e., Street Address, City, State/Province, Postal Code, Country or {{address}}, {{city}}, {{state}}, {{postal}}, {{country}}.
  
  
• Show Coordinates on Map - this will show a map featuring the latitude and longitude coordinates specified in the "Pass parameters" field below. The coordinates can be either static text or a form field reference, space-separated and using the {{dataname}} syntax - e.g., -12.345678 76.54321 or {{mylocationfield}}.
  
  
• Upload Form and Print - this will submit/upload the form and print an output report based on the HTML template provided in the App Printing section within the form Settings page. The print job will be sent via the device's default printing service. Please see this article for more detail.
• Upload Form - this will submit/upload the form. This serves as an alternative to the usual navigation to the end of the form to press the Upload button there.

Layout & Styling

Background Color

The color chosen in the hex code field here will apply to the field. The Transparent box can also be chosen instead for making this transparent instead of a solid color.

Field Layout

This drop-down determines how this field is shown on the screen.

• Vertical centers the action buttons in their respective columns.
  
• Horizontal will place the action buttons in series at the right of the screen.
  
• Horizontal (Tablets Only) will use Vertical layout for phones and Horizontal for tablets.

Flexible Columns

This checkbox option will use flexible columns on the screen, which means that positions will be determined by the number of buttons; by default, buttons are shown in fixed positions. The exact appearance/size of the buttons will vary based on the device operating system and orientation.

For example, notice the difference on our Android app with the device in landscape orientation:

Fixed:

Flexible:

Validation & Behavior

Required

Checking this box will enforce validation against this field to make the field required, disallowing the user from progressing to the next page or submitting the form if it is left blank. If the user tries, they will be prompted with an error to return to the field and make a selection. When this validation occurs is determined by the "Validation Property" chosen on the page level; please see this article for more detail on this.

This property can also be made conditional based on a formula. To enable this, click "add condition" below the checkbox and enter a formula into the field that populates. The formula serves as the basic of the required-ness of this field.

Please see this article for more information on conditionally-required fields.

Visibility

The contents of this field will determine whether the field will be visible to the user. For more detail on visibility rules, please see this article.

Read Only

If this checkbox is checked, users will be able to see the contents of the field but will be unable to make edits.

Similar to the Required property, the Read Only property also includes the ability to define a conditional formula determining whether the read-only property is enabled. Click "add condition" to define such a formula.

Validation Message

The contents of this property will serve as a custom message to display to the user if their input fails validation.

Advanced Options

Bind to Data Source Column

This property allows for the binding of the contents of the field to a data source that is linked to either a choices field or data field on the form. For details, please see the screenshot below:

1. The data source can be selected with this dropdown. More than one will be available if multiple data source control fields (choices fields or data fields) have been added to the form.
2. The data source control field can be selected from this dropdown. More than one will be available if multiple data source control fields for the same data source have been added to the form.
3. The column on the data source to be bound can be selected from this dropdown.

Data Source binding allows you to create forms that can load data from, and update data to, any given data source. This opens up amazing opportunities to have dynamic data that is updated on the move (e.g., adding contacts or clients). For more information, please see this article.

Bind to Global Value

Global Values are a local key/value store that is available to any Screen on the app. Use this property to allow the user to view and save defaults for use across the app (e.g., a default project or customer). Please see this article for more information.

Exclude from Export/Display

By default, every field is displayed on Form entries in the Data area, and is included in non-templated exports (e.g., generic pdf, CSV, spreadsheet, database connectors). Use this property to prevent this field from showing on all such display and exports.

Always Trigger on Button Press

This checkbox option specifies that formulae must be triggered every time the button is pressed. By default, buttons will only trigger dependent formulae once - on the first time that a user clicks this button.

This is useful for scenarios involving counters/clickers where the field's value increments on each button press - e.g., a Number field with Dynamic Value of:

IF(NOTBLANK({{button}}), VAL('numfield')+1, 0)

Interaction Result

This property can supply a static answer value that is always set to this field, no matter which button is pressed. By default, this field is populated with the title of the button last pressed by the user.

Display Result to User

This checkbox option determines whether to display the field's result to the user as inline text below the buttons. The value displayed would either be the title of last button pressed or the Interaction Result (if specified - see above).