Composition is a powerful feature that lets us focus on breaking down the functionality of our app into discrete pieces and then combine those pieces together into a unified app. We used this feature in Chapter 1 when we built a traffic light out of three individual lights. Each descendant of Component has a components block that takes an array of component definitions.

We are not restricted to composing within new kinds. Many of the components that Enyo supplies were designed as containers for other components. We’ll cover many of the kinds that are designed to hold other components in Chapter 4. Some kinds, such as Button, weren’t intended to contain other components.

Components introduce create() and destroy() methods to asisst with the component’s lifecycle. These functions can be overridden by kinds that derive from Component to provide extra functionality, such as allocating and deallocating resources. We previously used the create() function to initialize published properties on our Light kind. We can use this feature to create a simple heartbeat object:

enyo.kind({
    name: "Heartbeat",
    events: {
        onBeat: ""
    },
    create: function() {
        this.inherited(arguments);
        this.timer = window.setInterval(enyo.bind(this, "beat"), 1000);
    },
    destroy: function() {
        if(this.timer !== undefined) {
            window.clearInterval(this.timer);
        }
        this.inherited(arguments);
    },
    beat: function() {
        this.doBeat({});
    }
});

We used the destroy() function to ensure that we cleaned up the timer we allocated in the create() function. You may also notice that we introduced a new function: enyo.bind(). In all our previous event handlers, Enyo handles making sure the context of the event handlers is set correctly. We’ll need to take care of that ourselves when subscribing directly to non-Enyo events. For more information on binding and why it’s necessary, please see this article on Binding Scope in JavaScript.

Up to this point we’ve always created components when a kind is being instantiated. It is also possible to create and destroy components dynamically. Components have a number of functions for interacting with their owned components. You can use createComponent() to create an individual component or create a number of components at once using createComponents(). A component can be removed from an instance of a component by calling its destroy() method. It is also possible to destroy all owned components by calling destroyComponents(). The following example shows creating a component dynamically:

enyo.kind({
    name: "DynamicSample",
    components: [
        { kind: "Button", content: "Click", ontap: "tapped" }
    ],
    tapped: function(inSender, inEvent) {
        this.createComponent({ content: "A new component" });
        this.render();
        return(true);
    }
});

new DynamicSample().renderInto(document.body);

New controls are not rendered until requested. Call the render() function on a control to ensure that it and its children are rendered to the DOM.

The core visual controls in Enyo are wrappers around the basic elements you can create directly with HTML. Of course, because they’re Enyo controls, they’ll have properties and events defined that make them easy to use within your apps. The core controls include: Button, Checkbox, Image, Input, RichText, Select, and TextArea.

The following code sample creates a simple app with several controls:

enyo.kind({
    name: "ControlSample",
    components: [
        { kind: "Button", content: "Click", ontap: "tapped" },
        { tag: "br"},
        { kind: "Checkbox", checked: true, onchange: "changed" },
        { tag: "br"},
        { kind: "Input", placeholder: "Enter something", onchange: "changed" },
        { tag: "br"},
        { kind: "RichText", value: "<i>Italics</i>", onchange: "changed" }
    ],
    tapped: function(inSender, inEvent) {
        // React to taps
    },
    changed: function(inSender, inEvent) {
        // React to changes
    }
});

new ControlSample().renderInto(document.body);

You will note that the controls themselves are unstyled, appearing with the browser’s default style. We’ll see how the Onyx versions of these controls compare next. You may also note that some controls use the content property to set the content of the control. The exceptions to this rule are the text field controls: Input, TextArea, and RichText. These controls use the value property to get and set the text content.

The Onyx library (an optional piece of Enyo) includes professionally designed widgets. These controls expand upon the basic set available in the Enyo core. The Onyx controls that correspond to the core controls use the same interface as those core controls:

enyo.kind({
    name: "ControlSample",
    components: [
        { kind: "onyx.Button", content: "Click", ontap: "tapped" },
        { tag: "br"},
        { kind: "onyx.Checkbox", checked: true, onchange: "changed" },
        { tag: "br"},
        { kind: "onyx.InputDecorator", components: [
            { kind: "onyx.Input", placeholder: "Enter something",
              onchange: "changed" }
        ]},
        { tag: "br"},
        { kind: "onyx.InputDecorator", components: [
            { kind: "onyx.RichText", value: "<i>Italics</i>",
              onchange: "changed" }
        ]}
    ],
    tapped: function(inSender, inEvent) {
        // React to taps
    },
    changed: function(inSender, inEvent) {
        // React to changes
    }
});

As you can see, the Onyx widgets are much more pleasing to look at. With Onyx, we wrapped the text input controls in an InputDecorator. This is a control that allows for additional styling and should be used for all Onyx input controls.

The Onyx library also provides a number of new controls, including Drawer, ProgressBar, TabPanel, and TimePicker, among others. Here’s a sample of some of the new Onyx controls that show off their important properties and events:

enyo.kind({
    name: "OnyxSample",
    components: [
        { kind: "onyx.Toolbar", components: [
            { content: "Toolbar" },
            { kind: "onyx.Button", content: "Toolbar Button" }
        ]},
        { content: "Radio Group" },
        { kind: "onyx.RadioGroup", onActivate: "activated", components: [
            { content: "One", active: true },
            { content: "Two" },
            { content: "Three" }
        ]},
        { content: "Groupbox" },
        { kind: "onyx.Groupbox", components: [
            { kind: "onyx.GroupboxHeader", content: "Groupbox Header" },
            { content: "Groupbox item" }
        ]},
        { content: "ProgressBar" },
        { kind: "onyx.ProgressBar", progress: 25 }
    ],
    activated: function(inSender, inEvent) {
        // React to radio button activation change
    }
});

new OnyxSample().renderInto(document.body);

Controls have a number of methods and properties that focus on their special role of interacting with the DOM. These methods include rendered(), hasNode(), and a number of methods for manipulating the DOM.

The first, rendered(), is a method that can be overridden to perform processing that only takes place when the DOM node associated with the control is available. By default, controls are not rendered into the DOM until they are required. In our samples, we have used the renderInto function to tell Enyo to create the nodes associated with the kinds in our examples. As always, be sure to call the inherited() function within rendered().

The second important method is hasNode(). This function allows us to test whether the DOM node for the control exists and to retrieve it, if available. hasNode() will return null if no node is available. This function is most useful when you are creating new controls that will need to manipulate the DOM or for when you want to wrap a widget from another UI library.

The following example shows a naive way to implement a scalable vector graphic (SVG) container object. The only purpose is to show off the rendered() and hasNode() functions:

enyo.kind({
    name: "Svg",
    published: {
        svg: ""
    },
    rendered: function() {
        this.inherited(arguments);
        this.svgChanged();
        // Can only call when we have a node
    },
    svgChanged: function() {
        var node = this.hasNode();
        if(node !== null) {
            node.innerHTML = '<embed src="' + this.svg + '"
                type="image/svg+xml" />';
        }
    }
});

new Svg({
    svg: "http://upload.wikimedia.org/wikipedia/commons/8/84/Example.svg"
}).renderInto(document.body);