Echo Web Framework

As previously discussed in the Component Properties documentation, Echo has several inherent property types for colors, borders, images, and measurements. The framework provides tools to aid in rendering these properties from their component-based representations to CSS styles in DOM elements.

The framework provides numerous tools in the Echo.Sync namespace for rendering properties to the DOM (see table below). Properties should always be rendered using this API when it is applicable.

Pixels Only, Please

While Echo3 supports setting dimensions in all the units provided by CSS (pixels, centimeters, millimeters, inches, picas, points, "ex"es, and "em"s), all CSS rendering should be done in pixels when possible. The Core.Web.Measure API provides capabilities to convert all such units into pixels. See the Core JavaScript Framework's Measuring Tools Documentation for more information.

Percentile units should generally be converted to pixels when possible. This can be accomplished when the container size is known and will not change, or by using renderDisplay() to detect changes and redraw appropriately as required (renderDisplay() is covered later).

An Example

As an example of using the property rendering methods, we'll add the capability to render colors, fonts, and a background image to the SpinButton example component. Only the renderAdd() implementation will need to be modified. Changes are shown below in bold:

    renderAdd: function(update, parentElement) {
        this._div = document.createElement("div");
        this._div.id = this.component.renderId;
    
        this._decSpan = document.createElement("span");
        this._decSpan.style.cursor = "pointer";
        this._decSpan.appendChild(document.createTextNode("<"));
        this._div.appendChild(this._decSpan);
        
        var value = this.component.get("value");
        this._input = document.createElement("input");
        this._input.type = "text";
        this._input.value = value == null ? "0" : parseInt(value);
        this._input.style.textAlign = "right";
        Echo.Sync.Color.render(this.component.render("foreground"), this._input, "color");
        Echo.Sync.Color.render(this.component.render("background"), this._input, "backgroundColor");
        Echo.Sync.Font.render(this.component.render("font"), this._input);
        Echo.Sync.FillImage.render(this.component.render("backgroundImage"), this._input);
        this._div.appendChild(this._input);
    
        this._incSpan = document.createElement("span");
        this._incSpan.appendChild(document.createTextNode(">"));
        this._incSpan.style.cursor = "pointer";
        this._div.appendChild(this._incSpan);
        
        Core.Web.Event.add(this._decSpan, "click",
                Core.method(this, this._processDecrement), false);
        Core.Web.Event.add(this._incSpan, "click",
                Core.method(this, this._processIncrement), false);
        Core.Web.Event.add(this._input, "change",
                Core.method(this, this._processTextChange), false);
    
        parentElement.appendChild(this._div);
    },

Let's examine the first new line of code shown above:
Echo.Sync.Color.render(this.component.render("foreground"), this._input, "color");

The Echo.Sync.Color.render() method takes a color property, DOM element, and CSS style attribute as its parameters (in that order). To determine the value of the property, we invoke the render() method on the Component. The method will query the component, its Style, and its application's StyleSheet in that order and return the property value if it is set, or null if it is not. In the case that Echo.Sync.Color.render() receives a null property value, it will simply return, doing nothing. If it receives a valid property value, it will update the specified CSS attribute value to reflect the provided property.

You'll want to look at the client-side API specification for the Echo.Sync namespace for more details on how each of these property rendering methods works. The API provides many shortcuts for common cases, for example, we don't have to invoke Echo.Sync.Color.render() twice to set the foreground and background colors; instead we could simply invoke the following convenience method which will set both foreground and background colors in one shot:

Echo.Sync.Color.renderFB(this.component, this._input);