x-slot

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

Warning

Mixins

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.

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.

Param	Type	Default	Description
message	string		The message to display in the warning
type	string	"xslot.warning"	The warning type. Convention is to not use spaces. Use ".", "_", or "-" instead

warning.toConsole()

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

WARNING: 

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

Param	Type	Description
target	HTMLNode	The HTML node to which the nodeList elements will be appended
nodeList	Array.<HTMLNode> | HTMLNodeList	An array of HTMLNodes or an HTMLNodeList

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.

Param	Type	Description
options	object	An object containing options to enhance the behavior of x-slot
options.cacheDom	boolean	If TRUE, the slot content will only be retrieved if it hasn't already been retrieved. This is useful for using the library with frameworks that bind the HTML elements directly. An update can be forced by setting the force param to TRUE. Default is FALSE.
options.force	boolean	Force the slot content to update even if it's already been inserted. Useful only if cacheDom === true
options.delay	boolean	If TRUE, this will perform the default function on the next execution cycle. This is useful for having x-slot work on frameworks, like Mithril, where the children of the current element aren't accessible on the cycle that the "inserted" callback is called on.

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

Param	Type	Description
element	HTMLElement	The HTML Node element to which the classes should be added
classNames	string	A space delimited string of class names that should be added to the element if missing
prepend	boolean	If TRUE, will prepend the missing class names. Otherwise, the names will be appended. Default is TRUE (prepend)