@ornery/web-components

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

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.

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.

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

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.

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

DataStore.setState(newState) ⇒ Object | *

wraps this.set

Kind: static method of DataStore

DataStore.subscribe(callback) ⇒ Object | *

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

Kind: static method of DataStore

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

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

Kind: static method of DataStore

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.

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.

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

call replace() to replace the existing state.

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

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.

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.

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

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

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

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

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.

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.

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.

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}'.

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}'.

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 ${}.

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.

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

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.

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.

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.

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);