Umajin LibJS

Return to Umajin Development Center

Welcome to the Umajin LibJS docs.

Umajin LibJS is a JavaScript library that makes it easy to enhance the functionallity of your Umajin app. It is broken into a number of modules, that you can require as needed.

There are many advantages in using LibJS over the original JS Main API. You will get rich IntelliSense if you are using Visual Studio Code, providing much greater discoverability of the API. The use of Enums over magic strings, that are error-prone.

The API has been organised into modules and classes, rather than global functions. Each component has its own class, with properties and methods. Custom actions and feeds are creating using their classes, and VSCode's IntelliSense knows about these types, and will help you along the way.

Getting started

If you have an existing Umajin app, go to File > Open with Visual Studio Code, this will open a VSCode workspace in the correct location, and configure a few things needed to work with LibJS.

Create a new JavaScript file with a ".js" extension in the root of your projects scripts/ folder. Now you can require any LibJS modules, and start using them.

A great way to see how LibJS works is by making a simple custom action. Copy and paste this code into your script:

var uComps = require('u-components');
var uActions = require('u-actions');
var Action = uActions.Action;

new Action('Say hello', sayHello)
    .addStringParameter('Your Name', 'World')
    .addBooleanParameter('Show in popup?', false)
    .addParameter('Text Output', uActions.ParamType.TEXT)
    .register();

function sayHello(yourName, showInPopup, textOutput) {
    var greeting = 'Hello ' + yourName + '!';
    if (showInPopup) {
        uActions.showPopup(greeting);
    } else {
        var textComp = uComps.cast.toText(textOutput);
        textComp.text = greeting;
    }
}

In Umajin editor, create a Button and a Text component on your page. Add an action to the "On Press" event of your new Button. Your new custom action should be called "Say hello". You can search for it using the search box, or look under the "Custom" tab.

Once added, you can type your name into the "Your Name" property of the Action. Then select the Text component you created for the "Text Output" property.

Press play in Umajin Editor to test things out. Then press the button you created. It should display a message for you in the text field. Nice job!

Working with components

In the example action above, you can see that the third parameter is "Text Output", and is a Text Component reference. The component reference is passed to the action callback function as textOutput. Unfortunatly, VSCode is not able to figure out what type textOutput is, which is the reason why we cast it to a Text Component a few lines down.

Once we cast it using the uComps.cast.toText() method from the u-components module, then VSCode can help us with IntelliSense.

For details of each components properties, see the docs for the u-components module.