Getting Started with BajaScript

Configuration

From the website

If you're viewing this content from bajascript.com, then please click on the individual examples available from the Nav Tree. Each example contains some code that can be run in the browser. You can edit each code example and save your own work to a unique URI you can reuse at a later date.

From a local Niagara Installation

  • Ensure you have the BoxService from the box palette added to your Station's Service Container.
  • Open the docDeveloper palette and add the BajaScriptExamples folder to the root of your Station.
  • Make sure you're logged on as a user with admin read, write and invoke privileges.

Hello World

Please note, each example is running in a special JsPlayground Component. This component has specifically been designed for learning about our JavaScript frameworks. The JsPlayground component isn't intended for use in production web applications!

You can run each example by clicking the Run JavaScript command button in Workbench.

Here's the code for the "Getting Started" tutorial....

// Start BajaScript like this. It will automatically connect to the same
// station serving up the HTML file. Ensure that the station has a 
// BoxService installed.
require(['baja!', 'dialogs'], function (baja, dialogs) {
  dialogs.showOk('Hello world!: ' + baja.version);
});

In Niagara 4.0, RequireJS is used to create modular JavaScript and load it into the browser. Click here for more information on using RequireJS.

The above code requires (or imports) the BajaScript namespace so it can be used in a web application. By the time the function is invoked, BajaScript is up and running and connected to the Station. From Niagara 4.0 onwards, a WebSocket is used to connect back to the Station. Also note how we're importing Niagara 4.0's new dialogs library to pop up a dialog box to the user.

Let's improve the above example and do something more interesting. Here's the code from the "Subscription" tutorial. (If you're not viewing this from bajascript.com, please add a Ramp from the kitControl palette to the root of your Station.)

// Subscribe to a Ramp. When it changes, print out the results.
require(['baja!', 'dialogs'], function (baja, dialogs) {
  var sub = new baja.Subscriber();
  dialogs.showOk(function (dlg, jq) {
    jq.text("Loading...");

    function update(ramp) {
      jq.text(ramp.getOutDisplay());
    }

    // Called whenever the Ramp changes.
    sub.attach('changed', function (prop) {
      if (prop.getName() === 'out') { update(this); }
    });

    // Resolve the ORD to the Ramp and update the text.    
    baja.Ord.make('station:|slot:/Ramp').get({ subscriber: sub })
      .then(update);
  })
  .promise()
  .finally(function () {
    // Called when the dialog is closed.
    sub.unsubscribeAll();
    sub.detach();
  });
});

The above example resolves an ORD to a point, shows a dialog and then changes the text of the dialog whenever the Ramp changes. When the dialog is closed, we're no longer interested in the live value so we unsubscribe and do all the necessary clean up.

As you can see from this code example, baja.Ord.get, along with much of BajaScript's public API, now returns a Promise. Code using BajaScript version 1's API based on ok and fail callbacks will still work, but we recommend using Promises for better ease of use.

  • The showOk method is passed a function that's called when the dialog box is about to be shown.
  • The dialog function has two parameters. The first is the dialog instance. The second is a jQuery wrapper around the dialog's content DOM element.
  • The inner text of the dialog's DOM element is updated using jQuery's text method. This prevents XSS attacks.
  • An ORD is used to resolve and subscribe the Ramp Component on the Station. BajaScript creates a proxy version of the Ramp Component in the browser. The proxy version of the Ramp has all of the Slots the Java based version has running on the Station! Because we subscribe it, we'll also receive events for any changed property values.
  • The update method updates the dialog's content. The Ramp's getOutDisplay method is auto-generated by BajaScript based upon the frozen Slots a Ramp has.
  • The listener method attached to the Subscriber is called whenever one of the Ramp's Properties changes. If the Property that changed is the out slot, it will update the dialog with the current display value. In the listener method, the this keyword refers to the proxy Component instance.
  • Once the ORD has been resolved, the update method is also called. This way, we load the dialog with the Ramp's current value, and the subscriber keeps it up to date whenever it changes.
  • When the dialog is closed, the finally method is called.
    • unsubscribeAll stops listening for events from the Ramp.
    • detach detaches all listeners from the Subscriber. This is best practice for avoiding memory leaks.

Proxy Components

In the above example, the Ramp component has many methods available to it. You can find out about most of them here. However for ease of use, there are many auto-generated methods created. For instance, each frozen Property has a getter and setter method (i.e. getOut and setOut) to get and set the Property's value. As well as being able to access a Property's value, we can also access its display String. A display String is created in the Server by calling the toString(Context) method on the given value. This will contain a locally formatted String version of the value that's really useful for updating our HTML. In fact, it's so useful, BajaScript also generates a getter for accessing the display String. In this case, it's called getOutDisplay().

What next?

For more information on how to use BajaScript, please try out the aforementioned examples in the BajaScriptExamples Station folder. Thanks!