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 [email protected] 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'
}