Introduction to Custom Actions

Introduction

This tutorial will show you how to create some relatively simple custom actions to try a test application.  Custom Actions can be used to drive business rules and workflow in your app, such as showing different pages/sections based on information passed to the Action (or retrieved by the Action).

The ‘Hello World’ examples test that you can get a custom action to display in your application and the Currency Converter and World Clock are examples of more sophisticated actions.

Prerequisites

Before starting to use JavaScript code in your application, you need to install Umajin App Creator and it may be helpful to set up a JavaScript code environment as well.  Try the Visual Studio Code Setup tutorial which will help you to install a code environment and add a JavaScript debugger for when your code doesn’t work.

Hello World 1

All this Action does is display a ‘hello world’ message when it’s called. It doesn’t have any parameters the user can specify.  To try out the Action, do the following:

  1. Open your code environment.  This is easy if you have set up Visual Studio Code.

    • Open the app project you want to add JavaScript in to.  You could create a new project for this tutorial and call it something like ‘Hello World App’.
    • Go to the File menu in Umajin App Creator.
    • Click the “Open with Visual Studio Code” menu item.  This loads up and opens the Visual Studio Code environment, points it at the /scripts directory in your project’s Resources Folder and adds all the configuration files needed for you to use JavaScript in your app.
  2. Create a new File, it doesn’t matter what you call this file as long as the extension is ‘.js’.  E.g. ‘helloworld.js’
  3. Copy the code below into the text area when the file opens.
  4. Save the file.
  5. Go back to Umajin App Creator and click on a Page then go to the Actions panel (the tab next to the Properties in the Properties Inspector) for the Page.
  6. Select the ‘On Press’ event and then the Add Action button (the plus icon to the left of On Press) to bring up the “Actions Selector”
  7. Click ‘Custom’ category.  If this ‘Custom’ category is not available, it means that Umajin App Creator has not found your code file.  This could be because it wasn’t saved in the right place (it should be in the ‘scripts’ sub-directory of the Resources Folder) or the file doesn’t have the .js extension.  It could also mean that Umajin App Creator has had an issue and needs to Reload the project, so you could try saving the project and then choosing Reload from the File menu.
  8. In the Custom Actions category, you should see the Action called “Hello World 1”.  Insert this action into the On Press’ event of the page.
  9. Now run your project in Umajin App Creator and go to the page where you added the On Press action.  Click the page (not a component on the page).
  10. If the Script Console is not visible, then you will need to click the icon for it at bottom right of the Run bar (it should have a little blue dot on it indicating that something new has been written to the Script Console output).
  11. You should see the text ‘hello world’ text in the Script Console window next to the current system time.

You have now created your first custom Action in Umajin App Creator. Use the same procedure to create all your Actions.  Now you can either try your own custom Action or proceed to the next example in this tutorial to learn how to add parameters to your Actions.

Hello World 2

This custom Action will take two parameters and do a calculation, then display the results in the Script Console (similar to the first example). The first parameter is a string labeled ‘caption’ with a default value of ‘default’. The second parameter is an integer labeled ‘value’.  This integer is displayed to the consumer of the Action as a range with a minimum value of 0 and a maximum of 100. The default for the integer is 10.  If all the defaults are used in the Action, then the Action output will be ‘caption = default AND value * 10 = 100‘ when it is run.

Try creating a new JavaScript file with the following code.

Use the same procedure as the ‘Hello World 1’ example above and remember to add the custom Action to a Component’s event in your application in Umajin App Creator as well.

Note the types of parameters you can pass to the registerAction are;

  • bool:label[:default_value] – the label describes the parameter for the user. Examples of this parameter type are “bool:Expand” and “bool:With particles:yes”. The default_value can be ‘true’, ‘false’, ‘on’, ‘off’, ‘yes’ or ‘no’.
  • string:label[:default_value] – the label describes the string parameter expected for the user when the Action is displayed.  This should be a descriptive name for the parameter.  The default_value can be any string value.
  • int:label[:default_value]:min:max – the label describes the integer parameter for the consumer of the custom Action. The default can be any integer value between the min and max numeric values.
  • real:label[:default_value]:min:max – the label describes the real parameter for the consumer of the custom Action. The default can be any real value between the min and max numeric values.
  • component:label:type – the label describes the component use within the custom Action.  The type of component is required to limit the components displayed in the list to those that are required/supported in the Action.

Hello World 3

This example uses a component parameter and updates properties on the component that is passed to it. This is a very common practice for actions.  In this case, will create some code to change the text on a button and make it bounce!

Again, use the same procedure as the Hello World 1 example above to add the code to your project.  This time you will need to add a Button Component to your page so that the Action can manipulate it.

Note: the getProperty, setProperty and setPropertyIn method are described in more detail in the Using getProperty and setProperty to enable Custom Components tutorial.

Another Example

The following is a quick example of custom Actions which is a little more sophisticated in its function.  It follows the same basic procedure which you will be a little more familiar with by now.  If you want more information about custom Actions, check out our example section; like Creating new Actions with registerAction and Accessing Global Variables From Actions.

World Clock Example

This example Action allows you to turn any Text Component into a digital world clock. You can specify the offset from UTC which you can find on wikipedia.