In order to allow for the recognition and parsing of custom HTML tags,
X-Tag relies on a variety of events to detect
and upgrade elements with user-defined, extended functionality. X-Tag
works regardless of whether the element was present in the original
source of the document, added by setting
generated dynamically using
an example showing the registration of a custom element, with a
description of each of the foundational interfaces the API offers:
Whenever a tag is recognized and parsed on load or generated using
document.createElement, a created function is called
allowing you to modify the element before any other code is applied to it.
The inserted method is called everytime a given component's DOM element is added to the DOM. This allows you to do things like check the state or structure of the surrounding DOM tree or window scope and modify your component accordingly.
The accessors object provides native value retrieval handlers
to your component. For example: if a user caches a component's value,
var value = element.value; your
getter would have the opportunity to fetch that value from anywhere
you'd like and even modify it before returning.
The attribute object allows easy mapping from an accessor to an element attribute. Instead of having to write getAttribute and setAttribute inside of your accessors, you can add the attribute object to create the mapping automatically. There are also a few options available inside the attribute object. See the code example below.
The events object allows you to bind events to the component at the time of creation.
Pseudo events like delegation are supported, additional pseudos can be added to
pseudos object on the global
The mixins array allows you specify mixin keys that map to collections of getters, setters,
events, and lifecycle functions. X-Tag merges mixins into your component definition object for you.
Mixins are found on the
mixins object of the global
xtag variable -
you can add your own mixins there too!
Extends allows you to use an existing html element as the base of your custom element. Common values are
div, span, input.
Prototype allows you to set the prototype of the custom element to any object you wish. This enables you to incorporate functionality of another object into your custom element.
The X-Tag library comes with just enough helper methods to make it bearable to work in Vanilla JS.
Converts the given object into an array.
Returns a boolean that indicates if the element has the specified class.
Adds a class to the element.
Removes a class from the element.
Adds the class if it doesn't exist on an element or removes the class if it exists.
Returns a boolean that indicates if the given selector matches the element.
Runs querySelector all on the given element and returns the results as an array.
Allows you to query only the direct children of the element.
Returns an animation frame.
createFragmentelement or html string
Creates a document fragment out of the passed element.
Returns a new function where the first function is called, then the second function. If false is returned from the first function then the second function will not execute.
Sets the innerHTML of element with the passed html and parses for x-tags. You need to do this instead of just assigning the innerHTML property if you intend to use custom elements as part of the html of a custom element.
fireEventelement, eventType, object
Creates a DOM custom event and fires it on the given element.
addEventelement, eventType, function
Adds a DOM event listener to an element. It also allows for event pseudo chains. Returns an event object that is used for removal of the event listener.
Adds multiple DOM event listeners to an element. Returns a collection of event objects that is used for removal of the event listeners.
removeEventelement, eventType, event
Removes a DOM event listener from an element. Passing the event type is optional.
Removes multiple DOM event listener from an element.
X-Tag pseudos can be applied to accessors, events and methods. They allow you to easily tack on common functionality like filtering and delegation.
Delegate works by attaching a listener to a given element/document and will call the provided function if the target matches the delegate selector.
Keypass acts as a filter, only letting through certain keycodes.
Anything placed inside a template element will be turned into a HTML document fragment. Use the
.content accessor to access the document fragment and cloneNode() to create a new instance of the contents.
You can also use templates when registering components. For example: