replaceAction()

Last updated 6/02/2025

The

replaceAction()

function will replace the current action with the chosen action on a dashboard. The action replacing the current action in the dashboard will take the dashboard area that the function is being run from.

When using with

previousAction()

, setting the

revertSelect

parameter to

false

will take you back to the previous action in the dashboard area. Optionally, you can pass in a number of actions you want to go back, in the case of more than one action being replaced.

In the previous chapters,

selectAction()

and

previousAction()

, three processes were created, we are going to use these actions to demonstrate how

replaceAction()

works.

info

The Action Navigation application is created to demonstrate the

replaceAction()

function, the creation of this application is documented in the Introduction chapter so you can perform the tutorial. The

replaceAction()

tutorial follows on from the

selectAction()

and

previousAction()

tutorials.

Multiple actions and functions are used to demonstrate replacing actions on a dashboard.

In this tutorial, the following will be performed to demonstrate how

replaceAction()

and

previousAction()

work together:

• Add the Replace Demo dashboard - To demonstrate how the functions
  replaceAction()
  and
  previousAction()
  work together.
• Add the
  ReplaceProcessA()
  function - When on Process A on the Replace Demo dashboard, will replace Process A with Process C.
• Add the
  PreviousActionWithRevertFalse()
  function - When on Process C on the Replace Demo dashboard, will return you to Process A.
• Edit the Process A record - To add an action button and attach the
  ReplaceProcessA()
  function.
• Edit the Process C record - To add an action button and attach the
  PreviousActionWithRevertFalse()
  function.

Add the Replace Demo Dashboard

The Replace Demo dashboard is added so we can add multiple dashboard areas to demonstrate how the

replaceAction()

and

previousAction()

functions work together. We will use the process actions that are saved in the Action Navigation application from the previous tutorials.

1. Select Visual in the menu.

2. Select Dashboards in the sub-menu.

Figure 1 - Dashboards menu item

3. Click the Add Item button.

4. Type Replace Demo in the Title field.

5. Type 2 in the Columns field.

Figure 2 - Add the Replace Demo dashboard

6. Click the Actions tab.

Figure 3 - Actions tab

7. Click the Add Actions button.

Figure 4 - Add Actions button

8. Click the Edit button in the Page Position field.

Figure 5 - Edit button

9. Select A1 and click the Save button in the grid picker.

Figure 6 - Save A1 position

10. Click the lookup icon in the Action field and select ProcessA (Process).

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

Figure 7 - Save button

12. Click the Add Actions button.

Figure 8 - Add Actions button

13. Click the Edit button in the Page Position field.

Figure 9 - Edit button

14. Select B1 and click the Save button in the grid picker.

Figure 10 - Save B1 position

15. Click the lookup icon in the Action field and select ProcessB (Process).

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

Figure 11 - Save button

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

Figure 12 - Save button

tip

Don't forget to make a menu item for your dashboard!

Figure 13 - Replace Demo menu item

Add the ReplaceProcessA Function

The

ReplaceProcessA()

function will use Five's

replaceAction()

function on the

Five

object and pass in the action ID

ProcessC

. This will replace Process A with Process C in the dashboard area.

1. Select Logic in the menu.

2. Select Functions in the sub-menu.

Figure 14 - Functions menu item

3. Click the Add Item button.

4. Type ReplaceProcessA in the Function ID field.

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

Figure 15 - Add ReplaceProcessA function

6. Copy and paste the code block below.

note

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

Replaces action ID ProcessA with action ID ProcessC

function ReplaceProcessA(five, context, result) {
    five.replaceAction('ProcessC');
    return five.success(result);
}

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

Figure 16 - Save button

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

Figure 17 - Save button

Add the PreviousActionWithRevertFalse Function

The

PreviousActionWithRevertFalse()

function will use Five's

previousAction()

function on the

Five

object to return to the previous action. The

revertSelect

parameter needs to be set to

false

in the

previousAction()

function to return to Process A from Process C while on the Replace Demo dashboard.

1. Click the Add Item button.

2. Type PreviousActionWithRevertFalse in the Function ID field.

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

Figure 18 - Add the PreviousActionWithRevertFalse function

4. Copy and paste the code block below.

note

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

Returns to the previous action on a dashboard

function PreviousActionWithRevertFalse(five, context, result) {
    five.previousAction(false);
    return five.success(result);
}

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

Figure 19 - Save button

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

Figure 20 - Save button

Edit Process A

The Process A record that was added in the previous chapters, needs to be edited to add an action button. The button will have an On Press event and when clicked, the

ReplaceProcessA()

function will execute and replace Process A with Process C.

1. Select Tasks in the menu.

2. Select Processes in the sub-menu.

Figure 21 - Processes menu item

3. Select the Process A record in the list.

4. Click the Action Buttons tab.

Figure 22 - Action Buttons tab

5. Click the Add Action Buttons button.

Figure 23 - Add Action Buttons button

6. Type Replace Process A in the Caption field.

7. Click the Events tab.

Figure 24 - Events tab

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

Figure 25 - On Press field

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

Figure 26 - Save button

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

Figure 27 - Save button

Edit Process C

The Process C record that was added in the previous chapters, needs to be edited to add an action button that will return us to Process A from Process C while on the dashboard. The button will have an On Press event and when clicked, the

PreviousActionWithRevertFalse()

function will execute and return to Process A.

1. Select the Process C record in the list.

2. Click the Action Buttons tab.

Figure 28 - Action Buttons tab

3. Click the Add Action Buttons button.

Figure 29 - Add Action Buttons button

4. Type Previous Action With Revert False in the Caption field.

5. Click the Events tab.

Figure 30 - Events tab

6. Click the lookup icon in the On Press field and select PreviousActionWithRevertFalse.

Figure 31 - On Press field

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

Figure 32 - Save button

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

Figure 33 - Save button

How This Works in an Application

Deploy/run your application and select Replace Demo in the menu, you will be positioned on the Replace Demo dashboard. On the dashboard are Process A and Process B. In Process A's app bar is the Replace Process A button. Click this button.

Figure 34 - Replace Process A button

The event will execute the

ReplaceProcessA()

function and replaces Process A with Process C in the dedicated dashboard area. This is because

ProcessC

is passed into

replaceAction()

In Process C's app bar is the Previous Action With Revert False button. Click this button.

Figure 35 - Previous Action With Revert False button

The event will execute the

PreviousActionWithRevertFalse()

function and returns to Process A. This is because

false

is passed into

previousAction()

.

Figure 36 - Process A