An Intro to Enyo (Part 1): Components

When HP announced that WebOS was to be open sourced, one of the first components to be released was Enyo, the JavaScript-based application development framework for webOS. The first version was designed with webOS in mind, and as such would work only on that OS. However, for the second major release of Enyo (2.0), the goal was to have a framework that works across browsers.

Even so, the framework is optimised and built with mobile in mind. It can be easily combined with something like PhoneGap to create a powerful mobile app that can be distributed via app stores. It is possible to create desktop applications with it, however the default widget set that comes with is definitely better suited for mobile and touch applications.

Enyo is a JavaScript framework, and as such it is possible to create an entire application in Enyo without touching either HTML or CSS code. It is object-oriented and uses object-oriented concepts such as encapsulation to make it easy to create reusable code. The basic unit of an Enyo application is a component, and these components can combines and wired together in different ways to create an application.

Components can also be combined together to create more complex components. As a simple example, one may combine a text area, a submit button and a clear button into a search component. Or, one could combine a canvas, and a collection of buttons and panels into an image editor component. These can then be reused across multiple applications or within the same application.

A sample of Enyo

As we said before, the basic building blocks of Enyo applications are components. We talked about a search component before, one that has a text input and two buttons—for search and clearing the input text—so let’s build that.

 1 new enyo.Control({
 2   components: [
 3     {tag: "input"},
 4     {tag: "button", content: "Search"},
 5     {tag: "button", content: "Clear"}
 6   ]
 7 }).write();

This is great, but not very reusable. To make it reusable we make it into an Enyo “kind”. Here is what that would look like:

 1 enyo.kind({
 2   name: "SearchComponent",
 3   kind: enyo.Control,
 4   components: [
 5     {tag: "input"},
 6     {tag: "button", content: "Search"},
 7     {tag: "button", content: "Clear"}
 8   ]
 9 });
10 
11 new SearchComponent().write();

When you run this, you will see that it has the same results as before. However, this time we can simply place new SearchComponent().write(); wherever we want the component to show up.

To actually use this in an application though, we should first go over how to set up an Enyo application.

Beginning with Enyo

Before we begin using Enyo, we need to download it and set up a boilerplate document. You can download Enyo from the Enyo website. The download page has a several options, and if you have Git installed and set up on your computer, you should use the first method. It includes Enyo and a basic Enyo-based application that you can start working on immediately.

Otherwise if you download from the second link “Downoad Latest Release”, you will find the same basic bootplate in a subdirectory of the Enyo code.

Now open the index.html file in this directory. You will notice that nothing happens. Don’t worry, it will work when you have run the deployment script on it. For now you can test with debug.html. This should show “Hello World” on screen.

All the work you do will be in the source directory in the bootplate folder. It should contain three files, App.css, App.js, and package.js. Enyo enables you to split your code in multiple files, the package.js file in fact lists the dependencies that you project has. For now let’s leave it alone.

While your Enyo project can be modular, with dependencies on other submodules or plug-ins, it does not need to be deployed this way. It includes two scripts, deploy and minify, which are useful for deployment. On Windows you can run the deploy.bat file from the command line, and it will combine all your JavaScript resources into a single .js file and similarly all your CSS code into a single CSS file. After you run the deploy command, the index.html file will start working.

For our purposes, the App.js file is enough. Open it, and we’ll begin hacking away at it.

Components

Let’s go back to our component example. We would like to use this in our application; so open the App.js file, and replace it with the following:

 1 enyo.kind({
 2     name: "SearchComponent",
 3     kind: enyo.Control,
 4     components: [
 5         {tag: "input"},
 6         {tag: "button", content: "Search"},
 7         {tag: "button", content: "Clear"}
 8     ]
 9 });
10 
11 enyo.kind({
12     name: "App",
13     fit: true,
14     components: [
15         {kind: "SearchComponent"}
16     ]
17 });

Now if you open the debug.html file in the browser, and you will notice that you now have a text input area, a button labelled “Search” and a button labelled “Clear”. How did this happen?

First of all, we haven’t touched the debug.html file, however it includes the basic JavaScript code that will run our application as long as it is called App. So here we have created a new component called App, which itself simply includes the SearchComponent we already built. The fit: true bit ensures the the app fits the entire page.

Now, let’s make this example more involved. We will add an option to this component which will allow to specify whether the “Clear” button should be shown or not.

First we need to add the option in a way that it can be changed while creating the component. Enyo provides a shortcut for this. Any properties that you want people to have the ability to change can be places in a block called published.

Here is how we would add a property for showing the clear button:

 1 enyo.kind({
 2     name: "SearchComponent",
 3     kind: enyo.Control,
 4     published: {
 5         showClearButton: true
 6     },
 7     components: [
 8         {tag: "input"},
 9         {tag: "button", content: "Search"}
10     ]
11 });

We also removed the clear button from the components block since we want it to be shown only if the users specifies it should. We have set the default value of showClearButton as true, so the button will show up by default. Of course we haven’t coded that bit yet, so nothing will happen as of now.

To set this value while creating the component we could do the following:

 1 enyo.kind({
 2     name: "App",
 3     fit: true,
 4     components: [
 5         {kind: "SearchComponent", showClearButton: true}
 6     ]
 7 });

You will notice that we added the showClearButton option here. What we need to do now is to actually have this option do something. Right now the Clear button will not be shown in any case.

For this we need to check the value of shoeClearButton while the component is being created, and add the button based on its value. For this we need to use the create function of the component. Before we go there, let’s take a look at the code that will actually do the work:

 1 if (this.showClearButton) {
 2   this.createComponents(
 3     [
 4       {tag: "button", content: "Clear"}
 5     ],
 6     {owner: this}
 7   );
 8 }

This code is simple enough. We check if showClearButton is true, and if it is, we use the createComponents function to add the clear button to our component. The {owner: this} bit tells Enyo that this component is being added as a child of our main component; this needs to be done if we are adding components dynamically.

Now let’s put this code in context of the entire app:

 1 enyo.kind({
 2   name: "SearchComponent",
 3   kind: enyo.Control,
 4   published: {
 5     showClearButton: true
 6   },
 7   create: function () {
 8     this.inherited(arguments);
 9     if (this.showClearButton) {
10       this.createComponents(
11         [
12           {tag: "button", content: "Clear"}
13         ],
14         {owner: this}
15       );
16     }
17   },
18   components: [
19     {tag: "input"},
20     {tag: "button", content: "Search"}
21   ]
22 });
23 
24 enyo.kind({
25   name: "App",
26   fit: true,
27   components: [
28     {kind: "SearchComponent", showClearButton: true}
29   ]
30 });

If you look now, you will notice that we added a new create function which begins with this.inherited(arguments). Since the create function is being overridden in our component, it still needs to call it’s parent’s—which would be enyo.Control here—create function, Enyo provides a shortcut to do this using that line of code. The rest of the application should feel quite familiar to you since nothing has changed.

However, if you run the application now, it will show the clear button once again. If you now set the showClearButton value to false and refresh the page, the clear button will disappear. We have made this custom control configurable. If we want we can add more options, such as the ability to set the url to post to the search query to—right now it does nothing—or the ability to set a default bit of text to show in the search box, or even the ability to remove the search button.

You can imagine how this would be useful for creating reusable complex components, in fact Enyo comes with many of them. The Enyo layout packages, and the onyx widget set are all build on a similar base and can be used to rapidly build an application.

In the next part, we will continue with more about components, and then move on to the components that come with Enyo..