Getting Started with X-Tag

What is X-Tag?

X-Tag is a small library that wraps the Web Components family of APIs to provide a tight, feature-rich interface that makes development of components even easier. The basic build only relies on the presence of the Custom Elements features of the Web Components specs - and in the absence of those features, X-Tag leverages Google's shared polyfill. If you're in a browser that supports the entire Web Components family of specs, or include the full set of polyfills (including HTML Imports and Shadow DOM), X-Tag provides feature hooks to easily incorporate those features.

X-Tag has focuses on eliminating common, repetitive cases, and brings to bear a set of features that are extremely advanced, all in a tiny package weighing less than 12k. With X-Tag, your components will be smaller, more efficient, and easier to maintain.

Welcome to Web Components, Welcome to X-Tag!

Installation of X-Tag

X-Tag comes in three flavors:

X-Tag lib (requires you to ensure Custom Element features are present)

https://github.com/x-tag/core/blob/master/src/core.js

X-Tag lib + Custom Elements polyfill

https://github.com/x-tag/core/blob/master/dist/x-tag-core.min.js

X-Tag lib + full, Web Components polyfill set

It All Starts with Registration

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 declare the lifecycle callbacks, accessors, and events for your custom element. Here's what defining a custom element looks like with X-Tag:

xtag.register('x-frankenstein', {
  lifecycle:{
    created: function(){
      alert("Look! It's moving. It's alive!");
    }
  }
});

Meet the Lifecycle Callbacks

There are 4 lifecycle callbacks you'll leverage often when developing components, here's an example of what all 4 look like when specified in an element definition:

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

Adding Methods to the Mix

Your custom elements are probably going to need some of their own, unique methods to provide the functionality you desire. X-Tag makes method attachment a snap, you 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:

xtag.register('x-foo', {
  lifecycle:{
    created: function(){
      this.shout('WHY AM I YELLING?');
    }
  },
  methods: {
    shout: function(message){
    	alert(message);
    }
  }
});

Say Hello to Accessors

X-Tag features an easy system for dealing with attributes, setters, getters, and linking them all together. To use these features, add an accessors object to the top level of your xtag.register() definition object. Within this object, you can add keys that will be made available as getters/setters, as seen below. By adding the key attribute, it tells X-Tag to link the bar setter/getter with the bar attribute.

xtag.register('x-foo', {
  lifecycle:{
    created: function(){
      alert('x-foo in da house!');
    }
  },
  accessors: {
    bar: {
      // this links the attribute 'bar' to the getter/setter xfoo.bar
      attribute: {},
      get: function(){
    		// do something when the getter is accessed
    	},
      set: function(value){
    		// act on the value being passed to the setter
    	}
    }
  }
});

There are a few advanced options available in the attribute object that let you configure the way the setter/getter and attribute linkage operates. The most oft used feature is name. This key allows you to specify an alternate attribute name to link the accessor with. Here's an example to help visualize the use case:

xtag.register('x-foo', {
  accessors: {
    bar: {
      attribute: {
        name: 'data-bar'
      }
    }
  }
});

The DL on Events

X-Tag provides an insanely powerful event system that 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 add events to your component, is add an events object to the top level of your xtag.register() definition object. The keys of this object will be the event types you wish to bind to your custom element. In the example below you'll see a familiar, native event name, click, and a couple that are custom: tap and move. These are just two of the custom events X-Tag provides that unify, optimize, and simplify common event interactions. In the case of tap and move, X-Tag is unifying the mouse and touch equivalents of these events - have a look:

xtag.register('x-foo', {
  events: {
  	click: function(){
    	// perform an action when the user clicks on your element
    },
    tap: function(){
    	// perform an action when the user taps your custom
      // element via a mouse click or touch input.
    },
    move: function(){
    	// perform an action when the user moves their 
      // mouse click or finger (touch) over your element
    }
  }
});

The one advanced feature you should know about right off the bat is the delegate pseudo. X-Tag features a function modifier system called pseudos that allows you to create seamless wrap existing functions to extend their functionality. The delegate pseudo enables you to quickly add event delegation (event target filtering based on CSS expression) to any event function you bind to your component. Here's an example:

xtag.register('x-foo', {
  lifecycle:{
    created: function(){
      this.appendChild(document.createElement('input'));
    }
  },
  events: {
    'tap:delegate(input)': function(){
    	// Perform an action *only* when an <input> within your
      // custom element is tapped via mouse click or touch input.
    }
  }
});

For more information on what event delegation is, see this resource: http://stackoverflow.com/questions/1687296/what-is-dom-event-delegation