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!

$3

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)

$3

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
``javascript
//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
`javascript
//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
`javascript
//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
`javascript
//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
`javascript
//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



$3

Path to folder awesome.js is located in.

Kind: static property of awesome
Access: protected
Example
`javascript
//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);
`



$3

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
`javascript
//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
`javascript
//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
`javascript
const constanst = awesome.constansts.components;

//input pattern for a valid username, alphanumeric
pattern = constansts.VALIDATE_EMAIL
>
// 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
`javascript
const constanst = awesome.constansts.components;

//input patter for a valid email address, alphanumeric
pattern = constansts.VALIDATE_EMAIL
>
// an email submission of user@site will not be accepted but rather user@site.company would
`

##### component.VALIDATE_URL : EventName
regular expression for validating url

Kind: static property of component
Memeber: awesome.constansts.component.VALIDATE_URL
Example
`javascript
const constanst = awesome.constansts.components;

//input pattern for a valid url
pattern = constansts.VALIDATE_URL
>
// 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
`javascript
//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'
}
`



$3

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
`javascript

// 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
}


`



$3

language objects used by awesome components

Kind: static property of awesome

$3

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



$3

awesome 1 way data flow stores for use by component

Kind: static property of awesome
Example
`javascript
state=awesome.stores.auth.state;

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



$3

Path to bower components

Kind: static property of awesome
Access: protected
Example
`javascript
//include bower components using the bower components path
awesome.requireScript(${awesome.bower}bower-component/bower-component.js);
`



$3

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
`javascript
//taken from awesome-list example, loadTemplate will load template element of awesome-component
//and returns element

//html snippet





//js

const content=awesome.loadTemplate(this);

//constents of content


Test 1

Test 2

Test 3

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

this.innerHTML=

${content}

;
`

$3

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
`javascript
//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);
`



$3

requireLanguage includes js scripts into document

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

| Param | Type | Description |
| --- | --- | --- |
| path | String | path to script |

$3

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
`javascript
//require any CSS to script
awesome.requireCSS(${awesome.path}components/your-component/your-component.css);
`



$3

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
`javascript
defaultElementDataset = {
property1: 'one',
property2: 'two'
}

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

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



$3

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
`javascript
//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'
}
`



$3

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
`javascript
//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!
`



$3

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 |

$3

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
`javascript
window.on(
'awesome-script-loaded',
yourAwesomeLoadedHandler
);
`



$3

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 |

$3

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 |

$3

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

$3

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
`javascript
//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'
}

``