X-Tag

Rocket fuel for component development

Standard

Built on Web Components APIs

Efficient

Powerful features, just 5k gzipped

Pluggable

Plays nice with other libraries

What is X-Tag?

X-Tag is a Microsoft supported, open source, JavaScript library that wraps the W3C standard Web Components family of APIs
to provide a compact, feature-rich interface for rapid component development. While X-Tag offers feature hooks for all Web Component APIs
(Custom Elements, Shadow DOM, Templates, and HTML Imports), it only requires Custom Element support to operate.
In the absence of native Custom Element support, X-Tag uses a set of polyfills
shared with Google's Polymer framework. You can view our package options in the Builds section

Time for a demo

Here's a nifty ‹x-clock› component to help you get a sense of what it's like to create Web Components
with X-Tag. As you can see, there's a tap event attached to the element that lets you start and stop time - but be careful,
stopping time is serious business, you don't want to cause a chain reaction that unravels the very fabric of the space-time continuum.

Docs

Table of Contents

Getting Started

Registration - Where it All Begins

The most important method in the X-Tag library is xtag.register(). The register function on the X-Tag object is what you'll use
to create new custom element definitions, which can include things like lifecycle callbacks, attibute-linked getters/setters (accessors),
and event listeners. Here's what defining a simple custom element looks like with X-Tag:

Content is King

For many of the components you create, you'll want to insert various elements into them for structure and presentation purposes. X-Tag provides some awesome features to help you with this.
The primary method for adding content to your component with X-Tag is the content property of your component registration defintion.
The content property accepts both a simple HTML string, or a comment string within a function to enable multiline HTML snippets. Below are examples
of what each variant looks like in practice.

Simple string:

xtag.register('x-frankenstein', {
content: '‹h2›My name is Frank‹/h2›' +
'‹span›I work for a mad scientist‹/span›'
});

Multi-line string:

xtag.register('x-frankenstein', {
content: function(){/*
‹h2›My name is Frank‹/h2›
‹span›I work for a mad scientist‹/span›
*/}
});

Meet the Lifecycle Callbacks

There are four lifecycle callbacks you will rely on to develop your components.
Here's an example of what each looks like when specified in an element definition:

xtag.register('x-foo', {
lifecycle:{
created: function(){
alert('I fire when an ‹x-foo› is CREATED');
},
inserted: function(){
alert('I fire when an ‹x-foo› is INSERTED to the DOM');
},
removed: function(){
alert('I fire when an ‹x-foo› is REMOVED from the DOM');
},
attributeChanged: function(attrName, oldValue, newValue){
alert('I fire when an ATTRIBUTE is CHANGED on an ‹x-foo›');
}
}
});

Adding Methods to the Mix

Your custom elements will likely need some of their own, unique methods to provide the functionality you desire.
X-Tag makes method addition a snap, just add a methods object to your top-level xtag.register() definition object
and include your methods within it - here's what it looks like:

Say Hello to Accessors

X-Tag has built-in features to deal with attributes, setters, getters, and link them all together to provide a common interface.
To use these features, you first add an accessors object to the top level of your xtag.register() definition object.
Within this object you can add keys names that will be made available as getters/setters, as seen below. By adding the key attribute,
to an accessor, it tells X-Tag to link the setter/getter with the corresponding HTML attribute of the same name. When attributes are linked to
a getter/setter, their gets, sets, and state will remain in sync without having to write any additional code.

The `attribute` property of an accessor has a few options you can use to change behavior and perform advanced syncing to other parts of your component.
Some of these advanced options include `boolean`, `property`, and `validate`, which are detailed in the examples below.

The DL on Events

X-Tag provides an insanely powerful event system you'll use often in developing your components.
We'll cover the basics here, and leave the more advanced features for a special tutorial dedicated to the topic.

The first thing you'll need to do to attach events to your component is add an events object to the top level
of your xtag.register() definition object. The keys of this object are the names of the events you wish to attach to your custom element.
In the example below you'll see a familiar, native event name, focus, and a couple that X-Tag provides to make life easier:
tap and move. These are just two of the custom events X-Tag provides that unify, optimize, and simplify common event interactions
across platforms and devices. In the case of tap and move, X-Tag is unifying the mouse and touch equivalents of these events - have a look:

Gettin' Jedi with Pseudos

One advanced feature of X-Tag you should be aware of right off the bat is the delegate pseudo.
X-Tag features a function modifier system called pseudos which allows you to seamlessly wrap
functions anywhere in your custom element defintion object (lifecycle callbacks, methods, accessors, and events)
to extend their functionality. The delegate pseudo enables you to quickly add event delegation
(filtering of event targets based on CSS expressions) to any event function you add to your component. Here's an example:

Create your own Pseudo:

Once you create a pseudo and add it to the main xtag.pseudos object, as show below,
you can then use it on any key of your custom element defintion objects that has a
function as its value.

xtag.pseudos.example = {
onAdd: function(){
/*
This function is fired once when the base function is added to
the target object. For instance:
If you added an event with xtag.addEvent(someNode, 'tap:example', fn),
the onAdd function of the 'example' pseudo would be fired once when
the event is first attached to the element 'someNode'.
*/
},
onRemove: function(){
/*
This is basically the opposite of the onAdd function above.
With onRemove, you can clean up whatever you may have done
in your onAdd or action function invocations.
*/
},
action: function(pseudo, event) {
/*
This function is fired each time the pseudo chain is fired.
Pseudo actions are fired in the order they are chained, meaning
the in the pseudo 'toggle:log:example', the action function
for the 'log' pseudo would fire first, then the 'example' action
and finally the base function 'toggle' they are chained to.
*/
}
};

Inheritance

X-Tag uses the standard Custom Elements API for inheritance.
Custom elements can inherit from standard DOM elements by using
the extends property.

Extending custom elements:

To extend custom elements, you need to use the
the prototype property. Keep in mind that when any of the properties of the custom element is
overwritten, it gets added to an execution queue. When accessed, the base property will be executed first
and then the rest of the queue will be accessed. For this cases the is syntax is
not needed.