replaceAction()

Last updated 28/01/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. Optionally, you can pass in a

recordKey

parameter to be on the selected form record on the replaced action.

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()

, several processes were created, we are going to use some of 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 Customer table - The Customer table is added to use as the data source for the Customers form.
• Add the Customers form - The Customers form is added so records can be saved in the Action Navigation app and we can use the optional
  recordKey
  parameter to select a specific form record.
• 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.
• Edit the Process A record - To add an action button and attach the
  ReplaceProcessA()
  function.

Add the Customer Table

The Customer table is added so we can create a Customers form.

1. Select Data in the menu.

2. Select Table Wizard in the sub-menu.

Figure 1 - Table Wizard menu item

3. Type Customer in the Name field.

4. Click the Add Fields button.

Figure 2 - Add the Customer table

5. Type Name in the Name field.

6. Click the Save button in the Table Wizard app bar.

Figure 3 - Save the Customer table

7. Click the Save button in the Table Upgrade window.

Figure 4 - Save button

Add the Customers Form

The Customers form is added so we can add some records to demonstrate later in this tutorial how to pass in the optional

recordKey

for a form.

1. Select Visual in the menu.

2. Select Form Wizard in the sub-menu.

Figure 5 - Form Wizard menu item

3. Click the lookup icon in the Main Data Source field and select Customer.

4. Click the Save button in the Form Wizard app bar.

Figure 6 - Add the Customers form

Add the Replace Demo Dashboard

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

replaceAction()

and

previousAction()

work together. We will use the process actions we already have saved in the Action Navigation application.

1. Select Visual in the menu.

2. Select Dashboards in the sub-menu.

Figure 7 - 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 8 - Add the Replace Demo dashboard

6. Click the Actions tab.

Figure 9 - Actions tab

7. Click the Add Actions button.

Figure 10 - Add Actions button

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

Figure 11 - Edit button

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

Figure 12 - 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 13 - Save button

12. Click the Add Actions button.

Figure 14 - Add Actions button

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

Figure 15 - Edit button

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

Figure 16 - 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 17 - Save button

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

Figure 18 - Save button

tip

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

Figure 19 - Replace Demo menu item

Add the ReplaceProcessA Function

The

ReplaceProcessA()

function will use Five's inbuilt

replaceAction()

function on the

Five

object and pass in the action ID ProcessC to replace Process A with Process C in the dashboard area.

1. Select Logic in the menu.

2. Select Functions in the sub-menu.

Figure 20 - 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 21 - Add ReplaceProcessA function

6. Copy and paste the code block below.

note

The code block needs to be pasted over the boiler template that Five has created by default in the editor.

info

The action ID for Process C needs to be passed into

replaceAction()

to replace Process A with Process C on the dashboard.

Replaces ProcessA with 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 22 - Save button

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

Figure 23 - Save button

Edit Process A

The Process A record already saved in the Action Navigation application, needs to be edited to add an action button. The

ReplaceProcessA()

function will be attached to the On Press event for the button so when the button is clicked, the event will execute the code and replace Process A with Process C.

1. Select Tasks in the menu.

2. Select Processes in the sub-menu.

Figure 24 - Processes menu item

3. Select the Process A record in the list.

4. Click the Action Buttons tab.

Figure 25 - Action Buttons tab

5. Click the Add Action Buttons button.

Figure 26 - Add Action Buttons button

6. Type Replace Process A in the Caption field.

7. Click the Events tab.

Figure 27 - Events tab

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

Figure 28 - On Press field

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

Figure 29 - Save button

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

Figure 30 - Save button

How This Works in an Application

In the Action Navigate application when you select the Replace Demo menu, you will be on the Replace Demo dashboard. On the dashboard are Process A and Process B.

Figure 31 - Replace Demo dashboard

In Process A's app bar is the Replace Process A button. Click this button.

Figure 32 - Replace Process A button

Once the button is clicked, Process A will be replaced with Process C.

Figure 33 - Process C