All examples in this documentation use the ES2015/ES6 syntax. Use a compiler like Babel to compile them into ES5 compatible Javascript.

Custom Elements

Custom elements are a great way to add some custom behaviour to dom elements, in a reusable and modular manner. GREMLIN.JS offers a simple interface to create and describe these custom elements.

Currently, GREMLIN.JS uses the Custom Elements V0 spec. It's planned to add support for the V1 version of the custom elements in the future.

Browser support

Creating custom elements with document.registerElement is supported in modern Chrome, Firefox and Opera. For older browser there exists a small polyfill, that's already included in GREMLIN.JS. If you need support for IE8, you'll have to include another script available at the polyfills repository.

You can use the barebones GREMLIN.JS library, too, if you want to bring your own polyfill or prefer to live on the cutting edge. Include the lib/native.js instead to omit the polyfill.


Creating components

The spec

Every gremlin component is described with a component specification, an object literal providing methods, properties and an optional constructor function initialize.

You'll add the spec to GREMLIN.JS by calling the gremlins.create function.

property type description
mixin Object, [Object] on or more mixins to use with this component
created Function called for all elements after they were created
attached Function called for all elements after they were added to the dom
detached Function called for all elements after they were removed from the dom
attributeDidChange Function called for all elements if a one of the element's attributes was changed

Additionally, every gremlin provides a reference to the actual dom element with this.el;

import gremlins from 'gremlins';
import gremlinsJquery from 'gremlins-jquery';

gremlins.create('foo-gremlin', {
  mixins: [gremlinsJquery],
  created: function(){
    console.log('a new foo is in town!', this.el);
  }
});


The custom element

When you created a spec, you can use the corresponding custom element to add gremlin components to your site. In fact, it does not matter if you create the spec first, specs can be added after the element exists in the dom.

The custom element's (tag) name is created with the tag name you provide when creating the gremlin.

The spec

gremlins.create('my-element');

would be used for all

<my-element>...</my-element>

elements.


Tag names

Some theory first:

The custom element type identifies a custom element interface and is a sequence of characters that must match the NCName production, must contain a U+002D HYPHEN-MINUS character, and must not contain any uppercase ASCII letters. The custom element type must not be one of the following values:

  • annotation-xml
  • color-profile
  • font-face
  • font-face-src
  • font-face-uri
  • font-face-format
  • font-face-name
  • missing-glyph

works:
<foo-bar /> or <my-tag />

throws an exception:
<foo />, <foo_bar /> or <fooBar />