Introduction to Custom Components

Introduction

In this tutorial, we will be discussing the ability to create Custom Components in Umajin App Creator.  These components are able to be consumed by other developers and designers in other apps, as well as being available in your own app projects.

Custom Components are usually created using a group of the internal Umajin App Creator components, so knowing what these are is an advantage.

Prerequisites

The following tutorials are recommended:

  • Installing Umajin App Creator and the sections on our help website associated with components – Custom components are usually constructed from internal Umajin App Creator components so knowing what these are is a real advantage.
  • Visual Studio Code Setup – This is a good code editor available on Windows/Mac and it has a debugging extension that works well with the Umajin App Creator JavaScript system.
  • Introduction to Custom Actions – This tutorial gives an insight into how to work with JavaScript and procedures for developing in Umajin App Creator which will not be rehashed in this tutorial. It will be assumed that you know how to create, write, run and debug JavaScript code within the Umajin App Creator ecosystem.

Registering a Custom Component

To create a Custom Component, it must be registered in the same way as an Action is.  The Custom Component registration call is:

The 9 parameters to the registerComponent call are;

Parameter Description Type
name A unique name for the component which should not have spaces or special characters.  String
icon The relative path to the icon file from the root of the app’s project folder. This is the icon that is used when displaying the component in the Umajin Editors Component Selector window.  Forward slashes are used in the path even on windows systems so “/images/presets/umajin.png” will show the Umajin logo (from the Images > Presets folder) in the component selector.  String
title This is the human readable version of the name which is shown to the user in the Umajin Editor component selector and anywhere the component is described such as in the right hand Help panel of the Umajin Editor component selector window when the user highlights a component to add to the project. String
description A text description of the component that gets displayed in the right hand Help panel of the Umajin Editor component selector window when the user highlights a component to add to the project.  Note: simple HTML tags such as <br>, <p>, <b> and <i> can be used in the description text for formatting purposes. String
callback_initialize The name of a correctly formatted JavaScript function that gets called only when the component is first initialized. The function gets called with two parameters (width, height). Width is the width of the component in local coordinate space. Height is the height of the component in local coordinate space. String
callback_resize The name of a correctly formatted JavaScript function that gets called when the component is resized by the user in the editor, or triggered at run-time. The function gets called with two parameters (width, height). Width is the width of the component in local coordinate space. Height is the height of the component in local coordinate space. String
callback_refresh The name of a correctly formatted JavaScript function that gets called when the component is refreshed by changing a property in the property panel. The function gets called with two parameters (width, height). Width is the width of the component in local coordinate space. Height is the height of the component in local coordinate space. String
property_list This is a list of comma separated properties. The types of properties you can use are:

bool:title[:default_value]
string:title[:default_value]
imagepicker:filename:default
animationpicker:filename:default
videopicker:filename:default
color:name:0x3345543
real:title[:default_value]:min_value:max_value
int:title[:default_value]:min_value:max_value
enum:title:default:v0|v1|v2|v3|v4
String
event_list A comma separated list of event names that get called when the matching raiseEvent is fired from within the component’s code. The event_list names must match the names of the events that are fired. Umajin editor users can then attach Actions to these events from within the editor. String

Example of a simple Custom Component

This example registers the component with an internal name (within JavaScript) of ‘helloWorldComponent‘. It uses the default icon for a custom component and has a readable name of ‘Hello World Component’ so users see the component name with formatting such as spaces between words that are not allowed in object/function names in JavaScript.

Note: the description can have simple HTML style formatting tags added to allow you to highlight words or correctly space information as you desire.

This shows how we can createComponent during the init callback. In this case a rectangle and then a text component on top. Then you can see how using getData we can retrieve properties out of the object which we have provided to the designer to alter, in this case the mycaption and mycolor properties. Finally we can respond to the refresh callback so that the components can be retrieved and updated to the new property values the user has set.

To add the ‘Hello World’ example component to a project, we will assume that you are starting from scratch.  Note: if you have already completed the Custom Actions tutorial then you could open the Hello World app you created, use the menu in Umajin App Creator to open VS Code to the right project and skip to Step 3.

  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 (use File -> Save or the CTRL + S shortcut keys).
  5. Go back to Umajin App Creator and click on a Page (or create a new page).
  6. On the page, open the component picker and click the Custom category.  The ‘Hello World Component’ should be shown in the selector.
  7. Click once on the component to display the Help description in the right-hand help panel.
  8. Insert the component on the page and you should see a component very similar to the one below.