From 18912970613f82a45278cb4acc1362aef32bddfb Mon Sep 17 00:00:00 2001 From: Harry S Date: Tue, 21 Nov 2017 01:08:06 -0500 Subject: [PATCH] Update README.md --- README.md | 868 +++++++++++++++++++++++++++--------------------------- 1 file changed, 434 insertions(+), 434 deletions(-) diff --git a/README.md b/README.md index 40584df..8f5e455 100644 --- a/README.md +++ b/README.md @@ -1,434 +1,434 @@ -# CORE - -Core is a modular, scalable and concise frontend framework. It's main purpose is to manage modules, plugins and extensions. It ensures loose coupling of components and allows for the use whatever communication system you want; however, one is provide in the extras folder. - -### Advance Usage - -Fetch the project via git: - -`git clone https://github.com/harry-sm/CORE.git` - -Include in your project - -```html - -``` - -```html - -``` - -This library uses a variant of the naming convention known as [Hungarian Notation](https://en.wikipedia.org/wiki/Hungarian_notation) for variable names. Simply put the variable name is prefixed with the first letter of the data type the variable is. - -| Prefix | Data Type | Example | -| ------ | ---------- | -------- | -| s | string | sData | -| n | number | nData | -| a | array | aData | -| o | object | oData | -| $ | DOM object | $element | - -### Browser Support - -- IE9+ -- Chrome -- Firefox - -The parameter `$` used in the factory functions contains the DOM element that corresponds with the module ID and other module data along with the methods for any extensions and plugins specified. All dependencies are injected into each component when they are instantiated. - -> **NOTE: ** All modules are connected to a DOM element. - -| Parameter(object) | Defaults | Type | Description | -| ----------------- | ------------------------- | ---------------- | ---------------------------------------- | -| $ | domEl | [HTMLCollection] | The corresponding DOM element of the module name. | -| | find(sEl) | function | Gets the descendants of the module DOM element that matches the query. | -| | length | number | The number of elements that was returned from the DOM query. | -| | moduleIdentifier | string | The name of the module. | -| | plugin( sPluginID, oData) | function | Initialize any the plugin specified. | - -#### $.find(sEl) - -| Parameter | Type | Example | Description | -| --------- | ------ | --------------------- | ---------------------------------------- | -| sEl | string | '#id' of '.classname' | The selector string that will be queried against the DOM elements. | - - - -#### $.plugin( sPluginID, oData) - -| Parameter | Type | Example | Description | -| --------- | ------ | ----------- | ---------------------------------------- | -| sPluginID | string | 'accordion' | The name of the plugin. | -| oData | object | {data} | The data should be provided upon initialization of the plugin. | - - - -## Module Methods - -### CORE.module.create(sModuleID, aExtensions, fFn, aPlugins) - -This factory function registers a new module to CORE module management system. - -#### Parameters - -| Parameter | Type | Example | Description | -| ----------- | -------- | -------------------- | ---------------------------------------- | -| sModuleID | string | '#foo' | The module name which is use to query the DOM for corresponding element with an ID with the same name. | -| aExtensions | [string] | ['dom'] | An array containing the extension IDs of the module's dependencies. | -| fFn | function | function ($) { ... } | The function that contains the implementation details of the module. | -| aPlugins | [string] | ['myPlugin'] | An array containing the plugin IDs of the module's dependencies. | - -#### Return Type - -`void` - -#### Example - -```js -CORE.module.create('#foo', ['dom'], function ($) { - var $childElement = $.find('#foo-child'); - - return { - init: function() { - $.plugin('plugin', $); - }, - destroy: function () { - //body - } - }; -}, ['plugin']); -``` - -```html -
- ... -
-``` - - - -### CORE.module.start( sModuleID, oData ) -Starts the module by creating a new instance of it. - -#### Parameters - -| Parameter | Type | Example | Description | -| --------- | ------ | --------------------------- | ---------------------------------------- | -| sModuleID | string | '#foo' | The name of the module that should be instantiated. | -| oData | object | {
name: 'Harry'
} | Any data that should be consumes upon the module instantiation. The data is passed to the `init()` function of the module and is optional. | - -#### Return Type -`void` - -#### Example -```js -CORE.module.start('#foo'); -``` - -### CORE.module.stop( sModuleID ) -Stops the module by calling the destroy method and removing the instance from CORE. - -#### Parameters - -| Parameter | Type | Example | Description | -| --------- | ------ | ------- | ---------------------------------------- | -| sModuleID | string | '#foo' | The name of the module instance that should be destroyed. | - -#### Return Type -`void` - -#### Example -```js -CORE.module.stop('#foo'); -``` - - - -### CORE.module.startAll( aExcept ) -Start all modules except the ones specified. - -#### Parameters - -| Parameter | Type | Example | Description | -| --------- | -------- | -------- | ---------------------------------------- | -| aExcept | [string] | ['#bar'] | An array containing all the module IDs that should be instantiated. | - -#### Return Type -`void` - -#### Example -```js -CORE.module.startAll(); -``` - - - -### CORE.module.stopAll( aExcept ) -Stop all modules except the ones specified. - -#### Parameters - -| Parameter | Type | Example | Description | -| --------- | -------- | -------- | ---------------------------------------- | -| aExcept | [string] | ['#foo'] | An array containing all the module IDs that should not be instantiated. | - -#### Return Type -`void` - -#### Example -```js -CORE.module.stopAll(['#foo']); -``` - - - -### CORE.module.restart( aModuleID ) - -Stops and then starts modules. - -#### Parameters - -| Parameter | Type | Example | Description | -| --------- | -------- | -------- | ---------------------------------------- | -| aModuleID | [string] | ['#foo'] | The name of the module that should be restarted. | - -#### Return Type -`void` - -#### Example -```js -CORE.module.restart(['#foo']); -``` - - - -## Plugins -Plugins are reuseable behaviours that are used within the app, such as sliders, accordion and carousels. - - -### CORE.plugin.create( sPluginID, aExtensions, fFn ) -Registers plugins to CORE. - -#### Parameters - -| Parameter | Type | Example | Description | -| ----------- | -------- | -------------------- | ---------------------------------------- | -| sPluginID | string | 'accordion' | The name of the plugin. This should be unique. | -| aExtensions | [string] | ['dom', 'events'] | An array containing the extension IDs of the module's dependencies. | -| fFn | function | function ($) { ... } | The function that contains the implementation details of the plugin. | - -#### Return Type -`void` - -#### Example -```js -CORE.plugin.create('accordion', ['dom', 'events'], function( $ ) { - var - nPrev, - nIdx, - _$elem, - $accordionBtns - ; - - function selectAccordionContent (){ - nIdx = $.dom.index(this, $accordionBtns); - - if(nPrev === nIdx){ - $.dom.removeClass('current', $accordionBtns[nIdx]); - nPrev = null; - return; - } - $.dom.removeClass('current', $accordionBtns); - $.dom.addClass('current', $accordionBtns[nIdx]); - - nPrev = nIdx; - } - return { - init: function ($elem){ - _$elem = $elem; - $accordionBtns = _$elem.find('.accordion-btn'); - - $.events.on(_$elem, 'click', '.accordion-btn', selectAccordionContent); - }, - destroy: function (){ - $.events.off(_$elem, 'click', '.accordion-btn', selectAccordionContent); - } - }; -}); -``` - - - -#### Usage - -```html -
-
Accordian 1
-
-
- Content 1 -
-
-
Accordian 2
-
-
- Content 2 -
-
-
-``` - -```js -CORE.module.create('#accordian-element', ['dom'], function ($) { - return { - init: function() { - $.plugin('accordion', $); - }, - destroy: function () { - this.plugin = null; - } - }; - -}, ['accordion']); -``` - - - -## Extensions - -Extensions are third party functionality you want to inject into the module, such as DOM manipulation, DOM events and a messaging system like a mediator. - - -### CORE.extension.create( sExtensionID, fFn ) -Registers extensions to CORE. - -#### Parameters - -| Parameter | Type | Example | Description | -| ------------ | -------- | -------------------- | ---------------------------------------- | -| sExtensionID | string | 'dom' | The name of the extension. This should be unique. | -| fFn | function | function ($) { ... } | The function that contains the implementation details of the extension. | - -#### Return Type -`void` - -#### Example -```js -CORE.extension.create('dom', function ( oData ){ - return { - addClass: function (sClassName, $el) { - // body - }, - removeClass: function (sClassName, $el) { - // body - }, - toggleClass: function (sClassName, $el) { - // body - }, - hasClass: function (sClassName, $el) { - // body - }, - ... - }; -}); -``` - -#### Usage - -```js -CORE.module.create('#elem', ['dom'], function ($) { - return { - init: function() { - // adds css class hide to it's dom element. - $.dom.addClass('.hide', $); - }, - destroy: function () { - } - }; - -}); -``` - - - -## CORE - -####CORE.debug( bOption ) - -Logs warnings and errors about CORE's internal operations to the console. Default value: **true** - -####Parameters - -| Parameter | Type | Example | Description | -| --------- | ------- | ------- | ----------------------------- | -| bOption | boolean | true | Enable or disable debug mode. | - -#### Return Type - -`void` - -#### Example - -```js -CORE.debug(true) -``` - - - -#### CORE.log( nSeverity, sMsg ) - -Prints message to the console. - -####Parameters - -| Parameter | Type | Example | Description | -| --------- | ------ | ------------------- | ---------------------------------------- | -| nSeverity | number | 2 | Specifies the type of message that will be logged to the console. Options:
1: INFO
2: WARNING
3: ERROR | -| sMsg | string | 'This is a warning' | The message that should be logged to the console. | - -#### Return Type - -`void` - -#### Example - -```js -CORE.log(1, 'Normal message'); -CORE.log(2, 'Warning message'); -CORE.log(1, 'Error message'); -``` - - - -####CORE.extend( sExtensionID, fFn ) - -Extend adds additional functionality you want to the CORE object. - -#### Parameters - -| Parameter | Type | Example | Description | -| ------------ | -------- | -------------------- | ---------------------------------------- | -| sExtensionID | string | 'dom' | The name of the extension. This should be unique. | -| fFn | function | function ($) { ... } | The function that contains the implementation details of the extension. | - -#### Return Type - -`void` - -#### Example - -```js -CORE.extend('anything', function (){ - return { - method: function (arg){ - // body - } - }; - }); -``` - -#### Usage - -```js -CORE.anything.method(data); -``` +# CORE + +Core is a modular, scalable and concise frontend framework. It's main purpose is to manage modules, plugins and extensions. It ensures loose coupling of components and allows for the use whatever communication system you want; however, one is provide in the extras folder. + +### Advance Usage + +Fetch the project via git: + +`git clone https://github.com/harry-sm/CORE.git` + +Include in your project + +```html + +``` + +```html + +``` + +This library uses a variant of the naming convention known as [Hungarian Notation](https://en.wikipedia.org/wiki/Hungarian_notation) for variable names. Simply put the variable name is prefixed with the first letter of the data type the variable is. + +| Prefix | Data Type | Example | +| ------ | ---------- | -------- | +| s | string | sData | +| n | number | nData | +| a | array | aData | +| o | object | oData | +| $ | DOM object | $element | + +### Browser Support + +- IE9+ +- Chrome +- Firefox + +The parameter `$` used in the factory functions contains the DOM element that corresponds with the module ID and other module data along with the methods for any extensions and plugins specified. All dependencies are injected into each component when they are instantiated. + +> **NOTE: ** All modules are connected to a DOM element. + +| Parameter(object) | Defaults | Type | Description | +| ----------------- | ------------------------- | ---------------- | ---------------------------------------- | +| $ | domEl | [HTMLCollection] | The corresponding DOM element of the module name. | +| | find(sEl) | function | Gets the descendants of the module DOM element that matches the query. | +| | length | number | The number of elements that was returned from the DOM query. | +| | moduleIdentifier | string | The name of the module. | +| | plugin( sPluginID, oData) | function | Initialize any the plugin specified. | + +#### $.find(sEl) + +| Parameter | Type | Example | Description | +| --------- | ------ | --------------------- | ---------------------------------------- | +| sEl | string | '#id' of '.classname' | The selector string that will be queried against the DOM elements. | + + + +#### $.plugin( sPluginID, oData) + +| Parameter | Type | Example | Description | +| --------- | ------ | ----------- | ---------------------------------------- | +| sPluginID | string | 'accordion' | The name of the plugin. | +| oData | object | {data} | The data should be provided upon initialization of the plugin. | + + + +## Module Methods + +### CORE.module.create(sModuleID, aExtensions, fFn, aPlugins) + +This factory function registers a new module to CORE module management system. + +#### Parameters + +| Parameter | Type | Example | Description | +| ----------- | -------- | -------------------- | ---------------------------------------- | +| sModuleID | string | '#foo' | The module name which is use to query the DOM for corresponding element with an ID with the same name. | +| aExtensions | [string] | ['dom'] | An array containing the extension IDs of the module's dependencies. | +| fFn | function | function ($) { ... } | The function that contains the implementation details of the module. | +| aPlugins | [string] | ['myPlugin'] | An array containing the plugin IDs of the module's dependencies. | + +#### Return Type + +`void` + +#### Example + +```js +CORE.module.create('#foo', ['dom'], function ($) { + var $childElement = $.find('#foo-child'); + + return { + init: function() { + $.plugin('plugin', $); + }, + destroy: function () { + //body + } + }; +}, ['plugin']); +``` + +```html +
+ ... +
+``` + + + +### CORE.module.start( sModuleID, oData ) +Starts the module by creating a new instance of it. + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | ------ | --------------------------- | ---------------------------------------- | +| sModuleID | string | '#foo' | The name of the module that should be instantiated. | +| oData | object | {
name: 'Harry'
} | Any data that should be consumes upon the module instantiation. The data is passed to the `init()` function of the module and is optional. | + +#### Return Type +`void` + +#### Example +```js +CORE.module.start('#foo'); +``` + +### CORE.module.stop( sModuleID ) +Stops the module by calling the destroy method and removing the instance from CORE. + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | ------ | ------- | ---------------------------------------- | +| sModuleID | string | '#foo' | The name of the module instance that should be destroyed. | + +#### Return Type +`void` + +#### Example +```js +CORE.module.stop('#foo'); +``` + + + +### CORE.module.startAll( aExcept ) +Start all modules except the ones specified. + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | -------- | -------- | ---------------------------------------- | +| aExcept | [string] | ['#bar'] | An array containing all the module IDs that should be instantiated. | + +#### Return Type +`void` + +#### Example +```js +CORE.module.startAll(); +``` + + + +### CORE.module.stopAll( aExcept ) +Stop all modules except the ones specified. + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | -------- | -------- | ---------------------------------------- | +| aExcept | [string] | ['#foo'] | An array containing all the module IDs that should not be instantiated. | + +#### Return Type +`void` + +#### Example +```js +CORE.module.stopAll(['#foo']); +``` + + + +### CORE.module.restart( aModuleID ) + +Stops and then starts modules. + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | -------- | -------- | ---------------------------------------- | +| aModuleID | [string] | ['#foo'] | The name of the module that should be restarted. | + +#### Return Type +`void` + +#### Example +```js +CORE.module.restart(['#foo']); +``` + + + +## Plugins +Plugins are reuseable behaviours that are used within the app, such as sliders, accordion and carousels. + + +### CORE.plugin.create( sPluginID, aExtensions, fFn ) +Registers plugins to CORE. + +#### Parameters + +| Parameter | Type | Example | Description | +| ----------- | -------- | -------------------- | ---------------------------------------- | +| sPluginID | string | 'accordion' | The name of the plugin. This should be unique. | +| aExtensions | [string] | ['dom', 'events'] | An array containing the extension IDs of the module's dependencies. | +| fFn | function | function ($) { ... } | The function that contains the implementation details of the plugin. | + +#### Return Type +`void` + +#### Example +```js +CORE.plugin.create('accordion', ['dom', 'events'], function( $ ) { + var + nPrev, + nIdx, + _$elem, + $accordionBtns + ; + + function selectAccordionContent (){ + nIdx = $.dom.index(this, $accordionBtns); + + if(nPrev === nIdx){ + $.dom.removeClass('current', $accordionBtns[nIdx]); + nPrev = null; + return; + } + $.dom.removeClass('current', $accordionBtns); + $.dom.addClass('current', $accordionBtns[nIdx]); + + nPrev = nIdx; + } + return { + init: function ($elem){ + _$elem = $elem; + $accordionBtns = _$elem.find('.accordion-btn'); + + $.events.on(_$elem, 'click', '.accordion-btn', selectAccordionContent); + }, + destroy: function (){ + $.events.off(_$elem, 'click', '.accordion-btn', selectAccordionContent); + } + }; +}); +``` + + + +#### Usage + +```html +
+
Accordian 1
+
+
+ Content 1 +
+
+
Accordian 2
+
+
+ Content 2 +
+
+
+``` + +```js +CORE.module.create('#accordian-element', ['dom'], function ($) { + return { + init: function() { + $.plugin('accordion', $); + }, + destroy: function () { + this.plugin = null; + } + }; + +}, ['accordion']); +``` + + + +## Extensions + +Extensions are third party functionality you want to inject into the module, such as DOM manipulation, DOM events and a messaging system like a mediator. + + +### CORE.extension.create( sExtensionID, fFn ) +Registers extensions to CORE. + +#### Parameters + +| Parameter | Type | Example | Description | +| ------------ | -------- | -------------------- | ---------------------------------------- | +| sExtensionID | string | 'dom' | The name of the extension. This should be unique. | +| fFn | function | function ($) { ... } | The function that contains the implementation details of the extension. | + +#### Return Type +`void` + +#### Example +```js +CORE.extension.create('dom', function ( oData ){ + return { + addClass: function (sClassName, $el) { + // body + }, + removeClass: function (sClassName, $el) { + // body + }, + toggleClass: function (sClassName, $el) { + // body + }, + hasClass: function (sClassName, $el) { + // body + }, + ... + }; +}); +``` + +#### Usage + +```js +CORE.module.create('#elem', ['dom'], function ($) { + return { + init: function() { + // adds css class hide to it's dom element. + $.dom.addClass('.hide', $); + }, + destroy: function () { + } + }; + +}); +``` + + + +## CORE + +#### CORE.debug( bOption ) + +Logs warnings and errors about CORE's internal operations to the console. Default value: **true** + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | ------- | ------- | ----------------------------- | +| bOption | boolean | true | Enable or disable debug mode. | + +#### Return Type + +`void` + +#### Example + +```js +CORE.debug(true) +``` + + + +#### CORE.log( nSeverity, sMsg ) + +Prints message to the console. + +#### Parameters + +| Parameter | Type | Example | Description | +| --------- | ------ | ------------------- | ---------------------------------------- | +| nSeverity | number | 2 | Specifies the type of message that will be logged to the console. Options:
1: INFO
2: WARNING
3: ERROR | +| sMsg | string | 'This is a warning' | The message that should be logged to the console. | + +#### Return Type + +`void` + +#### Example + +```js +CORE.log(1, 'Normal message'); +CORE.log(2, 'Warning message'); +CORE.log(1, 'Error message'); +``` + + + +#### CORE.extend( sExtensionID, fFn ) + +Extend adds additional functionality you want to the CORE object. + +#### Parameters + +| Parameter | Type | Example | Description | +| ------------ | -------- | -------------------- | ---------------------------------------- | +| sExtensionID | string | 'dom' | The name of the extension. This should be unique. | +| fFn | function | function ($) { ... } | The function that contains the implementation details of the extension. | + +#### Return Type + +`void` + +#### Example + +```js +CORE.extend('anything', function (){ + return { + method: function (arg){ + // body + } + }; + }); +``` + +#### Usage + +```js +CORE.anything.method(data); +```