Table of contents

• About JWL
  • Features
  • System requirements
  • Installation
• How to build a JWL component
• Saving and loading components
• Pre-create and post-create phases
• JWL and HTML5 web components
• More about creating a JWL component
• Three ways of using the JWL components
• TODO

About JWL

The JavaScript Widget Library (JWL) is a tool that allows you to build modern web applications by providing a simple way to create HTML components.
JWL is based on JUL - The JavaScript UI Language module and it easily integrates with JUL Designer.

How to build a JWL component

Building a JWL component is an easy process, either if you write the code directly or, even better, if you use JUL Designer to generate it. Here are the steps:

1. Write a configuration object for the root component. This should have at least a tag property and a binding ID property. The tag should be an existing HTML tag, and the binding should be a string starting with a dot. This string is referred as the component class.
2. Add a children array to the root config containing other configuration objects. These nay have binding IDs and should have at least a tag property. This tag can be a HTML tag or a JWL component name.
3. Create a separate object for the interface logic (behavior). This should have properties with the dame name as the binding IDs defined in the configuration tree. Each property is an object whose values are applied over the corresponding object in the config tree.
4. For each object in the logic configuration you may add properties like ‘data-<item>’. Here you must also add the element listeners if present. Add a 'listeners' object with properties set to event names and values set to your custom event handlers (listeners).
5. You can use the newly created component with JWL.parser in a page generated by JUL, or you can register it as a custom HTML element with JWL.register(), depending on browser support.

Saving and loading components

One or more JWL components can be serialized into JSON with JWL.save() and can be loaded from the serialized form with JWL.load().

Pre-create and post-create phases

The JWL parser uses a custom factory that receives a resulting configuration object used to instantiate a component. You can inspect and affect he direct members of this config object with the pre-create callback {Component}.preCreate(). Also, you can do post-processing of the instantiated component with {Component}.postCreate() callback.

JWL and HTML5 web components

Any JWL component can be register as a HTML5 custom element with JWL.register(). This allows using the component directly in the markup of the page. The component config can be attached with two additional properties: ‘prototype’ that specifies members to be added to the custom element prototype, and ‘css’ which is an inline style of an array of URL paths of external styles to apply to the component. The external styles are loaded with XMLHttpRequest, so you should put them in the same domain as the web page.

More about creating a JWL component

A component consists of two parts: the layout configuration (UI) and the component behavior (interface logic). They are the ‘ui’ and ‘logic’ properties of the component configuration object.
The ‘ui’ property is a tree of configuration objects of the component and its descendants. The ‘logic’ property is a mapping between UI nodes binding IDs and object containing their logic configuration. The ‘logic’ part also has the 'listeners' configuration for each UI node. The listeners of each UI node are applied in cascade (as required for a HTML element). The other members of the ‘logic’ config override the members with the same key of their UI node.
Other members of the component config are ‘prototype’ which contains properties and methods that should apply to the prototype of the HTML element, and ‘css’ which is an array of CSS descriptors for a custom HTML element. See the next chapter for more explanations.
The component key/index in JWL.components should be a lower case tag-like string. If the component is outside HTML namespace, the key should be prefixed with the namespace prefix and a colon (e.g. svg:logo).

Three ways of using the JWL components

1. Use the JWL parser to instantiate a configuration tree of HTML elements. When the parser encounters a JWL component, it automatically adds extra processing for it, The process flows as follows:
   • call the component preCreate method allowing inspecting or modifying the current configuration
   • distribute the dotted attributes of the form ‘subcomponent.attribte’ to the corresponding subcomponent
   • create the component and recursively process its corresponding subcomponent tree
   • call the component postCreate method allowing to attach behavior to the component instance

2. Use the JWL register method to register a custom HTML element as ‘jwl-componentname’ tag. This has the advantage of adding custom members to the element’s prototype. These members are stored in the ‘prototype’ property of the component configuration. The configuration may also have a ‘css’ property which is an array of CSS descriptor. In the simplest form, a descriptor is a string containing an inline style but it can also contain a local domain path to an external CSS. The full descriptor is an object with two properties: ‘style’ and ‘media’.

3. Use JWL.factory() callback to create components that are not HTML elements but mimic the element’s behavior as close as possible. The component instance exposes the standard properties and methods of a HTML element augmented with the members of the ‘prototype’ property of the component configuration. The exposed members operate directly on the wrapped HTML element, but also accept arguments that are component instances.
   This approach is useful when the browser lacks support for custom elements (web components), but it is also provided as a way of wrapping the DOM owned elements into user-space objects.

TODO

• create a standard set o desktop-like browser widgets based on JWL
• create a standard set of mobile-like browser widgets based on JWL
• create a standard hierarchy of abstract widget classes whose implementations target various JavaScript event-driven renderers (e.g. browser, mobile, embedded app)