An Introduction to jide.js

jide.js is a new toolkit for creating modern web applications. It consists of a collection of useful controls and all the tools you need to create your own, application specific, components. jide.js fully embraces AMD (require.js) to allow you to pick only those parts of it that you truly need. Starting with version 1.0.0-beta3, you’ll also be able to use it with Browserify.

At its core, jide.js is built around observable values, event emitters, and data binding. It utilizes the features of modern browsers (IE9+) to create a solid cross platform experience and to leverage the features of the current JavaScript language instead of clinging to the past.

Introducing the Core Concepts

Before we begin creating an actual jide.js application, let me explain a few of the core concepts.

Observable Values

Observables are a great way to keep various parts of your application in sync. jide.js allows you to subscribe to such observables and receive notifications whenever their values change. An example of this is shown below.

require(['jidejs/base/Observable'], function(Observable) {
  var counter = Observable(0);

  counter.subscribe(function(event) {
    console.log('counter changed', event.value);
  });

  counter.set(1);
  // invokes the subscribed listener and prints to console
});

When creating a jide.js application, you can choose from a number of observables, such as ObservableProperty, Observable.computed, and ObservableList. A computed observable can depend on other observables and is recalculated when one of its dependencies changes. An example which creates a computed observable is shown below.

var counterText = Observable.computed(function() {
  return 'You clicked the button ' + counter.get() + ' times!';
});

If you were to subscribe to counterText, you’d get notified whenever counter changes. One thing to watch out for is that computed observables created in this way are lazy by default. That means that their value is not computed unless required. The event passed to subscribers might not contain a value.

Instantiating Controls

All controls in jide.js have the same constructor signature. They all expect exactly one argument, a configuration object. Continuing from the previous example, here is how you’d create a button whose label is bound to the counterText observable we created before and which increments the counter whenever it is clicked.

var myButton = new Button({
  // bind the "text" property of the button to the "counterText" observable
  text: counterText,
  // we can add event listeners inline
  on: {
    // we use the "action" event instead of the "click" event
    // to support keyboard invocation, etc.
    action: function() {
      // increment the counter
      counter.set(counter.get() + 1);
    }
  }
});

// add the button to the document – you'd rarely do it this way, but it works
document.body.appendChild(myButton.element);

Control, Skin, and Template

jide.js allows you to create your application however you want but the suggested way is to use a clean separation of concerns in your custom controls. That is what we’ll do in our example.

In jide.js, each control should contain the properties it needs to be displayed. For example, a button should have a text and an icon property. On top of this, each control in jide.js has a skin which is responsible for building the internal DOM structure of the control, including event handlers, and injecting data into the DOM.

If you want to get the most out of jide.js, you can leave the DOM creation and data binding between the DOM and the control and its skin to a template. In this case, your skin should only contain event handlers and custom properties that are important to the template. This is the approach we’ll use for the remainder of the introduction.

Creating a jide.js Application

The easiest way to start a new jide.js project is to use the Yeoman generator. Yeoman requires that you have node.js and npm installed on your computer. Once you’ve done that, run the following commands in a terminal window:

npm install –g yeoman
npm install –g generator-jidejs
yo jidejs

Give your application a name you like and say “no” to the event bus. Once Yeoman has finished creating your project, you can take a look at it by typing grunt serve. This will start a server and open your browser so that you can start using your application. Your new application supports live reload, meaning that your browser will automatically refresh when you edit source files.

Now, you should see a very basic application that shows a text field where you can enter your name, and a button. When you click the button, the app will greet you.

Adding a Task list to the app

Next, open the app/page/IndexPage.js file in your project directory and change it to this:

define([
  'jidejs/base/Class',
  'jidejs/base/ObservableList',
  'jidejs/ui/Control',
  'jidejs/ui/Skin',
  'text!app/view/indexPage.html'
], function(
  Class, ObservableList, Control, Skin,
  IndexPageTemplate
) {
  function IndexPage(config) {
    this.tasks = ObservableList(config.tasks || []);
    delete config.tasks;
    Control.call(this, config);
    this.classList.add('page');
    this.classList.add('index');
  }

  Class(IndexPage).extends(Control);

  IndexPage.Skin = Skin.create(Skin, {
    template: IndexPageTemplate,

    addTask: function() {
      this.queryComponent('x-name').then(function(nameField) {
        this.component.tasks.add({
          name: nameField.text
        });

        nameField.text = '';
      }.bind(this));
    },

    deleteTask: function(task) {
      this.component.tasks.remove(task);
    }
  });

  return IndexPage;
});

The changes you just applied are quite simple. You’ve added a new property, tasks, to the IndexPage control. tasks is populated from the configuration parameter. The great thing here is that since you’re using an ObservableList, the UI will update automatically when you add or removing items from the list.

Now, we need to change the app/view/indexPage.html to actually display our task list. Change the content of the file to this:

<template>
  <input type="text" pseudo="x-name" bind="
    is: 'jidejs/ui/control/TextField',
    on: {
      action: addTask.bind($item)
    }
  ">
  <button bind="
    is: 'jidejs/ui/control/Button',
    on: {
      click: addTask.bind($item)
    }
  " text="Add"></button>
  <ul bind="
    foreach: component.tasks
  ">
    <template>
      <li>
        <span bind="text: name"></span>
        <a bind="
          is: 'jidejs/ui/control/Hyperlink',
          text: 'Delete',
          on: {
            action: $parent.deleteTask.bind($parent, $item)
          }
        ">Delete</a>
      </li>
    </template>
  </ul>
</template>

Templates in jide.js allow you to use data binding to upgrade standard HTML elements to jide.js controls. To bind an element, you just need to add a bind attribute to it. The syntax within that attribute is a literal JavaScript object (without opening and closing braces).

By specifying an is binding, we upgrade the element to the named control. It’s value must be the name of a valid AMD module that is a control. We can use an on binding to add event listeners to an HTML element or a jide.js control.

There are a few special variables available within a binding expression. The ones we use here are $item and $parent. For the outer template element, the $item variable refers to the skin of the IndexPage. In the inner template element, $parent refers to the skin, while $item refers to the current task object.

The foreach binding allows us to iterate over a collection of items and duplicates its template child node for each of the items it is iterating over. If the value assigned to it is an ObservableList, it will automatically add, remove, and modify its child nodes based on the changes of the ObservableList.

Conclusion

As you’ve just seen, jide.js offers a lot to developers. By using observable values you can stop writing event listeners and simply bind your data to the UI. Creating custom controls is not only simple, but effectively enforces a clean separation of concerns.

This article only serves as a brief introduction to jide.js. There are lots of other controls built into jide.js that help you create your application, and the presented style is only one way. If you prefer not to use templates at all, that’s fine too. You can, for example, use operations such as filter, map and sort to create live updating variants of your original data.

To learn more about jide.js, please visit the project website where you can find lots of examples, demos, and guides. You are also directed to the project’s GitHub repository.