awesome-webcomponents

awesome : object

Awesome-Webcomponents

Awesome ES6 compliant web componants for use in your app or website.

Tested and working on :

• Chrome
• Chromium
• Android Chrome
• FireFox >=45
• IE Edge
• Electron
• NW.js

Firefox >=45 supports evrything needed with the included ./bower_components/document-register-element/build/document-register-element.js. IE Edge Array.prototype.includes polyfill is build into awesome.js

install awesome-webcomponents via bower for your project by running bower install awesome-webcomponents don't forget to run bower update on occasion to get the latest version!

Working Component Examples and Demos

awesome-webcomponents on github.io

Licensed under DBAD license

See the DBAD license in your language or our licence.md file.

Contributing

1. Fork the repo
2. Do awesome stuff!
3. Submit a Pull Request
4. Feel Awesome!

Awesome.js Class api

window.awesome = new Awesome; is called automatically to instantiate a global awesome object for your use right away.

---

Kind: global namespace
Properties

Name	Type	Description
awesome.path	String	Path to folder awesome.js is located in
awesome.bower	String	path to bower components
constants	Object	awesome constants
constants.components	ShallowMergeObject	shallow merge for awesome.constants.components
constants.stores	ShallowMergeObject	shallow merge for awesome.constants.stores
constants.actions	ShallowMergeObject	shallow merge for awesome.constants.actions
config	DeepMergeObject	deep recursive merge for awesome config object
language	Object	awesome language objects
language.default	Object	awesome default language object
language.current	Object	awesome language object merged default and desiredLanguage
language.*	Object	awesome language objects for specific languages like awesome.language.en or awesome.language.ru
setLanguage	function	set the current language
dynamicLanguageString	function	a way to pass variables to language strings. This is helpful when you support languages with a variety of grammatical structures
dispatchers	Object	dispatchers for store/action/component messages
stores	Object	registered awesome.Store instances. These are designed to support 1 way data flows for use by components
Store	Class	Store class, used to create new stores
loadTemplate	function	fetches nested template contents for inclusion in awesome-component
requireScript	function	inject script tag into header
requireCSS	function	inject stylesheet link tag into header
mergeDataset	function	merges element's data-* attributes with the defaults for that component element
updateAttributesFromData	function	maps data-* values to * attribute values
uniqueEntries	function	ensures that keys and values of an object unique

• awesome : object
  • .Store
    • .state : Object
    • .defaultState : Object
    • .ignoreResetEvent : Boolean
    • .expose(instance, name)
    • .resetState(events)
    • "change"
  • .path : String
  • .constants : Object
    • .action : Object
      • .RESET_STORES : EventName
      • .FILE_LOADED : String
      • .LOGOUT_REQUEST : EventName
      • .LOGIN_REQUEST : EventName
      • .getter() ⇒ ActionConstants
      • .setter(constants) ⇒ ActionConstants
    • .store : Object
      • .RESET : EventName
      • .LOGIN_ERROR : EventName
      • .LOGOUT_ERROR : EventName
      • .LOGIN_SUCCESS : EventName
      • .LOGOUT_SUCCESS : EventName
      • .FILE_LIST : String
      • .getter() ⇒ StoreConstants
      • .setter(constants) ⇒ StoreConstants
    • .component : Object
      • .VALIDATE_USERNAME : EventName
      • .VALIDATE_EMAIL : EventName
      • .VALIDATE_URL : EventName
      • .getter() ⇒ ComponentConstants
      • .setter(constants) ⇒ ComponentConstants
  • .config : Object
    • .setter() ⇒ Object
  • .language : Object
  • .dispatchers : Object
    • .action : EventEmitter
    • .component : EventEmitter
    • .store : EventEmitter
  • .stores : Object
  • .bower : String
  • .loadTemplate(instance) ⇒ Object
  • .requireScript(path) ⇒ Boolean
  • .requireScript(path) ⇒ Boolean
  • .requireCSS(path) ⇒ Boolean
  • .mergeDataset(el, defaults)
  • .updateAttributesFromData(el, key, value) ⇒ HTMLElement
  • .uniqueEntries(data) ⇒ Boolean
  • "awesome-language-set" (e)
  • "awesome-script-loaded" (e)
  • "awesome-script-error" (e)
  • "awesome-language-loaded" (e)
  • "awesome-ready"
  • "awesome-wants-lang" (e)

awesome.Store

Kind: static class of awesome
Properties

Name	Type	Description
state	Object	state data of store exposed for reading by components via expose. The store modifies this as a shallow merge Object.
defaultState	Object	default store state
ignoreResetEvent	Boolean	flag to ignore the global reset event USE WITH CAUTION
resetState	function	rests the store state
expose	function	registers the read-only state with awesome.stores[store name] for components to use

• .Store
  • .state : Object
  • .defaultState : Object
  • .ignoreResetEvent : Boolean
  • .expose(instance, name)
  • .resetState(events)
  • "change"

Store.state : Object

state data of store exposed for reading by components via expose. The store modifies this as a shallow merge Object.

Kind: static property of Store
Access: protected
Example

//set the store state with a shallow merge
 myStoreState = {
  	property: 'prop'
 }
 store.state = myStoreState;

//get the store state
 const state = store.state

Store.defaultState : Object

default store state

Kind: static property of Store
Example

//set your default store
store.defaultState = {
 	defaultProperty1: 'red',
 	defaultProperty2: 'white',
 	defaultPropertyN: 'mandalorian'
}

Store.ignoreResetEvent : Boolean

flag to ignore the global reset event USE WITH CAUTION

Kind: static property of Store
Example

//ignore the global reset event
 store.ignoreResetEvent = true;

Store.expose(instance, name)

registers the read-only state with awesome.stores[store name] for components to use

Kind: static method of Store

Param	Type	Description
instance	Store	your instantiated Store instance
name	String	The name of your store

Example

//expose your store
store.expose(yourStoreScope, 'yourStoreName');

Store.resetState(events)

rests the store state

Kind: static method of Store

Param	Type	Description
events	Object	your stores event-pubsub instance

Example

//reset the store state
store.resetState();

"change"

Store.state change event used to notify component that the store state has changed.

Kind: event emitted by Store

awesome.path : String

Path to folder awesome.js is located in.

Kind: static property of awesome
Access: protected
Example

//use awesome.path to reference the awesome-webcomponents directory
awesome.requireCSS(`${awesome.path}components/buttons/awesome-buttonset.css`);
awesome.requireScript(`${awesome.path}components/buttons/awesome-buttonset.js`);

awesome.constants : Object

extensible/overwriteable constansts used in awesome apps

Kind: static property of awesome
Properties

Name	Type	Description
action	Object	action constants
store	Object	store constants
component	Object	component constants

• .constants : Object
  • .action : Object
    • .RESET_STORES : EventName
    • .FILE_LOADED : String
    • .LOGOUT_REQUEST : EventName
    • .LOGIN_REQUEST : EventName
    • .getter() ⇒ ActionConstants
    • .setter(constants) ⇒ ActionConstants
  • .store : Object
    • .RESET : EventName
    • .LOGIN_ERROR : EventName
    • .LOGOUT_ERROR : EventName
    • .LOGIN_SUCCESS : EventName
    • .LOGOUT_SUCCESS : EventName
    • .FILE_LIST : String
    • .getter() ⇒ StoreConstants
    • .setter(constants) ⇒ StoreConstants
  • .component : Object
    • .VALIDATE_USERNAME : EventName
    • .VALIDATE_EMAIL : EventName
    • .VALIDATE_URL : EventName
    • .getter() ⇒ ComponentConstants
    • .setter(constants) ⇒ ComponentConstants

constants.action : Object

Shallow merge action constants object

Kind: static property of constants

• .action : Object
  • .RESET_STORES : EventName
  • .FILE_LOADED : String
  • .LOGOUT_REQUEST : EventName
  • .LOGIN_REQUEST : EventName
  • .getter() ⇒ ActionConstants
  • .setter(constants) ⇒ ActionConstants

action.RESET_STORES : EventName

all stores should reset their state

Kind: static property of action

action.FILE_LOADED : String

files loaded and available

Kind: static property of action

action.LOGOUT_REQUEST : EventName

logout request

Kind: static property of action
Memeber: awesome.constants.action.LOGOUT_REQUEST

action.LOGIN_REQUEST : EventName

login request

Kind: static property of action
Memeber: awesome.constants.action.LOGIN_REQUEST

action.getter() ⇒ ActionConstants

action constants getter

Kind: static method of action
Returns: ActionConstants - action constants
Access: protected

action.setter(constants) ⇒ ActionConstants

action constants setter : merges the current action constants and the new constants via shallow merge.

Kind: static method of action
Returns: ActionConstants - actions merged constants
Access: protected

Param	Type	Description
constants	Object	constants to merge

Example

//original constants
{
 	ACTION_CONSTANT1: 'actionConst1',
 	ACTION_CONSTANT2: 'actionConst2',
}
myNewConstants = {
 	NEW_CONSTANT_1: 'const1',
 	NEW_CONSTANT_2: 'const2'
}

awesome.action.constants = myNewConstants;

//action constants will now be
//awesome.constants.action
{
 	ACTION_CONSTANT1: 'actionConst1',
 	ACTION_CONSTANT2: 'actionConst2',
 	NEW_CONSTANT_1: 'const1',
 	NEW_CONSTANT_2: 'const2'
}

constants.store : Object

Shallow merge store constants object

Kind: static property of constants

• .store : Object
  • .RESET : EventName
  • .LOGIN_ERROR : EventName
  • .LOGOUT_ERROR : EventName
  • .LOGIN_SUCCESS : EventName
  • .LOGOUT_SUCCESS : EventName
  • .FILE_LIST : String
  • .getter() ⇒ StoreConstants
  • .setter(constants) ⇒ StoreConstants

store.RESET : EventName

all stores should reset their state

Kind: static property of store

store.LOGIN_ERROR : EventName

user supplied bad credentials

Kind: static property of store

store.LOGOUT_ERROR : EventName

there was an error logging out

Kind: static property of store

store.LOGIN_SUCCESS : EventName

login was successful

Kind: static property of store

store.LOGOUT_SUCCESS : EventName

logout was successful

Kind: static property of store

store.FILE_LIST : String

file list available

Kind: static property of store

store.getter() ⇒ StoreConstants

store constants getter

Kind: static method of store
Returns: StoreConstants - store constants
Access: protected

store.setter(constants) ⇒ StoreConstants

action constants setter : merges the current store constants and the new constants via shallow merge.

Kind: static method of store
Returns: StoreConstants - stores merged constants
Access: protected

Param	Type	Description
constants	Object	constants to merge

Example

//original constants
{
 	STORE_CONSTANT1: 'actionConst1',
 	STORE_CONSTANT2: 'actionConst2',
}

myNewConstants = {
 	NEW_CONSTANT_1: 'const1',
 	NEW_CONSTANT_2: 'const2'
}

awesome.constantants.store = myNewConstants;

//action constants will now be
//awesome.constants.store
{
 	STORE_CONSTANT1: 'actionConst1',
 	STORE_CONSTANT2: 'actionConst2',
 	NEW_CONSTANT_1: 'const1',
 	NEW_CONSTANT_2: 'const2'
}

constants.component : Object

Shallow merge constants constants object *

Kind: static property of constants

• .component : Object
  • .VALIDATE_USERNAME : EventName
  • .VALIDATE_EMAIL : EventName
  • .VALIDATE_URL : EventName
  • .getter() ⇒ ComponentConstants
  • .setter(constants) ⇒ ComponentConstants

component.VALIDATE_USERNAME : EventName

regular expression for validating user name

Kind: static property of component
Memeber: awesome.constants.component.VALIDATE_USERNAME
Example

const constanst = awesome.constansts.components;

//input pattern for a valid username, alphanumeric
<input class = 'yourUserNameInput'
 	pattern = constansts.VALIDATE_EMAIL
></input>
// a user submission of userName will not be accepter but rather userName@group would

component.VALIDATE_EMAIL : EventName

regular expression for validating user email

Kind: static property of component
Memeber: awesome.constansts.component.VALIDATE_EMAIL
Example

const constanst = awesome.constansts.components;

//input patter for a valid email address, alphanumeric
<input class = 'yourEmailInput'
 	pattern = constansts.VALIDATE_EMAIL
></input>
// an email submission of user@site will not be accepted but rather [e-mail] would

component.VALIDATE_URL : EventName

regular expression for validating url

Kind: static property of component
Memeber: awesome.constansts.component.VALIDATE_URL
Example

const constanst = awesome.constansts.components;

//input pattern for a valid url
<input
 	pattern = constansts.VALIDATE_URL
></input>
// a url submission of www.nodejs.org would not be accepter but rather
// https://nodejs.org or http://www.yourSite.yourDomain

component.getter() ⇒ ComponentConstants

component constants getter

Kind: static method of component
Returns: ComponentConstants - component constants
Access: protected

component.setter(constants) ⇒ ComponentConstants

component constants setter : merges the current component constants and the new constants via shallow merge.

Kind: static method of component
Returns: ComponentConstants - components merged constants
Access: protected

Param	Type	Description
constants	Object	constants to merge

Example

//original constants
{
 	COMPONENT_CONSTANT1: 'actionConst1',
 	COMPONENT_CONSTANT2: 'actionConst2',
}

myNewConstants = {
 	NEW_CONSTANT_1: 'const1',
 	NEW_CONSTANT_2: 'const2'
}

awesome.constants.components = myNewConstants;

//action constants will now be
//awesome.constants.component
{
 	COMPONENT_CONSTANT1: 'actionConst1',
 	COMPONENT_CONSTANT2: 'actionConst2',
 	NEW_CONSTANT_1: 'const1',
 	NEW_CONSTANT_2: 'const2'
}

awesome.config : Object

extensible/overwriteable constansts used in awesome apps

Kind: static property of awesome

config.setter() ⇒ Object

Deep merge config object

Kind: static method of config
Returns: Object - awesome.config
Example

// awesome.config could be
{
    a:1,
    b:{
        c:3
    },
    d:{
        e:55,
        f:{
            g:99
        }
    },
    q:{
        r:77
    }
}

awesome.configMerge(
    {
        b:{
            x:{
                y:{
                    z:99999
                }
            }
        },         *
        d:{
            f:{
                h:55
            }
        },
        q:33
    }
)


//now awesome.config would look like
{
    a:1,
    b:{
        c:3
            x:{
                y:{
                    z:99999
                }
            }
        }
    },
    d:{
        e:55,
        f:{
            g:99,
            h:55
        }
    },
    q:33
}

awesome.language : Object

language objects used by awesome components

Kind: static property of awesome

awesome.dispatchers : Object

dispatchers for awesome 1 way data flow

Kind: static property of awesome
Access: protected
Properties

Name	Type	Description
action	Object	action dispatcher
store	Object	store dispatcher
component	Object	component dispatcher

• .dispatchers : Object
  • .action : EventEmitter
  • .component : EventEmitter
  • .store : EventEmitter

dispatchers.action : EventEmitter

awesome dispatcher for actions, uses event-pubsub

Kind: static property of dispatchers
Properties

Name	Type	Description
on	function	binds handler to action event
off	function	unbinds handler from action event
trigger	function	fires store event

Example

const dispatcher = awesome.dispatchers.action;
const constants = awesome.constants;

//trigger an event to store
dispatcher.trigger(
 	constants.store.YOUR_STORE_CONSTANT,
 	{
 		data1 : 'data1',
 		data2 : 'data2'
 	}
);

//listen to an event from a component
dispatcher.on(
 	constants.components.YOUR_COMPONENT_CONSTANT,
 	yourHanderFunction
);

//stop listening to the event
dispatcher.off(
 	constants.components.YOUR_COMPONENT_CONSTANT,
 	yourHanderFunction
);

dispatchers.component : EventEmitter

awesome dispatcher for components, uses event-pubsub

Kind: static property of dispatchers
Properties

Name	Type	Description
trigger	function	fires action event

Example

const dispatcher = awesome.dispatcher.component;
const constants = awesome.constants;

//trigger an event to action
dispatcher.trigger(
 	constants.action.YOUR_COMPONENT_CONSTANT,
 	{
 		data1 : 'data1',
 		data2 : 'data2'
 	}
);

dispatchers.store : EventEmitter

awesome dispatcher for stores, uses event-pubsub

Kind: static property of dispatchers
Properties

Name	Type	Description
on	function	binds handler to store events
off	function	unbinds handler from store event
events	function	fires event

Example

const dispatcher = awesome.dispatcher.store;
const constants = awesome.constants;

//listen to an event from an action
dispatcher.on(
 	constants.action.YOUR_STORE_CONSTANT,
 	yourHanderFunction
);

//stop listening to the event
 dispatcher.off(
 	constants.components.YOUR_STORE_CONSTANT,
 	yourHanderFunction
);

awesome.stores : Object

awesome 1 way data flow stores for use by component

Kind: static property of awesome
Example

state=awesome.stores.auth.state;

state.on(
  	'change',
  	this.yourAwesomeUpdateHandler.bind(this)
);

awesome.bower : String

Path to bower components

Kind: static property of awesome
Access: protected
Example

//include bower components using the bower components path
awesome.requireScript(`${awesome.bower}bower-component/bower-component.js`);

awesome.loadTemplate(instance) ⇒ Object

loadTemplate collects template element and returns element

Kind: static method of awesome
Returns: Object - contents of template element
Access: protected

Param	Type	Description
instance	Object	instance or scope of template element

Example

//taken from awesome-list example, loadTemplate will load template element of awesome-component
//and returns element

//html snippet

 <awesome-list>
       <template>
           <li>
               Test 1
           </li>
           <li>
               Test 2
           </li>
           <li>
               Test 3
           </li>
       </template>
   </awesome-list>

//js

const content=awesome.loadTemplate(this);

//constents of content
       `<li>
           Test 1
       </li>
       <li>
           Test 2
       </li>
       <li>
           Test 3
       </li>`

//usage
//this content can now be loaded into awesome-list

this.innerHTML=`
    <ul>
        ${content}
    </ul>
`;

awesome.requireScript(path) ⇒ Boolean

requireScript appends scripts to the docuyment head with a differed false

Kind: static method of awesome
Returns: Boolean - true
Access: protected

Param	Type	Description
path	String	path to script

Example

//here we require the dispatcher to action and the constants to stores and actions
awesome.requireScript(`${awesome.path}dispatchers/action.js`);
awesome.requireScript(`${awesome.path}actions/constants.js`);
awesome.requireScript(`${awesome.path}stores/constants.js`);

awesome.requireScript(path) ⇒ Boolean

requireLanguage includes js scripts into document

Kind: static method of awesome
Returns: Boolean - true
Access: protected

Param	Type	Description
path	String	path to script

awesome.requireCSS(path) ⇒ Boolean

requireCSS requires and appends scripts to CSS head

Kind: static method of awesome
Returns: Boolean - false if stylesheet has already been loaded into document

Param	Type	Description
path	String	Path to CSS stylesheet

Example

//require any CSS to script
awesome.requireCSS(`${awesome.path}components/your-component/your-component.css`);

awesome.mergeDataset(el, defaults)

mergeDataset merges element's dataset to current default dataset of document

Kind: static method of awesome

Param	Type	Description
el	HTMLElement	element with dataset to be merged
defaults	Object	default dataset

Example

defaultElementDataset = {
 	property1: 'one',
 	property2: 'two'
}

function componentCreatedCallback(componentDataset){
		mergeDataset(myElement, componentDataset);
}

//after the component is created it will contain
//ElementDataset
 {
 	property1 : 'newProp1',
 	property2 : 'newProp2'
 }

awesome.updateAttributesFromData(el, key, value) ⇒ HTMLElement

updateAttributesFromData updates an element's attributes

Kind: static method of awesome
Returns: HTMLElement - updated element object

Param	Type	Description
el	HTMLElement	element object
key	String	key of element
value	String	value to update data to

Example

//orginal element attributes
{
 	attribute1 : 'green',
 	attribute2 : 'red',
 	attribute3 : 'white'
}

yourElementAttributeUpdater(element, attribute3, black);

function yourElementAttributeUpdater(element, elementKey,newValue){
 	awesome.updateAttributesFromData(element, elementKey, newValue);
}

//resulting element attributes
{
 	attribute1 : 'green',
 	attribute2 : 'red',
 	attribute3 : 'black'
}

awesome.uniqueEntries(data) ⇒ Boolean

uniqueEntries ensures that keys and values of data array are unique

Kind: static method of awesome
Returns: Boolean - true

Param	Type	Description
data	Object	Data object or array with unique entries

Example

//check that your constants all have unique entries as they should
 const constans = awesome.constans;

awesome.uniqueEntries(constans.store);
awesome.uniqueEntries(constans.components);
awesome.uniqueEntries(constans.actions);

//if entires are not unique an error will be thrown
`duplicate key of yourKey const keys mist be unique!`
//or
`duplicate value of yourConstant found on yourKey and yourKeyDuplicate const value strings MUST be unique!`

"awesome-language-set" (e)

emitted when the language is set or changed via awesome.setLanguage.

Kind: event emitted by awesome

Param	Type	Description
e	Event	Event Data
e.detail	String	languageCode

"awesome-script-loaded" (e)

emitted when a script included via requireScript has completed loading a script.

Kind: event emitted by awesome

Param	Type	Description
e	Event	Event Data
e.detail	String	path of the loaded script

Example

window.on(
 	'awesome-script-loaded',
 	yourAwesomeLoadedHandler
);

"awesome-script-error" (e)

emitted when a script included via requireScript can NOT be loaded.

Kind: event emitted by awesome

Param	Type	Description
e	Event	Event Data
e.detail	String	path of the loaded script

"awesome-language-loaded" (e)

emitted when a new language file included via awesome.requireLanguage has completed loading.

Kind: event emitted by awesome

Param	Type	Description
e	Event	Event Data
e.detail	String	path of the loaded language

"awesome-ready"

emitted when all queued scripts included via requireScript have completed loading. This will fire each time awesome deems it is ready for use. So if you include more scripts long after load it will fire again once all the new scripts are loaded.

Kind: event emitted by awesome

"awesome-wants-lang" (e)

emitted when a language check is performed for the first time and the language script is NOT in the head. This is useful when you have your own language files to load.

Kind: event emitted by awesome

Param	Type	Description
e	Event	Event Data
e.detail	String	desired language code

setLanguage(languageCode)

Merge a specific language and the default languages. If the languageCode has not been populated on the awesome.language object, the awesome.language.default will be used.

Kind: global function

Param	Type	Description
languageCode	String	like 'en', 'en-US', 'es' or 'zh' etc.

Example

//if awesome.language.default is
{
    hello:'Hello',
    appName:'My Awesome App'
}

//and awesome.language.es is
{
    hello:'Ola'
}

awesome.setLanguage('es');

//will result in awesome.language.current being
{
    hello:'Ola',
    appName:'My Awesome App'
}