Guide to Actions

Less than 10 minutes to read

Actions are reusable chunks of code that provide a way to encapsulate and reuse sets of instructions or tasks within your screen. They serve as the equivalent of functions and allow you to define a sequence of operations that can be invoked from various events or components in your screen. This guide will provide an overview of what actions are, how they are used, their use cases, and introduce additional useful concepts related to actions.

What are Actions?

Actions are similar to functions in traditional programming languages. They provide a way to define a sequence of operations or tasks that can be executed when triggered by an event, such as a button click, screen submission, or page load. Instead of writing the same set of operations multiple times, you can define an action and reuse it in different parts of the screen.

Reusability: Actions are meant to be reusable. If you have multiple buttons or components that need to perform the same set of tasks, you can assign the same action to their respective events, ensuring consistent behaviour and reducing code duplication.
Encapsulation: Actions allow you to encapsulate a sequence of operations into a single named entity. This makes your code more organized, modular, and easier to understand. By defining actions for specific tasks, you can abstract away complex logic and improve code readability.

Actions can be used in various scenarios within the screen. They can be assigned to event handlers, such as onClick events, to define the behaviour when an element is interacted with. Actions can also be used in the onSubmit, onLoad, and onClear events to perform initialization tasks or set initial values for components.

Use Cases for Actions

Actions can be applied to various scenarios within your screen. Here are some common use cases:

Button Clicks: Actions can be assigned to button onClick events, allowing you to define the tasks to be executed when the button is clicked. This ensures consistent behaviour across multiple buttons that perform the same action.
UI Extensions: In cases where you need to add or modify components dynamically, actions can be used to load or display specific components within a page. By defining a pageExtension/componentExtension action, you can control when and where a component appears, providing a customized user experience.
Error Handling: Actions can be used to handle errors and exceptions that may occur during screen execution. By using the tryCatch block, you can define actions to be performed in case of an error, such as displaying error messages or performing fallback actions.
Flow Control: Actions support if/then/else statements for flow control within your screen. This allows you to conditionally execute specific actions or change the behaviour of your screen based on certain conditions.

Actions, Functions, and Operators

Actions provide a powerful way to encapsulate and reuse sets of instructions or tasks within your screen. In addition to actions, there are two important concepts related to actions: functions and operators. This section will explain what you can do within an action, introduce the available string functions, and discuss the supported operators for conditional evaluations.

Within an action, you can define a sequence of operations to be performed. Let’s explore some key aspects of using actions:

Set Properties or State: Actions can involve setting properties or state values. You can use the “set” keyword to modify the properties or state of components in your screen. For example, you can set the value of a property or update the state based on certain conditions.

"actions": {
  "buttonOnClick": [
    {
      "set": {
        "state": {
          "part_number": {
            "string": {
              "value": "ABC123"
            }
          }
        }
      }
    }
  ]
},

Control Components: Actions can be used to load or display components dynamically. By defining a pageExtension/componentExtension action, you can control the appearance and behaviour of specific components within a page.

"actions": {
  "dialogButtonOnClick": [
    {
      "set": {
        "pageExtension": {
          "componentId": "name",
          "panel": "right",
          "uiExtension": "gridDialog"
        }
      }
    },
  ]
}

Handle Errors: Actions support error handling through the tryCatch block. This block allows you to define actions to be performed in case of an error, providing a way to gracefully handle exceptions during screen execution.

The tryCatch block consists of two main sections:
- try: The try section contains the actions that you want to execute. If an error occurs during their execution, the error is caught and handled in the catch section.
- catch: The catch section defines the actions to be performed when an error occurs. This can include displaying error messages, executing fallback actions, or any other necessary error handling logic.

Here’s an example of using try/catch within an action:

"actions": {
  "custPut": [
    {
      "tryCatch": {
        "try": [
          {
            "apiPut": {
              "endpoint": "v1/customers",
              "prefix": "",
              "id": {
                "get": {
                  "state": "account_opened"
                }
              }
            }
          },
          {
            "resetState": {}
          }
        ],
        "catch": [
          {
            "set": {
              "error_message": {
                "title": "Error updating Customer",
                "message": {
                  "get": {
                    "state": "CURRENT_ERROR"
                  }
                }
              }
            }
          }
        ]
      }
    }
  ],
},

By utilising the try/catch block, you can handle errors gracefully and ensure a smooth user experience even in the face of unexpected issues.

Implement Flow Control: Actions allow you to incorporate if/then/else statements for conditional execution. This enables you to control the flow of your screen based on specific conditions.

Operators in Schema are used for conditional evaluations within actions. The supported operators include:

eq (equal): Checks if two values are equal.
lt (less than): Checks if the left value is less than the right value.
gt (greater than): Checks if the left value is greater than the right value.
ge (greater than or equal): Checks if the left value is greater than or equal to the right value.
le (less than or equal): Checks if the left value is less than or equal to the right value.
ne (not equal): Checks if two values are not equal.

These operators can be used in combination with if/then/else statements to conditionally execute actions based on specific criteria.

String Functions: Actions support string functions that allow you to manipulate string values. The supported functions include Slice, Format, and Split. These functions provide ways to modify the format of a string or extract specific parts from it.
- Split: The split function allows you to divide a string into an array of substrings based on a specified delimiter. It takes two parameters: the delimiter and the index of the desired substring.
- Slice: The slice function extracts a portion of a string and returns it as a new string. It takes two parameters: the starting index and the ending index of the desired substring.
- Format: The format function is used to format a string by replacing placeholders with corresponding values. It resembles the String.Format function in C# and allows for dynamic string composition.

      {
        "set": {
          "state": {
            "part_number": {
              "string": {
                "value": "{0}-{1}-{2}",
                "function": {
                  "format": [
                    {
                      "get": {
                        "state": "part1"
                      }
                    },
                    {
                      "get": {
                        "state": "part2"
                      }
                    },
                    {
                      "get": {
                        "state": "part3"
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }

These string functions can be utilized within actions to manipulate string values according to your specific requirements.

Actions provide a powerful mechanism for organizing and reusing code within your screen. By encapsulating sets of instructions or tasks, you can enhance code modularity, improve code readability, and ensure consistent behaviour across different components. With the ability to handle errors, implement flow control, and leverage string functions, actions empower you to build dynamic and robust screens.