Rocket fuel for component development
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
|Edge (all versions and devices), Internet Explorer 9+|
|Firefox (all versions, devices, and platforms)|
|Chrome (all versions, devices, and platforms), Android 4+ stock browser|
|Safari Mac, Safari iOS 5+|
|Opera 11+ (all devices and platforms)|
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.
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:
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.
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.
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:
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:
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
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.
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
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:
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
move, X-Tag is unifying the mouse and touch equivalents of these events - have a look:
One advanced feature of X-Tag you should be aware of right off the bat is the
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:
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.
Define and register a new custom element. The example below shows test values for each of the top-level definition objects.
|NAME||String||The custom element's tag name (must contain a dash)|
|DEFINITION||Object||An object containing the various features your custom element will utilize|
for ensuring selections are easily iterable with standard JS Array functions, like
|ELEMENT||DOM element refrence||A reference to the DOM element you wish to query|
|SELECTOR||String||The CSS selector you would like to query the element with|
Query only the direct children of an element with a provided selector.
|ELEMENT||DOM element refrence||A reference to the DOM element you wish to query.|
|SELECTOR||String||The CSS selector string you would like to test for matches against the element's direct children.|
Generates a document fragment from a string, list of nodes, or a multi-line comment string.
||Pass in a string or function with a multi-line comment string of HTML, and a Document Fragment will be created from the contents.|
Add a native, custom, or X-Tag library event listener to an element. The TYPE field also accepts pseudo chains for even more powerful event handling.
|ELEMENT||DOM element reference||The element you would like to attach an event listener to.|
|TYPE||String||The event name, with any event pseudos you may want to chain.|
|HANDLER||Function||The event handler you want called when the event occurs.|
Add multiple native, custom, or X-Tag library event listeners to an element using one function. Pseudo chains are avaliable for use in your event object keys.
|ELEMENT||DOM element reference||The element you would like to attach the event listeners to.|
|OBJECT||Object||An object composed of multiple events - keys are event names, and values are the event handlers.|
npm install x-tag
bower install x-tag-core