3.0 beta 2

HTML

The user interface built with ActiveWidgets library usually consists of multiple high-level components. However, at the low level, each component is still composed from one or more basic HTML objects, which are rendered into HTML markup before inserted into the DOM and displayed by the browser.

Standalone elements

The AX.HTML class represents a single HTML tag.

var obj = new AX.HTML({
    id: 'test',
    innerHTML: 'Hello, world!'
});

// returns <span id="test">Hello, world!</span>
obj.toHTML();

To insert the ActiveWidgets component into the page you should include the placeholder tag with the matching id into your page markup.

<span id="test">Loading...</span>

The library will search the page for the DOM element with the same id and automatically replace it with the markup generated by the corresponding ActiveWidgets object.

This is only necessary for the top-level or standalone components. The child objects do not need separate ids or placeholders - the library will automatically insert or remove them from the DOM as you modify the content of your ActiveWidgets components.

Instead of using id and placeholder tag you can also insert the object manually with jQuery or DOM API.

// generate component markup
var markup = obj.toHTML();

// insert into the page with jQuery
$('.parent').html(markup);

Classes

The preferred way to change visual appearance of the ActiveWidgets component is to use css classes. Put css rules into the style block or external stylesheet and link them to your component with classes collection.

var obj = new AX.HTML({
    classes: 'my-component'
});

It is a good idea to use a prefix for all your classes to avoid name collision with 3rd party libraries (all ActiveWidgets 3 classes are prefixed with ax-).

Another good idea is to use properties. Instead of directly modifying the classes collection, link the classes to the object properties (via templates or calculated elements).

var obj = new AX.HTML({
    type: 'default',
    classes: 'my-{{@type}}-component'
});

// modify 'type' property
obj.type('active');

// returns <span class="my-active-component"></span>
obj.toHTML();

Changes to the linked property will trigger automatic updates of the class attribute at the component DOM node.

Styles

To modify component inline styles use styles collection.

var obj = new AX.HTML({
    styles: {
        color: 'red',
        width: '50%'
    }
});

or

var obj = new AX.HTML({
    styles: 'color:red; width:50%'
});

The styles collection elements are also accessible via style shortcut.

// get style
var s = obj.style('color');

// set style
obj.style('color', 'red');

Again, exposing the style value via dedicated property will make the code more readable -

var obj = new AX.HTML({
    color: 'red',
    styles: 'color:{{@color}}'
});

// update 'color' property and 'color' style
obj.color('blue');

Attributes

The attributes collection and attribute shortcut provide access to the inline html attributes.

// get 'title' attribute value
var s = obj.attribute('title');

// set value of the 'title' attribute
obj.attribute('title', 'xyz');

The id, classes and styles attributes are also part of attributes collection.

Content

The content of the HTML tag is available via innerHTML property.

var obj = new AX.HTML({
    message: 'Hello, World!',
    innerHTML: '<b>{{@message}}</b>'
});

As all ActiveWidgets properties accept promises, you can assign the deferred content (the object exposing Promise API) directly to the innerHTML.

// load the content (asynchronously, using jQuery)
var content = $.get('content.html');

// assign the deferred content directly to the innerHTML property
obj.innerHTML(content);

Composite elements

When an object contains other objects as child properties, it does not mean all of them will be automatically displayed as part of the parent content. To be included into the parent markup the child object has to be referenced by the parent template (or one of the already included children).

var icon = new AX.HTML({
    tag: 'img',
    src: '...'
};

var obj = new AX.HTML({
    icon: icon,
    text: 'xyz',
    innerHTML: '{{@icon}} {{@text}}'
}};

The child objects can also be referenced by object collections (using @name initialization strings).

var obj = new AX.Container({

    productSelector: {
        component: 'list',
        width: 150,
        height: 300
    },

    productPrice: {
        component: 'input',
        width: 150
    },

    orderAmount: {
        component: 'input',
        width: 50
    }

    // include child components into main form content
    items: ['@productSelector', '@productPrice', '@orderAmount']
});