Classes

htmlLoader

ContextBinding

DataStore

EventMap

I18nMessage

I18n

Functions

bindEvents(root, context) ⇒ HTMLElement

helper function used by the loader when importing html files as a template fucntion for using attributes such as "onclick" within your html templates. You do not need to call this yourself if you are importing your html files using the loader

getFromObj(path, obj, fb) ⇒ * | String

Returns the value of an object via the path as a string

template(tmpl, map, fallback) ⇒ * | String

Processes a string formatted like an ES6 template against an object

stripES6(expr, context) ⇒ String

removes the ${} wrapping from an es6 template literal expression.

arrayParser(val, key, params) ⇒ Boolean

In the event that the search string has multiple values with the same key it will convert that into an array of those values for the given key.

While there is no defined standard in RFC 3986 Section 3.4, most web frameworks accept and serialize them in the following manner as outlined in MSDN

toParams(str, options) ⇒ Object

Converts URL parameters to a Object collection of key/value pairs Decodes encoded url characters to back to normal strings.

toSearch(options, base) ⇒ String

Converts an Object of String/Value pairs to a query string for URL parameters prepended with the "base" character. Encodes unsafe url characters to url safe encodings.

prefixKeys(obj, prefix) ⇒ Object

Convenience method that converts the keys of an object to have a prefix. This is faster than stringification.

toDataAttrs(obj, stringify) ⇒ Object

Convenience method that wraps prefixKeys with 'data-' for easier property spreading within other frameworks such as react. This is preferrable over stringifying objects as parsing json is slow in the browser

htmlLoader

Kind: global class

new htmlLoader(content)

The HTML file is converted into a module that exports a function. That function takes a single argument (p shorthand for "props"). Also provides sass support by incliding a link tag in your html file to the scss file.

We use the builtin DOMParser to parse the HTML template to reduce runtime dependencies. an IIFE that takes a single argument (props) and returns the compiled template literal tring and passes it into the DOMParser.parseFromString fn.

The IIFE ends with fn.call(p, p) which ensures that the es6 template context supports both "this" and "props" within the template.

${this.myValue} and ${props.myValue} are treated identically and can be used interchangably For on*="" HTML5 event attributes, the loader replaces any ES6 syntax before babel conversion to the es6 template literal. This way, the interaction between the on* events and the ContextBinding mixin does not break. @see ContextBinding for more details.

Returns: String - it returns the HTML content wrapped as a module function

Param	Type	Description
content	String	fileContent from webpack

Example (webpack.config.js)

    {
      module: {
        rules: [
          {
            // set this to match the paths of the html files you want to import as functions.
            test: /web-components\/.+\.html$/,
            exclude: /node_modules/,
            use: [{
                loader: '@ornery/web-components/loader',
                options: {
                    minimize: true,
                    removeComments: true,
                    collapseWhitespace: true,
                    exportAsEs6Default: true,
                    attrs: false,
                    interpolate: false
                }
            }]
          }
        ]
      }
    }

Example (example.scss)

.example-list {
  padding: 0;
  margin: 0;

  .example-list-item {
    line-height: 1rem;
    margin: .5rem;
  }
}

Example (example.html)

<link src="./example.scss" />
<h3>${this.headerText}</h3>
<ul class="example-list">
    ${this.items.map(item => `<li class="example-list-item">${item}</li>`).join("")}
</ul>

Example

// becomes converted into:
const {bindEvents, setupConnect} = require("@ornery/web-components/templates");
module.exports = (p = {})=> {
  const parsed = new DOMParser().parseFromString(function(props){
  return "<style>.example-list{padding: 0;margin: 0;} .example-list .example-list-item{line-height: 1rem;margin: .5rem;}</style>" +
    "<h3>" + this.headerText + "</h3>" +
        "<ul>" +
    this.items.map(function(item){return "<li>" + item + "</li>"; })
                     .join("") +
        "</ul>"
  }.call(p, p), 'text/html');

  const elements = [...parsed.head.children, ...bindEvents(parsed.body, p).childNodes];
  return setupConnect(elements, p)
}

Example

import listTemplate from './example.html';
const fruits = ["apple", "orange", "banana"];

const compiledDOMNodeArray = listTemplate({
  headerText: "List of fruits.",
  items: fruits
});

console.log(compiledDOMNodeArray.length) // 2
console.log(compiledDOMNodeArray[0].tagName) // "h3"
console.log(compiledDOMNodeArray[0].innerHTML) // "List of fruits."
console.log(compiledDOMNodeArray[1].tagName) // "ul"
console.log(compiledDOMNodeArray[1].children[0].tagName) // "li"
console.log(compiledDOMNodeArray[1].children[0].innerHTML) // "apple"
console.log(compiledDOMNodeArray[1].children[1].tagName) // "li"
console.log(compiledDOMNodeArray[1].children[1].innerHTML) // "orange"
console.log(compiledDOMNodeArray[1].children[2].tagName) // "li"
console.log(compiledDOMNodeArray[1].children[2].innerHTML) // "banana"

ContextBinding

Kind: global class

• ContextBinding
  • new ContextBinding(superclass)
  • .getAttribute(attrKey) ⇒ String
  • .setAttribute(attrKey, attrVal)

new ContextBinding(superclass)

helper mixins for parsing data-* attributes as json objects via get/setAttribute.

Param	Type	Description
superclass	class	inheriting class

Example

//import the ContextBinding mixin
import ContextBinding from 'mck-webcomponents/lib/context-binding';

// define your custom element.
export default class ListComponent extends HTMLElement {
  constructor(self) {
    super(self);
    self = this;
  }

  connectedCallback() {
      this.shadowRoot.innerHTML = "";
      // ContextBinding allows you to access data-* attributes as JSON objects with or without the "data-" prefix.
      let items = this.getAttribute('items');
      listTemplate({
          items,
     }).forEach((node) => this.shadowRoot.appendChild(node));
  }
}

// Before registering, apply the mixin to your class.
customElements.define('list-component', ContextBinding(MainComponent));

Example

<!-- Usage in raw HTML -->
<list-component data-items="['apple','orange','banana']" selected-item="apple"></list-component>

ContextBinding.getAttribute(attrKey) ⇒ String

If using data-attributes, it will handle the string->JSON conversion for you. You may reference the data-* attributes with or without the data- prefix for convenience.

Kind: static method of ContextBinding
Returns: String - current attribute value.

Param	Type
attrKey	String

ContextBinding.setAttribute(attrKey, attrVal)

If using data-attributes, it will handle the JSON->string conversion for you when the value to set is not a string. You may reference the data-* attributes with or without the data- prefix for convenience. Bubbles up the attributeChangedCallback to your class when values are set.

Kind: static method of ContextBinding

Param	Type	Description
attrKey	String	the attribute key to set.
attrVal	String | *	the value to set the attribute to.

DataStore

Kind: global class

• DataStore
  • new DataStore()
  • .get(key) ⇒ Object
  • .getState() ⇒ Object
  • .set(key, value) ⇒ Object | *
  • .setState(newState) ⇒ Object | *
  • .subscribe(callback) ⇒ Object | *
  • .subscribeTo(keys, callback) ⇒ Object | *

new DataStore()

Configuration values can be set and propagated to consuming components via this static class or through the corresponding wc-config element

DataStore.get(key) ⇒ Object

Kind: static method of DataStore
Returns: Object - the current value of the requested property name.

Param	Type
key	String

DataStore.getState() ⇒ Object

Kind: static method of DataStore
Returns: Object - the current state object.

DataStore.set(key, value) ⇒ Object | *

wraps this.set

Kind: static method of DataStore

Param	Type	Description
key	String | Object	the name of the value to set. It can also be called with an {} query to set multiple values at once.
value	*	the value of the property to set it to.

DataStore.setState(newState) ⇒ Object | *

wraps this.set

Kind: static method of DataStore

Param	Type	Description
newState	Object	the new state object.

DataStore.subscribe(callback) ⇒ Object | *

call destroy() on the returned object to remove the event listener.

Kind: static method of DataStore

Param	Type	Description
callback	function	is the function to execute when any property changes.

DataStore.subscribeTo(keys, callback) ⇒ Object | *

call destroy() on the returned object to remove the event listener.

Kind: static method of DataStore

Param	Type	Description
keys	Array	the property names to be notified when they mutate
callback	function	the callback to be executed when any of the value for any of those keys have changed.

EventMap

Kind: global class

• EventMap
  • new EventMap()
  • .module.exports#on(event, callback) ⇒ Object
  • .module.exports#set(key, val, notify) ⇒ EventMap
  • .module.exports#replace(keyValuePairs, notify) ⇒ EventMap
  • .module.exports#del(key, notify) ⇒ EventMap
  • .module.exports#clear(notify) ⇒ Object
  • .module.exports#getAll() ⇒ Object

new EventMap()

provides an event bus for when properties of the underlying Map change.

EventMap.module.exports#on(event, callback) ⇒ Object

call the destroy() function ont he returned object to remove the event listener

Kind: static method of EventMap
Returns: Object - with the subscriber function, the event name, and a destroy function.

Param	Type	Description
event	String	'set'= after the property has been set
callback	function	notification channel

EventMap.module.exports#set(key, val, notify) ⇒ EventMap

call set() set the value for a given key in the map.

Kind: static method of EventMap
Returns: EventMap - this eventmap instance.

Param	Type	Description
key	String
val	Object | Array
notify	Boolean	set false to NOT notify subscribers.

EventMap.module.exports#replace(keyValuePairs, notify) ⇒ EventMap

call replace() to replace the existing state.

Kind: static method of EventMap
Returns: EventMap - this eventmap instance.

Param	Type	Description
keyValuePairs	Object
notify	Boolean	set false to NOT notify subscribers.

EventMap.module.exports#del(key, notify) ⇒ EventMap

call del() to remove a value from the map.

Kind: static method of EventMap
Returns: EventMap - this eventmap instance.

Param	Type	Description
key	*	the key to remove from the map.
notify	Boolean	set false to NOT notify subscribers.

EventMap.module.exports#clear(notify) ⇒ Object

call clear() to remove all the key/value entries from the map.

Kind: static method of EventMap
Returns: Object - object hash of all the key value pairs.

Param	Type	Description
notify	Boolean	set false to NOT notify subscribers.

EventMap.module.exports#getAll() ⇒ Object

call getAll() to retrieve the current set of key/value pairs.

Kind: static method of EventMap
Returns: Object - object hash of all the key value pairs.

I18nMessage

Kind: global class

new I18nMessage(key, values, dataAttributes)

HTML element. Provides tranlsation and interpolation for translatable strings

Param	Type	Description
key	String	the key for the strings based on current language. can be set as the innerHTML or defined as the attibutes: key, id, data-key, data-id
values	JSON	can be passed as data-* attributes or as a json-parseable object string as "data-values"
dataAttributes	String

Example (Given the following configuration)

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
 'translatable.message.name': "I'm a translated string from i18n",
  'tokenized.message': "I have a ${color} ${animal}"
});

Example (With the following usage)

<i18n-message>translatable.message.name</i18n-message>
<div>
   <i18n-message data-values="{'color: 'grey', 'animal': 'monkey'}">tokenized.message</i18n-message>
   <i18n-message data-color="grey" data-animal="monkey">tokenized.message</i18n-message>
   <i18n-message key="tokenized.message"/>
   <!-- React does not pass key or ref props so you can use "data-key" or "data-id" as well-->
   <i18n-message data-key="tokenized.message"/>
   <i18n-message id="translatable.message.name"/>
   <i18n-message data-id="translatable.message.name"/>
</div>

Example (Renders the HTML)

<i18n-message>I'm a translated string from i18n</i18n-message>
<i18n-message>I have a grey monkey</i18n-message>

I18n

Kind: global class

• I18n
  • new I18n()
  • .getLang() ⇒ String
  • .setLang(lang)
  • .getMessages() ⇒ String
  • .setMessages(values)
  • .addMessages(lang, strings)
  • .get(key, data) ⇒ String
  • .getAll(namespace) ⇒ Object

new I18n()

Import strings here and call I18n.addStrings() with the supported locale identifier and the strings object exported from the language file By default, it will set the values on window.i18n, if defined when loaded, as the starting messages. This is useful if you wish to server-side render HTML certain content before laoding scripts on the client.

Example

import { I18n } from '@ornery/web-components';

I18n.addMessages('en-US', {
    'translatable.message.name': "I'm a translated string from i18n",
    'tokenized.message': "I have a ${this.color} ${this.animal}"
});

Example

window.i18n = {
    'en-US': {
        'translatable.message.name': "I'm a translated string from i18n",
        'tokenized.message': "I have a ${this.color} ${this.animal}"
    }
}

import { I18n } from '@ornery/web-components';

console.log(I18n.getMessages()) // will log the window.i18n object

I18n.getLang() ⇒ String

returns the current language. defaults to the browser's navigator.language value.

Kind: static method of I18n
Returns: String - lang
Example

navigator.language = 'en-US';
import { I18n } from '@ornery/web-components';

console.log(I18n.getLang()) // "en-US"

I18n.setLang(lang)

sets the current i18n language. This does not change the browser language.

Kind: static method of I18n

Param	Type
lang	String

Example

import { I18n } from '@ornery/web-components';

I18n.setLang('en-US')
console.log(I18n.getLang()) //'en-US'

I18n.getMessages() ⇒ String

returns the current i18n messages set in the DataManager

Kind: static method of I18n
Returns: String - lang

I18n.setMessages(values)

sets the strings as a whole. This overrides all existing strings. Use addMessages to add more strings to the existing set.

Kind: static method of I18n

Param	Type
values	Object

Example

import { I18n } from '@ornery/web-components';

I18n.setMessages({
    'en-US': {
        'translatable.message.name': "I'm a translated string from i18n",
        'tokenized.message': "I have a ${this.color} ${this.animal}"
    }
})

I18n.addMessages(lang, strings)

add more strings to the existing language set.

Kind: static method of I18n

Param	Type
lang	String
strings	Object

Example

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
 'translatable.message.name': "I'm a translated string from i18n",
  'tokenized.message': "I have a ${color} ${animal}"
});

I18n.get(key, data) ⇒ String

Returns the value for the key. If a context is provided as the second argument for tokens, the tokens will be replaced in the returned string.

Kind: static method of I18n
Returns: String - Returns the value for the key. Processed if a data context is provided as the second argument.

Param	Type	Description
key	String	they key of the string to retrieve from the current language set.
data	Object	Optional, The data to process tokens in the string with.

Example

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
  'tokenized.message': "I have a ${color} ${animal}"
});

const stringTestData = {
    color: "grey",
    animal: "monkey"
};
console.log(I18n.get('tokenized.message', stringTestData)) // "I have a grey monkey"

I18n.getAll(namespace) ⇒ Object

If a namespace is provided, returns all the key value pairs for that namespace without the namespace in the keys.

Kind: static method of I18n
Returns: Object - Returns all the messages for the given language. Filtered to namespace if provided.

Param	Type
namespace	String

Example

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
 'translatable.message.name': "I'm a translated string from i18n",
  'tokenized.message': "I have a ${color} ${animal}"
});

console.log(I18n.getAll('tokenized')) // {"message": "I have a ${color} ${animal}"}

bindEvents(root, context) ⇒ HTMLElement

helper function used by the loader when importing html files as a template fucntion for using attributes such as "onclick" within your html templates. You do not need to call this yourself if you are importing your html files using the loader

Kind: global function
Returns: HTMLElement - the root element passed in.

Param	Type	Description
root	HTMLElement	The root element to find all elements from.
context	Object	the context object for finding functions to bind against. default is the root element

Example

The event handler method signature is the exact same as standard HTML5 event handlers.
[standard HTML5 event handlers](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener).

Supported html5 events:
[onabort], [onafterprint], [onbeforeonload], [onbeforeprint], [onblur], [oncanplay], [oncanplaythrough], [onchange],
[onclick], [oncontextmenu], [ondblclick], [ondrag], [ondragend], [ondragenter], [ondragleave], [ondragover],
[ondragstart], [ondrop], [ondurationchange], [onemptied], [onended], [onerror], [onfocus], [onformchange],
[onforminput], [onhaschange], [oninput], [oninvalid], [onkeydown], [onkeypress], [onkeyup], [onload], [onloadeddata],
[onloadedmetadata], [onloadstart], [onmessage], [onmousedown], [onmousemove], [onmouseout], [onmouseover],
[onmouseup], [onmousewheel], [onoffline], [ononline], [onpagehide], [onpageshow], [onpause], [onplay], [onplaying],
[onpopstate], [onprogress], [onratechange], [onreadystatechange], [onredo], [onresize], [onscroll], [onseeked],
[onseeking], [onselect], [onstalled], [onstorage], [onsubmit], [onsuspend], [ontimeupdate], [onundo], [onunload],
[onvolumechange], [onwaiting]

Example

// By using the provided htmlLoader, you can use the ES6 template-literal syntax in on* HTML5 event attributes
<mwc-button onclick="${this.itemClick}" label="${props.text}"></mwc-button>
// If you are not using the loader, use the string name of the function to execute
// that is present on the custom element using the template
<mwc-button onclick="itemClick"></mwc-button>
// you can also use "this."
<mwc-button onclick="this.itemClick"></mwc-button>
// you can also refence properties of a member."
<mwc-button onclick="this.someObj.itemClick"></mwc-button>

Example

<!-- list.html: -->
<p id="selected-item-text" style="display:${props.selectedItemText ? 'block' : 'none'};">
  ${props.selectedItemText}
</p>
<mwc-formfield id="input-label" alignEnd label="${this.inputLabel}">
  <input onkeyup="${this.onInputKeyUp}" type="text">
</mwc-formfield>
<div>
  <mwc-button id="add-item" onclick="${this.clickHandler}" disabled="disabled">${this.buttonLabel}</mwc-button>
</div>
<ul>
  ${this.items.map((text) => {
    return `<li><mwc-button onclick="${this.itemClick}" label="${text}"></mwc-button></li>`
  }).join("")}
</ul>

Example

// define your custom element.
export default class ListComponent extends HTMLElement {
  constructor(self) {
    super(self);
    self = this;
    // use the shadow dom for best results.
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
      this.shadowRoot.innerHTML = "";
      listTemplate({
          // the html template loader will wire up the event handlers for you if you have defined them in your HTML
          onInputKeyUp: () => console.log("input contents changed:", this),
          itemClick: () =>  console.log("item clicked: ", this),
          clickHandler: () =>  console.log("button clicked: ", this),
          selectedItemText: this.getAttribute('selected-item'),
          inputLabel: buttonLabelBlank,
          buttonLabel: "add item to list."
     }).forEach((node) => this.shadowRoot.appendChild(node));
  }
}
customElements.define('list-component', MainComponent);

getFromObj(path, obj, fb) ⇒ * | String

Returns the value of an object via the path as a string

Kind: global function
Returns: * | String - whatever the value from the nested key path is or the default string '${path}'.

Param	Type	Description
path	String
obj	Object	Object to find the property in
fb	String	Fallback string when not found

Example

let result = getFromObj('hello.foo', {
 hello: {
   foo: 'bar'
 }
});

result == 'bar';

template(tmpl, map, fallback) ⇒ * | String

Processes a string formatted like an ES6 template against an object

Kind: global function
Returns: * | String - whatever the value from the nested key path is or the default string '${path}'.

Param	Type	Description
tmpl	String	the string template
map	Object	Key/Value pairs to process the string against
fallback	String	they string fallback when the value is missing.

Example

let result = template('I am a string literal formatted ${message.label}.', {
 message: {
   label: 'to look like an ES6 template'
 }
});

result == 'I am a string literal formatted to look like an ES6 template.';

stripES6(expr, context) ⇒ String

removes the ${} wrapping from an es6 template literal expression.

Kind: global function
Returns: String - The cleaned sxpression without the ${}.

Param	Type	Description
expr	String	The es6 expression
context	Options | Object	the context object to find values for tokens.

arrayParser(val, key, params) ⇒ Boolean

In the event that the search string has multiple values with the same key it will convert that into an array of those values for the given key.

While there is no defined standard in RFC 3986 Section 3.4, most web frameworks accept and serialize them in the following manner as outlined in MSDN

Kind: global function
Returns: Boolean - returns the currently parsed value.

Param	Type	Description
val	Object	the value to parse
key	String	the name of the value to parse
params	Object	all of the parameters that have been parsed so far.

Example

window.location.search = '?values=foo&values=bar&values=hello&values=world';
const params = toParams(window.location.search, {});
console.log(params) // {values: ["foo","bar","hello", "world"]}

Example

window.location.search = '?values=1&values=2&values=3&values=5&values=7';
const params = toParams(window.location.search, {
    values: parseInt
});
console.log(params) // {values: [1, 2, 3, 5, 7]}

Example

window.location.search = '?answer=42';
const params = toParams(window.location.search, {
    answer: parseInt
});
console.log(params) // {answer: 42}

toParams(str, options) ⇒ Object

Converts URL parameters to a Object collection of key/value pairs Decodes encoded url characters to back to normal strings.

Kind: global function
Returns: Object - seach params as an object

Param	Type	Description
str	String
options	Object	custom parser functions based on the key name

Example (convert query string to object:)

import {toParams} from '@ornery/web-components';
let paramsObject = toParams('?foo=bar&hello=world&hello=array&unsafe=I%20am%20an%20unsafe%20string');

console.log(paramsObject) // { foo: 'bar', hello: ['world', 'array'], unsafe: 'I am an unsafe string'}

Example (pass an optional parser object)

import {toParams} from '@ornery/web-components';
let paramsObject = toParams('?intvals=1&intvals=2&intvals=3', {
    intvals: parseInt
});

console.log(paramsObject) // { intvals: [ 1, 2, 3 ] }

Example (without psassing an optional parser object)

import {toParams} from '@ornery/web-components';
let paramsObject = toParams('?intvals=1&intvals=2&intvals=3');

console.log(paramsObject) // { intvals: [ "1", "2", "3" ] }

toSearch(options, base) ⇒ String

Converts an Object of String/Value pairs to a query string for URL parameters prepended with the "base" character. Encodes unsafe url characters to url safe encodings.

Kind: global function
Returns: String - the object represented as a query string.

Param	Type
options	Object
base	String

Example (convert object to query string)

import {toSearch} from '@ornery/web-components';
let queryString = toSearch({
 foo: 'bar',
 hello: ['world', 'array'],
 unsafe: 'I am an unsafe string'

}, '#');

queryString == '#?foo=bar&hello=world&hello=array&unsafe=I%20am%20an%20unsafe%20string';

prefixKeys(obj, prefix) ⇒ Object

Convenience method that converts the keys of an object to have a prefix. This is faster than stringification.

Kind: global function
Returns: Object - The new object with transformed keys.

Param	Type
obj	Object
prefix	String

Example

import {prefixKeys} from '@ornery/web-components';
let newObj = prefixKeys({
 foo: 'bar',
 hello: ['world', 'array'],
 unsafe: 'I am an unsafe string'

}, 'zoo-');

newObj == {
  'zoo-foo': 'bar',
  'zoo-hello': ['world', 'array']',
  'zoo-unsafe': 'I am an unsafe string'
};

toDataAttrs(obj, stringify) ⇒ Object

Convenience method that wraps prefixKeys with 'data-' for easier property spreading within other frameworks such as react. This is preferrable over stringifying objects as parsing json is slow in the browser

Kind: global function
Returns: Object - The new object with transformed keys.

Param	Type	Description
obj	Object
stringify	Boolean	wether or not to stringify the values for each key.

Example (React example)

const stringTestData = {
 color: "black and white",
 animal: "panda"
};

const MyComponent = (props) => {
  const dataAttrs = toDataAttrs(stringTestData);
  return (<div>
    <div>
      <i18n-message
        data-key="tokenized.message"
        {...dataAttrs}/>
    </div>
    <div>
      <i18n-message
        data-id="tokenized.message"
        {...dataAttrs}
        data-color="red"/>
    </div>
  </div>);
};

const dataAttrs = toDataAttrs(stringTestData);