x-slot v0.7.0

x-slot - Overview

A mixin that brings <slot> capabilities to CustomElements created using the x-tag library.

Why was this created?

CustomElements are great, but the lack the ability to (easily) work with elements provided from outside the template HTML. ShadowDOM solves this issue by providing the <slot> element (which doesn't work outside of ShadowDOM). The solution was to create a mixin that provides any CustomElement with <slot>-like capabilities.

How do I use it?

This mixin has been, so far, only used with CustomElements created using the x-tag library. It's possible that it will work with any CustomElement but has yet to be tested.

To use, simply assign the mixin methods to the CustomElement's prototype:

require("x-tag").register("my-tag", {
  content: `<template>
              <x-slot>default content...</x-slot>
            </template>`,
  methods: Object.assign(require("x-slot"), {
    // extra methods here...
  })
});

then, run the "getSlotContent()" method to place the elements provided from outside of the CustomElement, into the correct slot:

require("x-tag").register("my-tag", {
  content: ...,
  methods: ...,
  lifecyle: {
    inserted: function(){
      this.getSlotContent()
    }
  }
})

That method must be run in the "inserted" lifecycle method - the elements provided from the outside are not yet children of the CustomElement when the "created" lifecycle method is run.

I'm using ES5 and need to include it in an HTML file...

No fear! Simply include the ES5 transpiled file in the dist folder:

<!-- example.html -->
<script src="/path/to/x-tag.js" -->
<script src="/path/to/x-slot.js" -->

// example.js
xtag.register("my-tag", {
  ...
  methods: xSlot
  ...
});

Is using the <template> necessary?

Yes! Part of the design of this mixin is the ability to easily switch from using the <x-slot> tag and the actual <slot> tag. Simply append a ShadowDOM to the CustomElement and replace all instances if <x-slot> with <slot>.

Contributing

Please run all tests and add/update tests if you make changes. Also, update the CHANGELOG with a description of your changes. Here are some useful build scripts:

• npm run deploy: test, build, minify
• npm run build: run browserify + babel
• npm run test: start karma in watch mode
• npm run test-once: start karma in single-run mode
• npm run minify: minifies the file outputted by npm run build. This generates the dist/xslot.min.js file# x-slot 0.5.0

A mixin that brings <slot> capabilities to CustomElements created using the x-tag library. Edit Add topics

API v0.6.0

Classes

Mixins

Warning

Kind: global class

• Warning
  • new Warning(message, type)
  • .toConsole()

new Warning(message, type)

A simple class for returning warnings. It provides a method for sending the warning to the console.

warning.toConsole()

Generates a warning message in the console. If console.warn is undefined, it logs with

Kind: instance method of Warning

xSlot

This mixin provides custom elements with like functionality. This is a useful addition to CustomElements and, if changing to WebComponents, simply switch to and it should work correctly with the ShadowDOM.

Kind: global mixin
this: The
Requires: module:Array.prototype.filter, module:document.querySelector, module:Object.assign
Example

xtag.register("my-tag", {
  content: "<template>...</template>",
  methods: Object.assign({}, xslot, {
    // other methods to attach to CustomElement...
  }),
  lifecycle: {
    inserted: function(){
      // expects the content of the element to use the <template> tag
      this.getSlotContent();
      // getting the slot content should happen AFTER the created
      // lifecycle. At the time of creation, any child elements
      // added by the developer *doesn't yet exist*. Only the <template>
      // exists at that point.
    }
  }
})

• xSlot
  • .appendNodesTo(target, nodeList) ⇒ null | Error
  • .getSlotContent(options) ⇒ Error | Warning | null | Promise
  • .addClass(element, classNames, prepend) ⇒ null | Warning | Error

xSlot.appendNodesTo(target, nodeList) ⇒ null | Error

Helper method that appends all of the nodes in the nodeList to the target node.

Kind: instance method of xSlot
Returns: null | Error - null is returned if successful

xSlot.getSlotContent(options) ⇒ Error | Warning | null | Promise

Finds all of the tags and appends the content to the correct slot. This method updates the DOM directly.

Kind: instance method of xSlot
Returns: Error | Warning | null | Promise - null is returned if the slot was successfully filled without errors or warnings. A Promise is returned if options.delay is TRUE. This promise resolves after the slot content has filled.

xSlot.addClass(element, classNames, prepend) ⇒ null | Warning | Error

Prepends the provided element's class attribute with the provided string of class names if the element doesn't already contain that class. If element is null, a warning is logged to the console. Warningings can be shut off if the global variable NODE_ENV is set to "production"

Kind: instance method of xSlot
Returns: null | Warning | Error - null is returned if successful