Creating new Actions with registerAction

Overview

The registerAction API allows you to create your own Custom Actions for use with Components. In this guide, we will walk you through the process while also demonstrating how to create an Image Swap Action. Custom Actions can be added to apps using the visual editor, and they expose properties that can be set without coding. These Actions can be attached to Components such as Buttons and Images.

Prerequisites

  1. Umajin App Creator downloaded and installed.
  2. Any text editor.

Pro Tip: using Visual Studio Code as your editor will allow you to integrate debugging.

Instructions

Step 1) Create a new blank app in the Umajin App Creator to use as a testing platform for our new Action Component. Call your new app something that means something relevant to you, such as ‘Actions Tutorial’.

Step 2a) If you use Visual Studio Code, go to File -> Open with Visual Studio Code. Create a new JavaScript file called ‘imageSwap.js’ in the Explorer side-bar, this will then be automatically opened as a new editor window.

OR

Step 2b) If you are using another text editor then go to File -> Open Resources Folder.  Click on the scripts folder in the explorer window. Right-click/create a new file called ‘imageSwap.js’. Now open this new file in your favorite text editor. 

Step 3) Now we need to register our JavaScript Action. A JavaScript Action is a fragment of JavaScript code that is run when an event is triggered in an app.  This can be achieved by using a call to the built-in registerAction statement. The first parameter will contain the name of the function that will be called when the Action triggers. Our function will be called “swapImage”, and we will write the function in a few moments. The second parameter will hold the name of the Image that will be used as an icon (if a specific one is not added then the default is used). We will leave it blank for now. The following parameter contains the desired name of your Action that appears when you add the Action in Umajin. The final parameter is a list of Components that you wish the user of your Action to configure when they use the Action. For our purposes, we will be using two Image Components, named image1 and image2; these will be swapped in our function. In this list, you can also use strings, integers, and booleans.

Further details about Action parameters are below:

Name Type Description
name string The JavaScript function to call with the parameters defined by the ‘params‘ string (defined below). These MUST adhere to JavaScript naming conventions.
icon string This is the path to a custom icon. This parameter is not currently implemented in this version so can be left blank by typing “” and the default script icon will be used.
title string This is a ‘friendly’ name for the Action – used within the editor. This is what gets presented to the user in the actions selector.
params string A string that defines the parameters that get passed to the ‘name‘ function. Currently five types of parameters are supported: bool (checkbox), string (textbox), int (range-bound integer slider), real (range-bound floating point slider), and component (can reference any component accessible within the Umajin editor). The parameters are built up as a comma separated string. Each of the types of parameters above need different information which are separated by colons. Parts in square brackets can be omitted.

  • bool:label[:default_value] – the label describes the parameter for the user. Examples: “bool:Expand” or “bool:With particles:yes”. default_value can be: true/false, on/off, yes/no
  • string:label[:default_value] – the label describes the parameter for the user
  • int:label[:default_value]:min:max – after the label, the default, min and max numeric values
  • real:label[:default_value]:min:max – after the label, the default, min and max real values
  • component:label:type – after the label the (optional) type of the component. All component types (including custom) are supported.

Step 4) Now the function that is called to complete the Action can be written. This is where you can get creative, so we can walk through the simple swapImage function. This function takes in our two Image Components as parameters, and holds the current image filenames as local variables. Using these variables, we set the properties of the images to the respective, opposite, file variable.

Step 5) Now the Umajin app can be setup for testing of your new Action. The example’s goal is to swap two images with the push of a button; therefore two Image Components and a Button Component have been added to the app screen.  

Our example of the placement of the 2 images and button is shown below:

Step 6) We need to Add an Action to the button now, so click the Button Component, and go to the Action tab.  On a Button Component we have three possible events that can trigger an Action: ‘On Press’, ‘On Down’, or ‘On Up’. For this example we are going to use the ‘On Press’ event so click the ‘(+)’ button to the right of ‘On Press’.

Step 7) The Action Selector will now pop up. Go to the Custom tab, and select your new Action called “Image Swap” to add it to the ‘On Press’ event of the Button.

Step 8) The Image Swap Action will now be displayed under the ‘On Press’ heading.  You can pick the 2 images that will swap, from the drop-down component picker which should only be showing images.  You will remember that we set up the ‘swapImage’ function by defining the image component type that should be used in the picker in the param list – “component:image1:image,component:image2:image”.

Step 9) Now you can test out the Action by clicking the Button to see the images swap.