Easy Installation

No need for Node.js, Webpack, Babel, or Gulp.

snuggsiツ works in production or in a plain 'ol HTML file!

Simply place the following script within your webpage:

  <script src=https://unpkg.com/snuggsi></script>
  

Et Voila (that's it!) ツ

See ECMAScript Module Imports for <script type=module> support!

Custom Element Lifecycle

0. define Element

A custom element is "defined" by specifying the Element `your-tag-name` declaration immediately followed with a (class extends HTMLElement {}) definition. The custom element will be considered an UnknownHTMLElement until an Element definition is specified. This means your custom element can be styled like any other HTML element. However, your element will not have functionality until after definition.

1. initialize Construction

After Definition & Declaration the custom element will go through it's constructor () routine. Typically you will not need to define a constructor () on your class. snuggsiツ takes care of all super () calls for you on instantiation.

If you would like to alter the custom element construction, define an initialize () function which is a hook that will be used automatically.

2. Reflection

After Construction the custom element will inspect your class extends HTMLElement definition for Event Handlers. These are typically methods prefixed with on (example: onclick (event)). snuggsiツ will automagically^™ delegate the event handler to your custom element container. As a convenience the this keyword will Always be bound to the custom element.

3. <link>Importing

The <link rel=import> step is critical for custom elements which contain a definition within an external file. (See HTML Imports for more detail). This is not your typical "import javascript library" you have been used to for years. Imports are relative to the partial HTML document that contains the contents to hydrate each instance of your custom element on upgrade.

4. <slot> Replacement

After Importing the default contents of your custom element there will be a replacement of any child elements with a slot=slotname attribute within your custom element. Your "Named Slot Elements" will replace the default import slots If the slot attribute coincides with a <slot name=slotname> defined within the imported custom element. In other words … An element with a slot attribute is assigned to the slot created by the <slot> element whose name attribute's value matches that slot attribute's value.

5. Rendering

Rendering of your custom element occurs on three specific occasions:

1. After on events (example: onclick (event)).
2. After initial onconnect () hook is fired.
3. Explicit calls to this.render ().

(See Animation Frames for more detail). Rendering can be disabled from within event handlers by calling event.prevent () from within handler functions. Be sure to declare event in your method signature. (example: onclick (event) { event.prevent () }

5a. {token} Binding

Occurs by "Tree Walking"^™ child content of your custom element each time a {token} is discovered. Tokens are a declarative placeholder for "Computed Property" values declared in your class definition. {foo} is replaced with "some value" If a get foo () { return 'some value' } is a property of your class definition.

5b. <template> Iteration

Often we need to iterate over collections within a custom element. Traditionally this is done imperatively vs. declaratively by using looping mechanisms that feel more like leaky abstractions than common HTML. snuggsiツ will "Tree Walk"^™ the children of your custom element looking for <template name=…> and "bind" the collection value of a property with the same name on your class.

5c. Event Registration

One of the many pains of classic browser programming is registering events on DOM elements. Event Registration is the process of declaratively registering event handlers by name within your custom element and <template> HTML. snuggsiツ will "Tree Walk"^™ your custom element and children looking for valid W3C GlobalEventHandlers by name once "connected" to the HTML document. <foo-bar onclick=hello> will "automagically"^™ register the hello (event) { } handler defined on the custom element class definition.

6. Post-Render Idle

Idling occurs after the Rendering routine consisting of Token Binding, Template Iteration, & Event Registration has completed. This 16ms , or 60 Frames Per Second rate period coincides with the idle time between animation frames .

7. Triggering Events (On completion repeats rendering step #5 a, b, & c)

There are a few ways events are registered by snuggsiツ. Whether you choose a declarative registration <button onclick=onfoo>, an imperative registration onclick (event) {}, or an explicit registration this.on ('click', this.onfoo), the Rendering pipeline will force a "reflow" and "repaint" unless the event is explicitly prevented.

To prevent Rendering simply prevent the default event action by calling
event.prevent () within the custom element handler.

Conventions

Anti-Patterns

Interfaces

This is some content about interfaces

Events

Tokens

Slots

Context

Mixins

Further Learning

• <mixins>
• Mixin: Object Oriented Programing Concepts
• Mix-in Definition
• Class Mix-ins