Action Buttons

Last updated 9/04/2025

The On Press and Do Press events can be used individually. All three events can be chained together. The On Complete event can be chained to either the On Press event, or the Do Press event, or both. The On Complete event will be called if the On Press event and the Do Press events are successful.

The On Complete event can be used on its own, however, it is not recommended as it is designed to run after the On Press and Do Press events.

Event	Executes	Description
On Press	Client	Executes when an action button is clicked.
Do Press	Server	Executes when an action button is clicked, if chained to the On Press event, it will be called after the successful execution of the On Press event.
On Complete	Client	Executes when an action button is clicked, when chained to the On Press event, it will be called after the successful execution of the On Press event. When chained to the Do Press event, it will be called after the successful execution of the Do Press event. When chained to the On Press and Do Press events, it will be called after the successful execution of the On Press and Do Press events.

How to Use Action Buttons

The following explains what is available on an action button when adding the button to different actions. When setting variables using Five's

setVariable()

function. The variables will be global and can be used in any action button using

five.variable

.

Forms

The

context

parameter contains a value called

Form

, this contains the information on the current form.

Example

{"Form": {"Name":"John", "Product.ProductID":"b7edcc3e-e101-414d-834d-83adc7834f18"}, "FileName":""}

The

Five

object contains the properties

form

,

field

, and

stack

.

Processes, Charts, Reports, Dashboards, and Mail Merges

The

context

parameter and the

Five

object contain no information based on the current process, chart, report, or dashboard. You need to set variables in the function attached to the On Press event to gain access to the current action's information and have the variables available in the backend using the values from the frontend.

Data Views

The

context

parameter contains no information about the screen fields on the current data view, however, the

Five

object automatically maps the variables from the screen fields using the

variable

property on the

Five

object so you do not need to manually set the variables to have them available in the backend.

Data field values are available through Five's

executeQuery()

function.

Chaining Events for an Action Button

This documentation will demonstrate how you can chain the On Press, Do Press, and On Complete events together for an action button. The following will be added in Five to demonstarte chaining events for a button:

• Button Demo application
• Message Email mail merge
• Send Message process with an action button
• ValidateData function for the On Press event
• SendEmailServer function for the Do Press event
• EmailCompleted function for the On Complete event
• Send Message menu item for the process

Notes

If you want the Button Demo application as a reference, click to download the FDF file ButtonDemo.fdf and you can import this FDF into your Five account.

If you are building the application, you can't have both application ID's called ButtonDemo.

You will need to add your SMTP settings on the instance record for the mail merge to work.

For this example, an action button will be attached to a process. When using an action button on a process and using the Do Press event, variables need to be set for the screen fields for them to be available in the backend.

Add the Button Demo Application

The Button Demo application is used to demonstrate adding an action button to an action and chaining all three events together for the one button. To follow this tutorial, you need to be in the Applications view to begin with.

1. Click the Add Item button.

2. Type Button Demo in the Title field.

Figure 1 - Add Button Demo application

3. Click the Save button in the form app bar.

Figure 2 - Save button

Add the Message Email Mail Merge

info

For your mail merge to work, you will need to set your SMTP settings on your instance record. Please refer to the Add SMTP Settings video in the Introductory Series chapter if you have not setup your SMTP settings before.

The Message Email mail merge will be sent through a function in the backend attached to the Do Press event. Before the mail merge can be sent the data will be validated on the Send Message process through a frontend function attached to the On Press event.

The mail merge has one screen field called Message. This will be passed into the mail merge template as a variable using

{{five.variable.Message}}

and when the data is submitted in the Message screen field on the Send Message process, this message will be passed into the variable in the mail merge template.

1. Click the Manage button.

Figure 3 - Manage button

2. Select Tasks in the menu.

3. Select Mail Merges in the sub-menu.

Figure 4 - Mail Merges menu item

4. Click the Add Item button.

5. Type Message Email in the Title field.

Figure 5 - Add Message Email mail merge

6. Click the Screen Fields tab.

Figure 6 - Screen Fields tab

7. Click the Add Screen Fields button.

Figure 7 - Add Screen Fields button

8. Type Message in the Caption field.

9. Click the lookup icon in the Display Type field and select _Text.

Figure 8 - Add Message field

10. Click the Save button in the form app bar.

Figure 9 - Save button

11. Click the General tab.

Figure 10 - General tab

12. Type Message from Message Centre in the Subject Text field.

13. Click in the Merge Text field to open the editor.

Figure 11 - Merge Text field

14. Type Hi

{{five.variable.SMTPToName}}

in the editor, press Enter/Return.

info

The SMTPToName variable is passed into the email template from the

SendEmailServer()

function that we will be adding later. The SMTPToName property is passed into Five's

executeAction()

function on the

context

parameter in the

SendEmailServer()

function, this then becomes available fo us to use in the email template to select the name of the recipient for the email.

15. Click the lookup icon in the Tags tool and select Message.

Figure 12 - Variables

16. Click the Save button in the editor app bar.

Figure 13 - Save button

17. Click the Save button in the form app bar.

Figure 14 - Save button

Add the Send Message Process

The Send Message process will have three screen fields Name, Email, and Message, these fields will be set as variables in the

ValidateData()

function that we will be adding later. These variables will become global and can then be used in our backend

SendEmailServer()

function.

1. Select Tasks in the menu.

2. Select Processes in the sub-menu.

Figure 15 - Processes menu item

3. Click the Add Item button.

4. Type Send Message in the Title field.

Figure 16 - Add Send Message process

5. Click the Screen Fields tab.

Figure 17 - Screen Fields tab

6. Click the Add Screen Fields button.

Figure 18 - Add Screen Fields button

7. Type Name in the Caption field.

8. Click the lookup icon in the Display Type field and select _Text.

Figure 19 - Add Name field

9. Click the Save button in the form app bar.

Figure 20 - Save button

10. Click the Add Screen Fields button.

Figure 21 - Add Screen Fields button

11. Type Email in the Caption field.

12. Click the lookup icon in the Display Type field and select _Email.

Figure 22 - Add Email field

13. Click the Save button in the form app bar.

Figure 23 - Save button

14. Click the Add Screen Fields button.

Figure 24 - Add Screen Fields button

15. Type Message in the Caption field.

16. Click the lookup icon in the Display Type field and select _Memo.

Figure 25 - Add Message field

17. Click the Save button in the form app bar.

Figure 26 - Save button

18. Click the Save button in the form app bar above the list.

Figure 27 - Save button

Add The ValidateData Function

The

ValidateData()

function will be attached to the On Press event, this is the first event that gets executed when chaining all three action button events together.

The

ValidateData()

function ensures the Name, Email, and Message screen fields on the Send Message process have valid data with

{{five.field.fieldID}}

. If the data is not valid when the Send action button is clicked, each field will show their respective message and the Do Press event won't be called as the

ValidateData()

function will create an error with Five's

createError()

function.

The Name, Email, and Message screen fields are set as variables with Five's

setVariable()

function. This makes the variables global enabling the backend

SendEmailServer()

function to have access them.

1. Select Logic in the menu.

2. Select Functions in the sub-menu.

Figure 28 - Functions menu item

3. Click the Add Item button.

4. Type ValidateData in the Function ID field.

5. Click in the Code field to open the Code Editor.

Figure 29 - Add ValidateData function

6. Copy and paste the code block below into the editor.

note

The code block needs to be pasted over the template that Five creates in the editor.

Validate the data in the screen fields

function ValidateData(five, context, result) {
    if (five.field.Name === '') {
        five.showMessage('Please enter the name for the recipient');
        return five.createError('Invalid Name');
    }

    if (five.field.Email === '') {
        five.showMessage('Please enter an email address to send the message too');
        return five.createError('Invalid Email');
    }

    if (five.field.Message === '') {
        five.showMessage('Please enter a message to send to : ' + five.field.Email);
        return five.createError('Invalid Message');
    }

    five.setVariable('name', five.field.Name);
    five.setVariable('email', five.field.Email);
    five.setVariable('message', five.field.Message);

    return five.success(result);
}

7. Click the Save button in the Code Editor app bar.

Figure 30 - Save button

8. Click the Save button in the form app bar.

Figure 31 - Save button

Add the SendEmailServer Function

The

SendEmailServer()

function will be attached to the Do Press event, this is the second event that gets executed when chaining all three action button events together, however, it won't be called if the On Press event creates an error.

If all the data is valid in the Name, Email, and Message screen fields on the Send Message process, when the Send button is clicked, the Do Press event will execute after the On Press event and send the Message Email mail merge using Five's

executeAction()

function. The MessageEmail action ID is passed in as the first parameter, and the mail merge properties and variables are passed in on the context parameter.

1. Click the Add Item button .

2. Type SendEmailServer in the Function ID field.

3. Click in the Code field to open the Code Editor.

Figure 32 - Add SendEmailServer function

4. Copy and paste the code block below into the editor.

note

The code block needs to be pasted over the template that Five creates in the editor.

Executing the MessageEmail mail merge

function SendEmailServer(five, context, result)  {
	result = five.executeAction('MessageEmail', {SMTPToEmail: five.variable.email, SMTPToName: five.variable.name, Message: five.variable.message});
    if (!result.isOk()) {
		return result;
	}

    return five.success(result);
}

5. Click the Save button in the Code Editor app bar.

Figure 33 - Save button

6. Click the Save button in the form app bar.

Figure 34 - Save button

Add the EmailCompleted Function

The

EmailCompleted()

function will be attached to the On Complete event, this is the third event that gets executed when chaining all three action button events together.

If the Do Press event is executed successfully when the Send button is clicked, the On Complete event will execute after the Do Press event and show the message passed into Five's

showMessage()

function.

1. Click the Add Item button.

2. Type EmailCompleted in the Function ID field.

3. Click in the Code field to open the Code Editor.

Figure 35 - AddEmailCompleted function

4. Copy and paste the code block below into the editor.

note

The code block needs to be pasted over the template that Five creates in the editor.

Shows message on success of all three events on the action button

function EmailCompleted(five, context, result) {
    five.showMessage('Email has been sent');
    return five.success(result);
}

5. Click the Save button in the Code Editor app bar.

Figure 36 - Save button

6. Click the Save button in the form app bar.

Figure 37 - Save button

Add the Send Action Button

The Send action button will be attached to the Send Message process. All three functions will be attached to the event fields for the action button. When the button is clicked, the events will consecutively execute on success of the previous event.

1. Select Tasks in the menu.

2. Select Processes in the sub-menu.

Figure 38 - Processes menu item

3. Select the Send Message process record in the list.

4. Click the Action Buttons tab.

Figure 39 - Action Buttons tab

5. Click the Add Action Buttons button.

Figure 40 - Add Action Buttons button

6. Type Send in the Caption field.

7. Click the Events tab.

Figure 41 - Events tab

8. Click the lookup icon in the On Press field and select ValidateData.

9. Click the lookup icon in the Do Press field and select SendEmailServer.

10. Click the lookup icon in the On Complete field and select EmailCompleted.

Figure 42 - Add events

11. Click the Save button in the form app bar.

Figure 43 - Save button

12. Click the Save button in the form app bar above the list.

Figure 44 - Save button

Add the Send Message Menu Item

The Send Message menu needs to reference the SendMessage (Process) action to be available in the Button Demo application.

1. Select Visual in the menu.

2. Select Menus in the sub-menu.

Figure 45 - Menus menu item

3. Click the Add Item button.

4. Type Send Message in the Caption field.

5. Click the lookup icon in the Action field and select SendMessage (Process).

Figure 46 - Add Send Message menu

6. Click the Save button in the form app bar.

Figure 47 - Save button

Button Demo Application

In the Button Demo application, when the correct data is entered into the Name, Email, and Message fields, the On Press event will execute successfully when the Send button is clicked. If the data is invalid, an error would be created and the Do Press event will not be called.

Figure 48 - Send Message process

After the On Press event has executed successfully, the Do Press event will execute and send the email to the recipient.

Figure 49 - Message Email mail merge

After the Do Press event has executed successfully, the On Complete will execute and display a message in the UI.

Figure 50 - UI message