Web Components With X-Tag

Written by Ian Elliot

Tuesday, 15 October 2013

Article Index
Web Components With X-Tag
Using X-Tag
Accessors, Methods and Events

Page 2 of 3

xtaglogo

Using X-Tag

The X-Tag library is an implementation of Web Components that is compatible with the W3C standard but not identical. It is built on top of the "polyfills" provided by the Polymer library. As already mentioned, it has been used by Mozilla to implement the Brick component library.

The first thing you need is a downloaded copy of the library.

Go to the X-Tag website and download a zip of the library. This includes a everything you need to build your own custom version of the library as well as a fully built library that you can just use. The only problem is that the X-Tag distributable also includes a range of sample components. If you want to distribute the smallest version of the library these need to be removed. At the moment the libary is about 21Kbytes.

Once you have the zip file you need to extract files in the dist folder and place them in a location where your web page can load them. The JavaScript library is currently called X-Tag-components.js and there is an associated CSS file of the same name that you should use if you plan to use any of the included components.

Add to the <head> section of the webpage:

<script type="text/javascript" src="/X-Tag-master/dist/X-Tag-components.js"></script>

Change the path to the file according to where you have stored the library.

At the moment you can only create a web component programatically and the xtag.register method wraps the document.register method provided by Polymer - later it will wrap the builtin method specified by the standard.

The xtag.register method has two paramters:

xtag.register("my-component", prototype object for the component );

Which is only slightly different to the document.register method. However there are more differences in the prototype object.

The Lifecycle Object

The lifecycle object is used to hold four event handlers

created - called when a component is created
instered - called when a component is inserted into the DOM
removed - called when the component is removed from the DOM

attributeChanged - called when any attributes are set

You can see that these are slight modifications and augmentations of the standard.

You can also put an extends property into the prototype to say what the component extends - but it doesn't seem to have any real effect.

With just this information let's implement a very simple web component - a div with minimal content.

xtag.register('my-component', { extends: 'button', lifecycle: { created: function() { this.innerHTML="<div>mycomponent</div>" } } } );

The new component extends button. The lifecycle object has only one event handler defined "created. This simply uses this, which is set to the HTML element object that we are creating to change the innerHTML to some somple HTML. You could also do the same job using ElementCreate and adding new DOM objects as children.

Notice that you don't have to call everything x-something as per the X-Tag examples but you do need to include a hyphen.

Now that the component has been registered you can make use of it using createElement or declaritively using tags:

<my-component>test1</my-component>

This results in:

<button is="my-component">test</button>

X-Tag converts this to:

<my-component is="my-component"> <div>mycomponent</div> </my-component>

Notice that X-Tag adds the is atrribute even if you don't.

You can also use the is attribute directly:

<button is="my-component">test</button>

In this case the initial element created i.e that this references in the created event handler is a button. That is X-Tag converts what you have written to:

<button is="my-component"> <div>mycomponent</div> </button>

That is if you use the <button is> form you get a button DOM object to either overwrite or elaborate on and if you don't you get a general HTMLelement - and this is irrespective of any extends property you may include in the prototype. This is probably not the intended behaviour and it means that your component could be used in ways you never intended. It is probabily a good idea to either check what sort of element you have "inherited" i.e. what this is set to or always overwrite it.

Of course the way that this all works is that the X-Tag library scans the HTML and dynamically converts it according to the code you write. What this means is that until X-Tag has completed its task the custom components don't exist. Any code that you want to run to work with your custom components has to wait until X-Tag has done its job and the simplest way to do this is to make use of the polymer DOMComponentLoaded event hander:

document.addEventListener('DOMComponentsLoaded', function(){...

Properties,Method And Events

As well as the four life-cycle event handlers you can also define some other things with the help of X-Tag. To be precise - properties complete with get/set accessors, methods and events.

Each of the following objects are placed within the prototype object passed to the register method but for simplicity they are listed independently. The full structure of the prototype object passed in the register call is:

{ extends:"tag", lifecycle: { created: function() {}, inserted: function() {}, removed: function() {}, attributeChanged: function() {} }, events: { }, accessors: { }, methods: { } }

Let's look at each of these objects in turn.

<< Prev - Next >>

Last Updated ( Tuesday, 15 October 2013 )