diff --git a/docs/_posts/2018-08-31-bootstrap.md b/docs/_posts/2018-08-31-bootstrap.md new file mode 100644 index 00000000..e875f21e --- /dev/null +++ b/docs/_posts/2018-08-31-bootstrap.md @@ -0,0 +1,134 @@ +--- +category: "general" +title: "Bootstrap" +--- + +## Classes + +
+
Bootstrap
+

Application bootstrap used to initialize the environment and the application +itself.

+
+
+ +## Constants + +
+
PRODUCTION_ENVIRONMENT : string
+

Environment name value in the production environment.

+
+
+ +## Bootstrap  +Application bootstrap used to initialize the environment and the application +itself. + +**Kind**: global class + +* [Bootstrap](#Bootstrap) + * [new Bootstrap(oc)](#new_Bootstrap_new) + * [._oc](#Bootstrap+_oc) : ObjectContainer + * [._config](#Bootstrap+_config) : Object.<string, \*> + * [.run(config)](#Bootstrap+run) + * [._initSettings()](#Bootstrap+_initSettings) + * [._getEnvironmentSetting()](#Bootstrap+_getEnvironmentSetting) ⇒ Object.<string, \*> + * [._bindDependencies()](#Bootstrap+_bindDependencies) + * [._initRoutes()](#Bootstrap+_initRoutes) + * [._initServices()](#Bootstrap+_initServices) + + +* * * + +### new Bootstrap(oc)  +Initializes the bootstrap. + + +| Param | Type | Description | +| --- | --- | --- | +| oc | ObjectContainer | The application's object container to use for managing dependencies. | + + +* * * + +### bootstrap._oc : ObjectContainer  +The object container used to manage dependencies. + +**Kind**: instance property of [Bootstrap](#Bootstrap) + +* * * + +### bootstrap._config : Object.<string, \*>  +Application configuration. + +**Kind**: instance property of [Bootstrap](#Bootstrap) + +* * * + +### bootstrap.run(config)  +Initializes the application by running the bootstrap sequence. The +sequence initializes the components of the application in the following +order: +- application settings +- constants, service providers and class dependencies configuration +- services +- UI components +- routing + +**Kind**: instance method of [Bootstrap](#Bootstrap) + +| Param | Type | Description | +| --- | --- | --- | +| config | Object.<string, \*> | The application environment configuration for the current environment. | + + +* * * + +### bootstrap._initSettings()  +Initializes the application settings. The method loads the settings for +all environments and then pics the settings for the current environment. + +The method also handles using the values in the production environment +as default values for configuration items in other environments. + +**Kind**: instance method of [Bootstrap](#Bootstrap) + +* * * + +### bootstrap._getEnvironmentSetting() ⇒ Object.<string, \*>  +Returns setting for current environment where base values are from production +environment and other environments override base values. + +**Kind**: instance method of [Bootstrap](#Bootstrap) + +* * * + +### bootstrap._bindDependencies()  +Binds the constants, service providers and class dependencies to the +object container. + +**Kind**: instance method of [Bootstrap](#Bootstrap) + +* * * + +### bootstrap._initRoutes()  +Initializes the routes. + +**Kind**: instance method of [Bootstrap](#Bootstrap) + +* * * + +### bootstrap._initServices()  +Initializes the basic application services. + +**Kind**: instance method of [Bootstrap](#Bootstrap) + +* * * + +## PRODUCTION_ENVIRONMENT : string  +Environment name value in the production environment. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-cache-cache-entry.md b/docs/_posts/2018-08-31-cache-cache-entry.md new file mode 100644 index 00000000..125a5275 --- /dev/null +++ b/docs/_posts/2018-08-31-cache-cache-entry.md @@ -0,0 +1,82 @@ +--- +category: "cache" +title: "CacheEntry" +--- + +## CacheEntry  +The cache entry is a typed container of cache data used to track the +creation and expiration of cache entries. + +**Kind**: global class + +* [CacheEntry](#CacheEntry) + * [new CacheEntry(value, ttl)](#new_CacheEntry_new) + * [._value](#CacheEntry+_value) : \* + * [._ttl](#CacheEntry+_ttl) : number + * [._created](#CacheEntry+_created) : number + * [.isExpired()](#CacheEntry+isExpired) ⇒ boolean + * [.serialize()](#CacheEntry+serialize) ⇒ Object + * [.getValue()](#CacheEntry+getValue) ⇒ \* + + +* * * + +### new CacheEntry(value, ttl)  +Initializes the cache entry. + + +| Param | Type | Description | +| --- | --- | --- | +| value | \* | The cache entry value. | +| ttl | number | The time to live in milliseconds. | + + +* * * + +### cacheEntry._value : \*  +Cache entry value. + +**Kind**: instance property of [CacheEntry](#CacheEntry) + +* * * + +### cacheEntry._ttl : number  +The time to live in milliseconds. The cache entry is considered +expired after this time. + +**Kind**: instance property of [CacheEntry](#CacheEntry) + +* * * + +### cacheEntry._created : number  +The timestamp of creation of this cache entry. + +**Kind**: instance property of [CacheEntry](#CacheEntry) + +* * * + +### cacheEntry.isExpired() ⇒ boolean  +Returns `true` if this entry has expired. + +**Kind**: instance method of [CacheEntry](#CacheEntry) +**Returns**: boolean - `true` if this entry has expired. + +* * * + +### cacheEntry.serialize() ⇒ Object  +Exports this cache entry into a JSON-serializable object. + +**Kind**: instance method of [CacheEntry](#CacheEntry) +**Returns**: Object - This entry exported to a + JSON-serializable object. + +* * * + +### cacheEntry.getValue() ⇒ \*  +Returns the entry value. + +**Kind**: instance method of [CacheEntry](#CacheEntry) +**Returns**: \* - The entry value. + +* * * + diff --git a/docs/_posts/2018-08-31-cache-cache-factory.md b/docs/_posts/2018-08-31-cache-cache-factory.md new file mode 100644 index 00000000..bbd80dc9 --- /dev/null +++ b/docs/_posts/2018-08-31-cache-cache-factory.md @@ -0,0 +1,26 @@ +--- +category: "cache" +title: "CacheFactory" +--- + +## CacheFactory  +Factory for creating instances of [CacheEntry](CacheEntry). + +**Kind**: global class + +* * * + +### cacheFactory.createCacheEntry(value, [ttl]) ⇒ CacheEntry  +Create a new instance of [CacheEntry](CacheEntry) with value and ttl. + +**Kind**: instance method of [CacheFactory](#CacheFactory) +**Returns**: CacheEntry - The created cache entry. + +| Param | Type | Description | +| --- | --- | --- | +| value | \* | The cache entry value. | +| [ttl] | number | Cache entry time to live in milliseconds. The entry will expire after the specified amount of milliseconds. | + + +* * * + diff --git a/docs/_posts/2018-08-31-cache-cache-impl.md b/docs/_posts/2018-08-31-cache-cache-impl.md new file mode 100644 index 00000000..cf1895cd --- /dev/null +++ b/docs/_posts/2018-08-31-cache-cache-impl.md @@ -0,0 +1,164 @@ +--- +category: "cache" +title: "CacheImpl" +--- + +## CacheImpl ⇐ Cache  +Configurable generic implementation of the [Cache](Cache) interface. + +**Kind**: global class +**Extends**: Cache + +* [CacheImpl](#CacheImpl) ⇐ Cache + * [new CacheImpl(cacheStorage, factory, Helper, [config])](#new_CacheImpl_new) + * [._cache](#CacheImpl+_cache) : Storage + * [._factory](#CacheImpl+_factory) : CacheFactory + * [._Helper](#CacheImpl+_Helper) : vendor.$Helper + * [._ttl](#CacheImpl+_ttl) : number + * [._enabled](#CacheImpl+_enabled) : boolean + * [.clear()](#CacheImpl+clear) + * [.has()](#CacheImpl+has) + * [.get()](#CacheImpl+get) + * [.set()](#CacheImpl+set) + * [.delete()](#CacheImpl+delete) + * [.disable()](#CacheImpl+disable) + * [.enable()](#CacheImpl+enable) + * [.serialize()](#CacheImpl+serialize) + * [.deserialize()](#CacheImpl+deserialize) + * [._canSerializeValue(value)](#CacheImpl+_canSerializeValue) ⇒ boolean + * [._clone(value)](#CacheImpl+_clone) ⇒ \* + + +* * * + +### new CacheImpl(cacheStorage, factory, Helper, [config])  +Initializes the cache. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| cacheStorage | Storage | | The cache entry storage to use. | +| factory | CacheFactory | | Which create new instance of cache entry. | +| Helper | vendor.$Helper | | The IMA.js helper methods. | +| [config] | Object | {ttl: 30000, enabled: false} | The cache configuration. | + +**Example** +```js +if (cache.has('model.articles')) { + return cache.get('model.articles'); +} else { + let articles = getArticlesFromStorage(); + // cache for an hour + cache.set('model.articles', articles, 60 * 60 * 1000); +} +``` + +* * * + +### cacheImpl._cache : Storage  +Cache entry storage. + +**Kind**: instance property of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl._factory : CacheFactory  +**Kind**: instance property of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl._Helper : vendor.$Helper  +Tha IMA.js helper methods. + +**Kind**: instance property of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl._ttl : number  +Default cache entry time to live in milliseconds. + +**Kind**: instance property of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl._enabled : boolean  +Flag signalling whether the cache is currently enabled. + +**Kind**: instance property of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.clear()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.has()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.get()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.set()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.delete()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.disable()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.enable()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.serialize()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl.deserialize()  +**Kind**: instance method of [CacheImpl](#CacheImpl) + +* * * + +### cacheImpl._canSerializeValue(value) ⇒ boolean  +Tests whether the provided value can be serialized into JSON. + +**Kind**: instance method of [CacheImpl](#CacheImpl) +**Returns**: boolean - `true` if the provided value can be serialized into JSON, + `false` otherwise. + +| Param | Type | Description | +| --- | --- | --- | +| value | \* | The value to test whether or not it can be serialized. | + + +* * * + +### cacheImpl._clone(value) ⇒ \*  +Attempts to clone the provided value, if possible. Values that cannot be +cloned (e.g. promises) will be simply returned. + +**Kind**: instance method of [CacheImpl](#CacheImpl) +**Returns**: \* - The created clone, or the provided value if the value cannot be + cloned. + +| Param | Type | Description | +| --- | --- | --- | +| value | \* | The value to clone. | + + +* * * + diff --git a/docs/_posts/2018-08-31-cache-cache.md b/docs/_posts/2018-08-31-cache-cache.md new file mode 100644 index 00000000..864f8eed --- /dev/null +++ b/docs/_posts/2018-08-31-cache-cache.md @@ -0,0 +1,141 @@ +--- +category: "cache" +title: "Cache" +--- + +## Cache  +**Kind**: global interface + +* [Cache](#Cache) + * [.clear()](#Cache+clear) + * [.has(key)](#Cache+has) ⇒ boolean + * [.get(key)](#Cache+get) ⇒ \* + * [.set(key, value, [ttl])](#Cache+set) + * [.delete(key)](#Cache+delete) + * [.disable()](#Cache+disable) + * [.enable()](#Cache+enable) + * [.serialize()](#Cache+serialize) ⇒ string + * [.deserialize(serializedData)](#Cache+deserialize) + + +* * * + +### cache.clear()  +Clears the cache by deleting all entries. + +**Kind**: instance method of [Cache](#Cache) + +* * * + +### cache.has(key) ⇒ boolean  +Tests whether the cache contains a fresh entry for the specified key. A +cache entry is fresh if the has not expired its TTL (time to live). + +The method always returns `false` if the cache is currently disabled. + +**Kind**: instance method of [Cache](#Cache) +**Returns**: boolean - `true` if the cache is enabled, the entry exists and has + not expired yet. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The identifier of the cache entry. | + + +* * * + +### cache.get(key) ⇒ \*  +Returns the value of the entry identified by the specified key. + +The method returns `null` if the specified entry does not exist, has +already expired, or the cache is currently disabled. + +**Kind**: instance method of [Cache](#Cache) +**Returns**: \* - The value of the specified cache entry, or `null` if the entry + is not available. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The identifier of the cache entry. | + + +* * * + +### cache.set(key, value, [ttl])  +Sets the cache entry identified by the specified key to the provided +value. The entry is created if it does not exist yet. + +The method has no effect if the cache is currently disabled. + +**Kind**: instance method of [Cache](#Cache) + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The identifier of the cache entry. | +| value | \* | The cache entry value. | +| [ttl] | number | Cache entry time to live in milliseconds. The entry will expire after the specified amount of milliseconds. Use `null` or omit the parameter to use the default TTL of this cache. | + + +* * * + +### cache.delete(key)  +Deletes the specified cache entry. The method has no effect if the entry +does not exist. + +**Kind**: instance method of [Cache](#Cache) + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The identifier of the cache entry. | + + +* * * + +### cache.disable()  +Disables the cache, preventing the retrieval of any cached entries and +reporting all cache entries as non-existing. Disabling the cache does +not however prevent modifying the existing or creating new cache +entries. + +Disabling the cache also clears all of its current entries. + +The method has no effect if the cache is already disabled. + +**Kind**: instance method of [Cache](#Cache) + +* * * + +### cache.enable()  +Enables the cache, allowing the retrieval of cache entries. + +The method has no effect if the cache is already enabled. + +**Kind**: instance method of [Cache](#Cache) + +* * * + +### cache.serialize() ⇒ string  +Exports the state of this cache to an HTML-safe JSON string. The data +obtained by parsing the result of this method are compatible with the +[deserialize](#Cache+deserialize) method. + +**Kind**: instance method of [Cache](#Cache) +**Returns**: string - A JSON string containing an object representing of the + current state of this cache. + +* * * + +### cache.deserialize(serializedData)  +Loads the provided serialized cache data into this cache. Entries +present in this cache but not specified in the provided data will remain +in this cache intact. + +**Kind**: instance method of [Cache](#Cache) + +| Param | Type | Description | +| --- | --- | --- | +| serializedData | Object.<string, {value: \*, ttl: number}> | An object representing the state of the cache to load, obtained by parsing the JSON string returned by the [serialize](#Cache+serialize) method. | + + +* * * + diff --git a/docs/_posts/2018-08-31-configbind.md b/docs/_posts/2018-08-31-configbind.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-configbind.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-configservices.md b/docs/_posts/2018-08-31-configservices.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-configservices.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-controller-abstract-controller.md b/docs/_posts/2018-08-31-controller-abstract-controller.md new file mode 100644 index 00000000..6893eefd --- /dev/null +++ b/docs/_posts/2018-08-31-controller-abstract-controller.md @@ -0,0 +1,149 @@ +--- +category: "controller" +title: "AbstractController" +--- + +## *AbstractController ⇐ Controller*  +Basic implementation of the [Controller](Controller) interface, providing the +default implementation of the most of the API. + +**Kind**: global abstract class +**Extends**: Controller + +* *[AbstractController](#AbstractController) ⇐ Controller* + * *[new AbstractController()](#new_AbstractController_new)* + * *[._pageStateManager](#AbstractController+_pageStateManager) : PageStateManager* + * *[._extensions](#AbstractController+_extensions) : Array.<Extension>* + * *[.status](#AbstractController+status) : number* + * *[.params](#AbstractController+params) : Object.<string, string>* + * *[.init()](#AbstractController+init)* + * *[.destroy()](#AbstractController+destroy)* + * *[.activate()](#AbstractController+activate)* + * *[.deactivate()](#AbstractController+deactivate)* + * **[.load()](#AbstractController+load)** + * *[.update()](#AbstractController+update)* + * *[.setState()](#AbstractController+setState)* + * *[.getState()](#AbstractController+getState)* + * *[.addExtension()](#AbstractController+addExtension)* + * *[.getExtensions()](#AbstractController+getExtensions)* + * **[.setMetaParams()](#AbstractController+setMetaParams)** + * *[.setRouteParams()](#AbstractController+setRouteParams)* + * *[.getRouteParams()](#AbstractController+getRouteParams)* + * *[.setPageStateManager()](#AbstractController+setPageStateManager)* + * *[.getHttpStatus()](#AbstractController+getHttpStatus)* + + +* * * + +### *new AbstractController()*  +Initializes the controller. + + +* * * + +### *abstractController._pageStateManager : PageStateManager*  +State manager. + +**Kind**: instance property of [AbstractController](#AbstractController) +**Access**: protected + +* * * + +### *abstractController._extensions : Array.<Extension>*  +The controller's extensions. + +**Kind**: instance property of [AbstractController](#AbstractController) + +* * * + +### *abstractController.status : number*  +The HTTP response code to send to the client. + +**Kind**: instance property of [AbstractController](#AbstractController) + +* * * + +### *abstractController.params : Object.<string, string>*  +The route parameters extracted from the current route. This field is +set externally by IMA right before the [Controller#init](Controller#init) or the +[Controller#update](Controller#update) method is called. + +**Kind**: instance property of [AbstractController](#AbstractController) + +* * * + +### *abstractController.init()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.destroy()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.activate()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.deactivate()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### **abstractController.load()**  +**Kind**: instance abstract method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.update()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.setState()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.getState()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.addExtension()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.getExtensions()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### **abstractController.setMetaParams()**  +**Kind**: instance abstract method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.setRouteParams()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.getRouteParams()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.setPageStateManager()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + +### *abstractController.getHttpStatus()*  +**Kind**: instance method of [AbstractController](#AbstractController) + +* * * + diff --git a/docs/_posts/2018-08-31-controller-controller-decorator.md b/docs/_posts/2018-08-31-controller-controller-decorator.md new file mode 100644 index 00000000..a1753950 --- /dev/null +++ b/docs/_posts/2018-08-31-controller-controller-decorator.md @@ -0,0 +1,181 @@ +--- +category: "controller" +title: "ControllerDecorator" +--- + +## ControllerDecorator ⇐ Controller  +Decorator for page controllers. The decorator manages references to the meta +attributes manager and other utilities so these can be easily provided to +the decorated page controller when needed. + +**Kind**: global class +**Extends**: Controller + +* [ControllerDecorator](#ControllerDecorator) ⇐ Controller + * [new ControllerDecorator(controller, metaManager, router, dictionary, settings)](#new_ControllerDecorator_new) + * [._controller](#ControllerDecorator+_controller) : Controller + * [._metaManager](#ControllerDecorator+_metaManager) : MetaManager + * [._router](#ControllerDecorator+_router) : Router + * [._dictionary](#ControllerDecorator+_dictionary) : Dictionary + * [._settings](#ControllerDecorator+_settings) : Object.<string, \*> + * [.init()](#ControllerDecorator+init) + * [.destroy()](#ControllerDecorator+destroy) + * [.activate()](#ControllerDecorator+activate) + * [.deactivate()](#ControllerDecorator+deactivate) + * [.load()](#ControllerDecorator+load) + * [.update()](#ControllerDecorator+update) + * [.setReactiveView()](#ControllerDecorator+setReactiveView) + * [.setState()](#ControllerDecorator+setState) + * [.getState()](#ControllerDecorator+getState) + * [.addExtension()](#ControllerDecorator+addExtension) + * [.getExtensions()](#ControllerDecorator+getExtensions) + * [.setMetaParams()](#ControllerDecorator+setMetaParams) + * [.setRouteParams()](#ControllerDecorator+setRouteParams) + * [.getRouteParams()](#ControllerDecorator+getRouteParams) + * [.setPageStateManager()](#ControllerDecorator+setPageStateManager) + * [.getHttpStatus()](#ControllerDecorator+getHttpStatus) + * [.getMetaManager()](#ControllerDecorator+getMetaManager) ⇒ MetaManager + + +* * * + +### new ControllerDecorator(controller, metaManager, router, dictionary, settings)  +Initializes the controller decorator. + + +| Param | Type | Description | +| --- | --- | --- | +| controller | Controller | The controller being decorated. | +| metaManager | MetaManager | The meta page attributes manager. | +| router | Router | The application router. | +| dictionary | Dictionary | Localization phrases dictionary. | +| settings | Object.<string, \*> | Application settings for the current application environment. | + + +* * * + +### controllerDecorator._controller : Controller  +The controller being decorated. + +**Kind**: instance property of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator._metaManager : MetaManager  +The meta page attributes manager. + +**Kind**: instance property of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator._router : Router  +The application router. + +**Kind**: instance property of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator._dictionary : Dictionary  +Localization phrases dictionary. + +**Kind**: instance property of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator._settings : Object.<string, \*>  +Application settings for the current application environment. + +**Kind**: instance property of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.init()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.destroy()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.activate()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.deactivate()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.load()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.update()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.setReactiveView()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.setState()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.getState()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.addExtension()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.getExtensions()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.setMetaParams()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.setRouteParams()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.getRouteParams()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.setPageStateManager()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.getHttpStatus()  +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) + +* * * + +### controllerDecorator.getMetaManager() ⇒ MetaManager  +Returns the meta attributes manager configured by the decorated +controller. + +**Kind**: instance method of [ControllerDecorator](#ControllerDecorator) +**Returns**: MetaManager - The Meta attributes manager configured by the + decorated controller. + +* * * + diff --git a/docs/_posts/2018-08-31-controller-controller.md b/docs/_posts/2018-08-31-controller-controller.md new file mode 100644 index 00000000..6f43ec84 --- /dev/null +++ b/docs/_posts/2018-08-31-controller-controller.md @@ -0,0 +1,269 @@ +--- +category: "controller" +title: "Controller" +--- + +## Controller  +**Kind**: global interface + +* [Controller](#Controller) + * [.init()](#Controller+init) + * [.destroy()](#Controller+destroy) + * [.activate()](#Controller+activate) + * [.deactivate()](#Controller+deactivate) + * [.load()](#Controller+load) ⇒ Object.<string, (Promise\|\*)> + * [.update([prevParams])](#Controller+update) ⇒ Object.<string, (Promise\|\*)> + * [.setState(statePatch)](#Controller+setState) + * [.getState()](#Controller+getState) ⇒ Object.<string, \*> + * [.addExtension(extension)](#Controller+addExtension) ⇒ [Controller](#Controller) + * [.getExtensions()](#Controller+getExtensions) ⇒ Array.<Extension> + * [.setMetaParams(loadedResources, metaManager, router, dictionary, settings)](#Controller+setMetaParams) + * [.setRouteParams([params])](#Controller+setRouteParams) + * [.getRouteParams()](#Controller+getRouteParams) ⇒ Object.<string, string> + * [.setPageStateManager(pageStateManager)](#Controller+setPageStateManager) + * [.getHttpStatus()](#Controller+getHttpStatus) ⇒ number + + +* * * + +### controller.init()  +Callback for initializing the controller after the route parameters have +been set on this controller. + +**Kind**: instance method of [Controller](#Controller) + +* * * + +### controller.destroy()  +Finalization callback, called when the controller is being discarded by +the application. This usually happens when the user navigates to a +different URL. + +This method is the lifecycle counterpart of the [init](#Controller+init) +method. + +The controller should release all resources obtained in the +[init](#Controller+init) method. The controller must release any resources +that might not be released automatically when the controller's instance +is destroyed by the garbage collector. + +**Kind**: instance method of [Controller](#Controller) + +* * * + +### controller.activate()  +Callback for activating the controller in the UI. This is the last +method invoked during controller initialization, called after all the +promises returned from the [load](#Controller+load) method have been +resolved and the controller has configured the meta manager. + +The controller may register any React and DOM event listeners in this +method. The controller may start receiving event bus event after this +method completes. + +**Kind**: instance method of [Controller](#Controller) + +* * * + +### controller.deactivate()  +Callback for deactivating the controller in the UI. This is the first +method invoked during controller deinitialization. This usually happens +when the user navigates to a different URL. + +This method is the lifecycle counterpart of the +[activate](#Controller+activate) method. + +The controller should deregister listeners registered and release all +resources obtained in the [activate](#Controller+activate) method. + +**Kind**: instance method of [Controller](#Controller) + +* * * + +### controller.load() ⇒ Object.<string, (Promise\|\*)>  +Callback the controller uses to request the resources it needs to render +its view. This method is invoked after the [init](#Controller+init) +method. + +The controller should request all resources it needs in this method, and +represent each resource request as a promise that will resolve once the +resource is ready for use (these can be data fetched over HTTP(S), +database connections, etc). + +The method must return a plain flat object. The field names of the +object identify the resources being fetched and prepared, each value +must be either the resource (e.g. view configuration or a value +retrieved synchronously) or a Promise that will resolve to the resource. + +The IMA will use the object to set the state of the controller. + +If at the server side, the IMA will wait for all the promises to +resolve, replaces the promises with the resolved values and sets the +resulting object as the controller's state. + +If at the client side, the IMA will first set the controller's state to +an object containing only the fields of the returned object that were +not promises. IMA will then update the controller's state every time a +promise of the returned object resolves. IMA will update the state by +adding the resolved resource to the controller's state. + +Any returned promise that gets rejected will redirect the application to +the error page. The error page that will be used depends on the status +code of the error. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: Object.<string, (Promise\|\*)> - A map object of promises + resolved when all resources the controller requires are ready. + The resolved values will be pushed to the controller's state. + +* * * + +### controller.update([prevParams]) ⇒ Object.<string, (Promise\|\*)>  +Callback for updating the controller after a route update. This method +is invoked if the current route has the `onlyUpdate` flag set to `true` and +the current controller and view match those used by the previously active +route, or, the `onlyUpdate` option of the current route is a callback and +returned `true`. + +The method must return an object with the same semantics as the result +of the [load](#Controller+load) method. The controller's state will only +be patched by the returned object instead of replacing it completely. + +The other controller lifecycle callbacks ([init](#Controller+init), +[load](#Controller+load), [activate](#Controller+activate), +[deactivate](#Controller+deactivate), [Controller#deinit](Controller#deinit)) are not call +in case this method is used. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: Object.<string, (Promise\|\*)> - A map object of promises + resolved when all resources the controller requires are ready. + The resolved values will be pushed to the controller's state. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [prevParams] | Object.<string, string> | {} | Previous route parameters. | + + +* * * + +### controller.setState(statePatch)  +Patches the state of this controller using the provided object by +copying the provided patch object fields to the controller's state +object. + +You can use this method to modify the state partially or add new fields +to the state object. + +Note that the state is not patched recursively but by replacing the +values of the top-level fields of the state object. + +Once the promises returned by the [load](#Controller+load) method are +resolved, this method is called with the an object containing the +resolved values. The field names of the passed object will match the +field names in the object returned from the [load](#Controller+load) +method. + +**Kind**: instance method of [Controller](#Controller) + +| Param | Type | Description | +| --- | --- | --- | +| statePatch | Object.<string, \*> | Patch of the controller's state to apply. | + + +* * * + +### controller.getState() ⇒ Object.<string, \*>  +Returns the controller's current state. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: Object.<string, \*> - The current state of this controller. + +* * * + +### controller.addExtension(extension) ⇒ [Controller](#Controller)  +Adds the provided extension to this controller. All extensions should be +added to the controller before the [init](#Controller+init) method is +invoked. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: [Controller](#Controller) - This controller. + +| Param | Type | Description | +| --- | --- | --- | +| extension | Extension | The extension to add to this controller. | + + +* * * + +### controller.getExtensions() ⇒ Array.<Extension>  +Returns the controller's extensions. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: Array.<Extension> - The extensions added to this controller. + +* * * + +### controller.setMetaParams(loadedResources, metaManager, router, dictionary, settings)  +Callback used to configure the meta attribute manager. The method is +called after the the controller's state has been patched with the all +loaded resources and the view has been rendered. + +**Kind**: instance method of [Controller](#Controller) + +| Param | Type | Description | +| --- | --- | --- | +| loadedResources | Object.<string, \*> | A plain object representing a map of resource names to resources loaded by the [load](#Controller+load) method. This is the same object as the one passed to the [setState](#Controller+setState) method. | +| metaManager | MetaManager | Meta attributes manager to configure. | +| router | Router | The current application router. | +| dictionary | Dictionary | The current localization dictionary. | +| settings | Object.<string, \*> | The application settings for the current application environment. | + + +* * * + +### controller.setRouteParams([params])  +Sets the current route parameters. This method is invoked before the +[init](#Controller+init) method. + +**Kind**: instance method of [Controller](#Controller) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [params] | Object.<string, string> | {} | The current route parameters. | + + +* * * + +### controller.getRouteParams() ⇒ Object.<string, string>  +Returns the current route parameters. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: Object.<string, string> - The current route parameters. + +* * * + +### controller.setPageStateManager(pageStateManager)  +Sets the page state manager. The page state manager manages the +controller's state. The state manager can be set to `null` if this +controller loses the right to modify the state of the current page (e.g. +the user has navigated to a different route using a different +controller). + +**Kind**: instance method of [Controller](#Controller) + +| Param | Type | Description | +| --- | --- | --- | +| pageStateManager | PageStateManager | The current state manager to use. | + + +* * * + +### controller.getHttpStatus() ⇒ number  +Returns the HTTP status code to send to the client, should the +controller be used at the server-side. + +**Kind**: instance method of [Controller](#Controller) +**Returns**: number - The HTTP status code to send to the client. + +* * * + diff --git a/docs/_posts/2018-08-31-coveragelcov-reportprettify.md b/docs/_posts/2018-08-31-coveragelcov-reportprettify.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-coveragelcov-reportprettify.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-coveragelcov-reportsorter.md b/docs/_posts/2018-08-31-coveragelcov-reportsorter.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-coveragelcov-reportsorter.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-debug-dev-tool.md b/docs/_posts/2018-08-31-debug-dev-tool.md new file mode 100644 index 00000000..97de896d --- /dev/null +++ b/docs/_posts/2018-08-31-debug-dev-tool.md @@ -0,0 +1,109 @@ +--- +category: "debug" +title: "DevTool" +--- + +## DevTool  +Developer tools, used mostly for navigating the page state history. + +**Kind**: global class + +* [DevTool](#DevTool) + * [new DevTool(pageManager, stateManager, window, dispatcher, eventBus)](#new_DevTool_new) + * [._pageManager](#DevTool+_pageManager) : PageManager + * [._stateManager](#DevTool+_stateManager) : PageStateManager + * [._window](#DevTool+_window) : Window + * [._dispatcher](#DevTool+_dispatcher) : Dispatcher + * [._eventBus](#DevTool+_eventBus) : EventBus + * [.init()](#DevTool+init) + * [.setState(statePatch)](#DevTool+setState) + * [.getState()](#DevTool+getState) ⇒ Object.<string, \*> + * [.clearAppSource()](#DevTool+clearAppSource) + + +* * * + +### new DevTool(pageManager, stateManager, window, dispatcher, eventBus)  +Initializes the developer tools. + + +| Param | Type | Description | +| --- | --- | --- | +| pageManager | PageManager | Application page manager. | +| stateManager | PageStateManager | Application state manager. | +| window | Window | IMA window wrapper. | +| dispatcher | Dispatcher | IMA event dispatcher. | +| eventBus | EventBus | IMA DOM event bus. | + + +* * * + +### devTool._pageManager : PageManager  +Application page manager. + +**Kind**: instance property of [DevTool](#DevTool) + +* * * + +### devTool._stateManager : PageStateManager  +Application state manager. + +**Kind**: instance property of [DevTool](#DevTool) + +* * * + +### devTool._window : Window  +IMA window wrapper. + +**Kind**: instance property of [DevTool](#DevTool) + +* * * + +### devTool._dispatcher : Dispatcher  +IMA event dispatcher. + +**Kind**: instance property of [DevTool](#DevTool) + +* * * + +### devTool._eventBus : EventBus  +IMA DOM event bus. + +**Kind**: instance property of [DevTool](#DevTool) + +* * * + +### devTool.init()  +Initializes the developer tools. + +**Kind**: instance method of [DevTool](#DevTool) + +* * * + +### devTool.setState(statePatch)  +Sets the provided state to the state manager. + +**Kind**: instance method of [DevTool](#DevTool) + +| Param | Type | Description | +| --- | --- | --- | +| statePatch | Object.<string, \*> | A patch of the current page state. | + + +* * * + +### devTool.getState() ⇒ Object.<string, \*>  +Returns the current page state. + +**Kind**: instance method of [DevTool](#DevTool) +**Returns**: Object.<string, \*> - The current page state. + +* * * + +### devTool.clearAppSource()  +Clears the current application state. + +**Kind**: instance method of [DevTool](#DevTool) + +* * * + diff --git a/docs/_posts/2018-08-31-dictionary-dictionary.md b/docs/_posts/2018-08-31-dictionary-dictionary.md new file mode 100644 index 00000000..eb216f34 --- /dev/null +++ b/docs/_posts/2018-08-31-dictionary-dictionary.md @@ -0,0 +1,74 @@ +--- +category: "dictionary" +title: "Dictionary" +--- + +## Dictionary  +**Kind**: global interface + +* [Dictionary](#Dictionary) + * [.init(config)](#Dictionary+init) + * [.getLanguage()](#Dictionary+getLanguage) ⇒ string + * [.get(key, [parameters])](#Dictionary+get) ⇒ string + * [.has(key)](#Dictionary+has) ⇒ boolean + + +* * * + +### dictionary.init(config)  +Initializes this dictionary with the provided language and localization +phrases. + +**Kind**: instance method of [Dictionary](#Dictionary) + +| Param | Type | Description | +| --- | --- | --- | +| config | Object.<string, \*> | The dictionary configuration. | +| config.language | string | The language property is an ISO 639-1 language code specifying the language of the provided phrases. | +| config.dictionary | \* | The dictionary property contains the localization phrases organized in an implementation-specific way. | + + +* * * + +### dictionary.getLanguage() ⇒ string  +Returns the ISO 639-1 language code of the language this dictionary was +initialized with. + +**Kind**: instance method of [Dictionary](#Dictionary) +**Returns**: string - The language code representing the language of the + localization phrases in this dictionary. + +* * * + +### dictionary.get(key, [parameters]) ⇒ string  +Retrieves the localization phrase identified by the specified key, +evaluates the phrase's placeholder expressions using the provided +parameters and returns the result. + +**Kind**: instance method of [Dictionary](#Dictionary) +**Returns**: string - The specified localization phrase with its placeholders + evaluated using the provided parameters. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the localization phrase. | +| [parameters] | Object.<string, (boolean\|number\|string\|Date)> | The map of parameter names to the parameter values to use. Defaults to an empty plain object. | + + +* * * + +### dictionary.has(key) ⇒ boolean  +Tests whether the specified localization phrase exists in the +dictionary. + +**Kind**: instance method of [Dictionary](#Dictionary) +**Returns**: boolean - `true` if the key exists and denotes a single + localization phrase, otherwise `false`. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the localization phrase. | + + +* * * + diff --git a/docs/_posts/2018-08-31-dictionary-message-format-dictionary.md b/docs/_posts/2018-08-31-dictionary-message-format-dictionary.md new file mode 100644 index 00000000..35e2fa22 --- /dev/null +++ b/docs/_posts/2018-08-31-dictionary-message-format-dictionary.md @@ -0,0 +1,97 @@ +--- +category: "dictionary" +title: "MessageFormatDictionary" +--- + +## MessageFormatDictionary ⇐ Dictionary  +Implementation of the [Dictionary](Dictionary) interface that relies on +compiled MessageFormat localization messages for its dictionary. + +**Kind**: global class +**Extends**: Dictionary + +* [MessageFormatDictionary](#MessageFormatDictionary) ⇐ Dictionary + * [new MessageFormatDictionary()](#new_MessageFormatDictionary_new) + * [._language](#MessageFormatDictionary+_language) : string + * [._dictionary](#MessageFormatDictionary+_dictionary) : Object.<string, Object.<string, function(Object.<string, (number\|string)>): string>> + * [.init(config)](#MessageFormatDictionary+init) + * [.getLanguage()](#MessageFormatDictionary+getLanguage) + * [.get(key, [parameters])](#MessageFormatDictionary+get) ⇒ string + * [.has(key)](#MessageFormatDictionary+has) ⇒ boolean + + +* * * + +### new MessageFormatDictionary()  +Initializes the dictionary. + + +* * * + +### messageFormatDictionary._language : string  +The language of the phrases in the dictionary, represented as a +ISO 639-1 language code. + +**Kind**: instance property of [MessageFormatDictionary](#MessageFormatDictionary) + +* * * + +### messageFormatDictionary._dictionary : Object.<string, Object.<string, function(Object.<string, (number\|string)>): string>>  +Stored dictionary. + +**Kind**: instance property of [MessageFormatDictionary](#MessageFormatDictionary) + +* * * + +### messageFormatDictionary.init(config)  +Initializes this dictionary with the provided language and localization +phrases. + +**Kind**: instance method of [MessageFormatDictionary](#MessageFormatDictionary) + +| Param | Type | Description | +| --- | --- | --- | +| config | Object.<string, \*> | The dictionary configuration. | +| config.language | string | The language property is an ISO 639-1 language code specifying the language of the provided phrases. | +| config.dictionary | Object.<string, Object.<string, function(Object.<string, (number\|string)>): string>> | The dictionary field contains the localization phrases organized in a deep plain object map. The top-level key is the name of the phrase group, the bottom-level key is the phrase key. The bottom-level value is the localization phrase generator that takes the phrase placeholder values map as an argument and produces the localization phrase with its placeholders evaluated using the provided placeholder values. | + + +* * * + +### messageFormatDictionary.getLanguage()  +**Kind**: instance method of [MessageFormatDictionary](#MessageFormatDictionary) + +* * * + +### messageFormatDictionary.get(key, [parameters]) ⇒ string  +Retrieves the localization phrase identified by the specified key, +evaluates the phrase's placeholder expressions using the provided +parameters and returns the result. + +**Kind**: instance method of [MessageFormatDictionary](#MessageFormatDictionary) +**Returns**: string - The specified localization phrase with its placeholders + evaluated using the provided parameters. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the localization phrase. The key consists of at least two parts separated by dots. The first part denotes the name of the source JSON localization file, while the rest denote a field path within the localization object within the given localization file. | +| [parameters] | Object.<string, (boolean\|number\|string\|Date)> | The map of parameter names to the parameter values to use. Defaults to an empty plain object. | + + +* * * + +### messageFormatDictionary.has(key) ⇒ boolean  +Tests whether the specified localization phrase exists in the +dictionary. + +**Kind**: instance method of [MessageFormatDictionary](#MessageFormatDictionary) +**Returns**: boolean - `true` if the key exists and denotes a single + localization phrase, otherwise `false`. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the localization phrase. The key consists of at least two parts separated by dots. The first part denotes the name of the source JSON localization file, while the rest denote a field path within the localization object within the given localization file. | + + +* * * + diff --git a/docs/_posts/2018-08-31-error-error.md b/docs/_posts/2018-08-31-error-error.md new file mode 100644 index 00000000..5a839f45 --- /dev/null +++ b/docs/_posts/2018-08-31-error-error.md @@ -0,0 +1,45 @@ +--- +category: "error" +title: "Error" +--- + +## Error ⇐ ExtensibleError  +**Kind**: global interface +**Extends**: ExtensibleError + +* [Error](#Error) ⇐ ExtensibleError + * [.getHttpStatus()](#Error+getHttpStatus) ⇒ number + * [.getParams()](#Error+getParams) ⇒ Object.<string, \*> + + +* * * + +### error.getHttpStatus() ⇒ number  +Returns the HTTP status to send to the client. + +If the error has occurred at the client-side, the status code is used to +determine the error page to show to the user. + +This method is a shorthand for the following code snippet: +`this.getParams().status || 500`. + +**Kind**: instance method of [Error](#Error) +**Returns**: number - The HTTP status to send to the client. +**See**: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html + +* * * + +### error.getParams() ⇒ Object.<string, \*>  +Returns the error parameters providing additional details about the +error. The structure of the returned object is always +situation-dependent, but the returned object usually contains the +`status: number` field which represents the HTTP status to send to +the client. + +**Kind**: instance method of [Error](#Error) +**Returns**: Object.<string, \*> - The route parameters of the route at which + the error has occurred. +**See**: Error#getHttpStatus + +* * * + diff --git a/docs/_posts/2018-08-31-error-extensible-error.md b/docs/_posts/2018-08-31-error-extensible-error.md new file mode 100644 index 00000000..53ac4365 --- /dev/null +++ b/docs/_posts/2018-08-31-error-extensible-error.md @@ -0,0 +1,85 @@ +--- +category: "error" +title: "ExtensibleError" +--- + +## *ExtensibleError ⇐ Error*  +**Kind**: global abstract class +**Extends**: Error + +* *[ExtensibleError](#ExtensibleError) ⇐ Error* + * *[new ExtensibleError(message, [dropInternalStackFrames])](#new_ExtensibleError_new)* + * *[.name](#ExtensibleError+name) : string* + * *[.message](#ExtensibleError+message) : string* + * *[._nativeError](#ExtensibleError+_nativeError) : Error* + * *[._stack](#ExtensibleError+_stack) : string* + * *[._dropInternalStackFrames](#ExtensibleError+_dropInternalStackFrames) : boolean* + * *[.stack](#ExtensibleError+stack) : string* + + +* * * + +### *new ExtensibleError(message, [dropInternalStackFrames])*  +Base class of custom error classes, extending the native `Error` class. + +This class has been introduced to fix the Babel-related issues with +extending the native JavaScript (Error) classes. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| message | string | | The message describing the cause of the error. | +| [dropInternalStackFrames] | boolean | true | Whether or not the call stack frames referring to the constructors of the custom errors should be excluded from the stack of this error (just like the native platform call stack frames are dropped by the JS engine). This flag is enabled by default. | + + +* * * + +### *extensibleError.name : string*  +The name of this error, used in the generated stack trace. + +**Kind**: instance property of [ExtensibleError](#ExtensibleError) + +* * * + +### *extensibleError.message : string*  +The message describing the cause of the error. + +**Kind**: instance property of [ExtensibleError](#ExtensibleError) + +* * * + +### *extensibleError._nativeError : Error*  +Native error instance we use to generate the call stack. For some reason +some browsers do not generate call stacks for instances of classes +extending the native `Error` class, so we bypass this shortcoming this way. + +**Kind**: instance property of [ExtensibleError](#ExtensibleError) + +* * * + +### *extensibleError._stack : string*  +The internal cache of the generated stack. The cache is filled upon first +access to the [stack](#ExtensibleError+stack) property. + +**Kind**: instance property of [ExtensibleError](#ExtensibleError) + +* * * + +### *extensibleError._dropInternalStackFrames : boolean*  +Whether or not the call stack frames referring to the constructors of +the custom errors should be excluded from the stack of this error (just +like the native platform call stack frames are dropped by the JS +engine). + +**Kind**: instance property of [ExtensibleError](#ExtensibleError) + +* * * + +### *extensibleError.stack : string*  +The call stack captured at the moment of creation of this error. The +formatting of the stack is browser-dependant. + +**Kind**: instance property of [ExtensibleError](#ExtensibleError) + +* * * + diff --git a/docs/_posts/2018-08-31-error-generic-error.md b/docs/_posts/2018-08-31-error-generic-error.md new file mode 100644 index 00000000..85a89bb8 --- /dev/null +++ b/docs/_posts/2018-08-31-error-generic-error.md @@ -0,0 +1,51 @@ +--- +category: "error" +title: "GenericError" +--- + +## GenericError ⇐ Error  +Implementation of the [Error](Error) interface, providing more advanced +error API. + +**Kind**: global class +**Extends**: Error + +* [GenericError](#GenericError) ⇐ Error + * [new GenericError(message, [params], [dropInternalStackFrames])](#new_GenericError_new) + * [._params](#GenericError+_params) : Object.<string, \*> + * [.getHttpStatus()](#GenericError+getHttpStatus) + * [.getParams()](#GenericError+getParams) + + +* * * + +### new GenericError(message, [params], [dropInternalStackFrames])  +Initializes the generic IMA error. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| message | string | | The message describing the cause of the error. | +| [params] | Object.<string, \*> | {} | A data map providing additional details related to the error. It is recommended to set the status field to the HTTP response code that should be sent to the client. | +| [dropInternalStackFrames] | boolean | true | Whether or not the call stack frames referring to the constructors of the custom errors should be excluded from the stack of this error (just like the native platform call stack frames are dropped by the JS engine). This flag is enabled by default. | + + +* * * + +### genericError._params : Object.<string, \*>  +The data providing additional details related to this error. + +**Kind**: instance property of [GenericError](#GenericError) + +* * * + +### genericError.getHttpStatus()  +**Kind**: instance method of [GenericError](#GenericError) + +* * * + +### genericError.getParams()  +**Kind**: instance method of [GenericError](#GenericError) + +* * * + diff --git a/docs/_posts/2018-08-31-event-dispatcher-impl.md b/docs/_posts/2018-08-31-event-dispatcher-impl.md new file mode 100644 index 00000000..c4aead7b --- /dev/null +++ b/docs/_posts/2018-08-31-event-dispatcher-impl.md @@ -0,0 +1,156 @@ +--- +category: "event" +title: "DispatcherImpl" +--- + +## Classes + +
+
DispatcherImpl
+

Default implementation of the Dispatcher interface.

+
+
+ +## Constants + +
+
EMPTY_MAP : Map.<function(*), Set.<?Object>>
+

An empty immutable map of event listener to scopes, used for a mismatch in +the _eventListeners map.

+
+
EMPTY_SET : Set.<?Object>
+

An empty immutable set of event listener scopes, used for a mismatch in the +_eventListeners map.

+
+
+ +## DispatcherImpl  +Default implementation of the Dispatcher interface. + +**Kind**: global class + +* [DispatcherImpl](#DispatcherImpl) + * [new DispatcherImpl()](#new_DispatcherImpl_new) + * [._eventListeners](#DispatcherImpl+_eventListeners) : Map.<string, Map.<function(\*), Set.<?Object>>> + * [.clear()](#DispatcherImpl+clear) + * [.listen()](#DispatcherImpl+listen) + * [.unlisten()](#DispatcherImpl+unlisten) + * [.fire()](#DispatcherImpl+fire) + * [._createNewEvent(event)](#DispatcherImpl+_createNewEvent) + * [._createNewListener(event, listener)](#DispatcherImpl+_createNewListener) + * [._getScopesOf(event, listener)](#DispatcherImpl+_getScopesOf) ⇒ Set.<?Object> + * [._getListenersOf(event)](#DispatcherImpl+_getListenersOf) ⇒ Map.<function(\*), Set.<?Object>> + + +* * * + +### new DispatcherImpl()  +Initializes the dispatcher. + + +* * * + +### dispatcherImpl._eventListeners : Map.<string, Map.<function(\*), Set.<?Object>>>  +Map of event names to a map of event listeners to a set of scopes to +which the event listener should be bound when being executed due to +the event. + +**Kind**: instance property of [DispatcherImpl](#DispatcherImpl) + +* * * + +### dispatcherImpl.clear()  +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) + +* * * + +### dispatcherImpl.listen()  +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) + +* * * + +### dispatcherImpl.unlisten()  +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) + +* * * + +### dispatcherImpl.fire()  +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) + +* * * + +### dispatcherImpl._createNewEvent(event)  +Create new Map storage of listeners for the specified event. + +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event. | + + +* * * + +### dispatcherImpl._createNewListener(event, listener)  +Create new Set storage of scopes for the specified event and listener. + +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event. | +| listener | function | The event listener. | + + +* * * + +### dispatcherImpl._getScopesOf(event, listener) ⇒ Set.<?Object>  +Retrieves the scopes in which the specified event listener should be +executed for the specified event. + +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) +**Returns**: Set.<?Object> - The scopes in which the specified listeners + should be executed in case of the specified event. The returned + set is an unmodifiable empty set if no listeners are registered + for the event. + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event. | +| listener | function | The event listener. | + + +* * * + +### dispatcherImpl._getListenersOf(event) ⇒ Map.<function(\*), Set.<?Object>>  +Retrieves the map of event listeners to scopes they are bound to. + +**Kind**: instance method of [DispatcherImpl](#DispatcherImpl) +**Returns**: Map.<function(\*), Set.<?Object>> - A map of event listeners to the + scopes in which they should be executed. The returned map is an + unmodifiable empty map if no listeners are registered for the + event. + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event. | + + +* * * + +## EMPTY_MAP : Map.<function(\*), Set.<?Object>>  +An empty immutable map of event listener to scopes, used for a mismatch in +the _eventListeners map. + +**Kind**: global constant + +* * * + +## EMPTY_SET : Set.<?Object>  +An empty immutable set of event listener scopes, used for a mismatch in the +_eventListeners map. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-event-dispatcher.md b/docs/_posts/2018-08-31-event-dispatcher.md new file mode 100644 index 00000000..d13080f4 --- /dev/null +++ b/docs/_posts/2018-08-31-event-dispatcher.md @@ -0,0 +1,88 @@ +--- +category: "event" +title: "Dispatcher" +--- + +## Dispatcher  +**Kind**: global interface + +* [Dispatcher](#Dispatcher) + * [.clear()](#Dispatcher+clear) ⇒ [Dispatcher](#Dispatcher) + * [.listen(event, listener, [scope])](#Dispatcher+listen) ⇒ [Dispatcher](#Dispatcher) + * [.unlisten(event, listener, [scope])](#Dispatcher+unlisten) ⇒ [Dispatcher](#Dispatcher) + * [.fire(event, data, [imaInternalEvent])](#Dispatcher+fire) ⇒ [Dispatcher](#Dispatcher) + + +* * * + +### dispatcher.clear() ⇒ [Dispatcher](#Dispatcher)  +Deregisters all event listeners currently registered with this +dispatcher. + +**Kind**: instance method of [Dispatcher](#Dispatcher) +**Returns**: [Dispatcher](#Dispatcher) - This dispatcher. + +* * * + +### dispatcher.listen(event, listener, [scope]) ⇒ [Dispatcher](#Dispatcher)  +Registers the provided event listener to be executed when the specified +event is fired on this dispatcher. + +When the specified event is fired, the event listener will be executed +with the data passed with the event as the first argument. + +The order in which the event listeners will be executed is unspecified +and should not be relied upon. Registering the same listener for the +same event and with the same scope multiple times has no effect. + +**Kind**: instance method of [Dispatcher](#Dispatcher) +**Returns**: [Dispatcher](#Dispatcher) - This dispatcher. + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event to listen for. | +| listener | function | The event listener to register. | +| [scope] | Object | The object to which the this keyword will be bound in the event listener. | + + +* * * + +### dispatcher.unlisten(event, listener, [scope]) ⇒ [Dispatcher](#Dispatcher)  +Deregisters the provided event listener, so it will no longer be +executed with the specified scope when the specified event is fired. + +**Kind**: instance method of [Dispatcher](#Dispatcher) +**Returns**: [Dispatcher](#Dispatcher) - This dispatcher. + +| Param | Type | Description | +| --- | --- | --- | +| event | string | The name of the event for which the listener should be deregistered. | +| listener | function | The event listener to deregister. | +| [scope] | Object | The object to which the this keyword would be bound in the event listener. | + + +* * * + +### dispatcher.fire(event, data, [imaInternalEvent]) ⇒ [Dispatcher](#Dispatcher)  +Fires a new event of the specified name, carrying the provided data. + +The method will synchronously execute all event listeners registered for +the specified event, passing the provided data to them as the first +argument. + +Note that this method does not prevent the event listeners to modify the +data in any way. The order in which the event listeners will be executed +is unspecified and should not be relied upon. + +**Kind**: instance method of [Dispatcher](#Dispatcher) +**Returns**: [Dispatcher](#Dispatcher) - This dispatcher. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| event | string | | The name of the event to fire. | +| data | Object.<string, \*> | | The data to pass to the event listeners. | +| [imaInternalEvent] | boolean | false | The flag signalling whether this is an internal IMA event. The fired event is treated as a custom application event if this flag is not set. The flag is used only for debugging and has no effect on the propagation of the event. | + + +* * * + diff --git a/docs/_posts/2018-08-31-event-event-bus-impl.md b/docs/_posts/2018-08-31-event-event-bus-impl.md new file mode 100644 index 00000000..5918de49 --- /dev/null +++ b/docs/_posts/2018-08-31-event-event-bus-impl.md @@ -0,0 +1,114 @@ +--- +category: "event" +title: "EventBusImpl" +--- + +## Classes + +
+
EventBusImpl
+

Helper for custom events.

+

It offers public methods for firing custom events and two methods for +catching events (e.g. inside view components).

+
+
+ +## Constants + +
+
IMA_EVENT : string
+

Global name of IMA.js custom event.

+
+
+ +## EventBusImpl  +Helper for custom events. + +It offers public methods for firing custom events and two methods for +catching events (e.g. inside view components). + +**Kind**: global class + +* [EventBusImpl](#EventBusImpl) + * [new EventBusImpl(window)](#new_EventBusImpl_new) + * [._window](#EventBusImpl+_window) : Window + * [._listeners](#EventBusImpl+_listeners) : WeakMap.<function(Event), WeakMap.<EventTarget, Map.<string, function(Event)>>> + * [._allEventListeners](#EventBusImpl+_allEventListeners) : WeakMap.<EventTarget, WeakSet.<function(Event)>> + * [.fire()](#EventBusImpl+fire) + * [.listenAll()](#EventBusImpl+listenAll) + * [.listen()](#EventBusImpl+listen) + * [.unlistenAll()](#EventBusImpl+unlistenAll) + * [.unlisten()](#EventBusImpl+unlisten) + + +* * * + +### new EventBusImpl(window)  +Initializes the custom event helper. + + +| Param | Type | Description | +| --- | --- | --- | +| window | Window | The IMA window helper. | + + +* * * + +### eventBusImpl._window : Window  +The IMA window helper. + +**Kind**: instance property of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl._listeners : WeakMap.<function(Event), WeakMap.<EventTarget, Map.<string, function(Event)>>>  +Map of listeners provided to the public API of this event bus to a +map of event targets to a map of event names to actual listeners +bound to the native API. + +The "listen all" event listeners are not registered in this map. + +**Kind**: instance property of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl._allEventListeners : WeakMap.<EventTarget, WeakSet.<function(Event)>>  +Map of event targets to listeners executed on all IMA.js event bus +events. + +**Kind**: instance property of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl.fire()  +**Kind**: instance method of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl.listenAll()  +**Kind**: instance method of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl.listen()  +**Kind**: instance method of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl.unlistenAll()  +**Kind**: instance method of [EventBusImpl](#EventBusImpl) + +* * * + +### eventBusImpl.unlisten()  +**Kind**: instance method of [EventBusImpl](#EventBusImpl) + +* * * + +## IMA_EVENT : string  +Global name of IMA.js custom event. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-event-event-bus.md b/docs/_posts/2018-08-31-event-event-bus.md new file mode 100644 index 00000000..667f5007 --- /dev/null +++ b/docs/_posts/2018-08-31-event-event-bus.md @@ -0,0 +1,134 @@ +--- +category: "event" +title: "EventBus" +--- + +## EventBus  +**Kind**: global interface + +* [EventBus](#EventBus) + * [.fire(eventTarget, eventName, data, [options])](#EventBus+fire) ⇒ [EventBus](#EventBus) + * [.listenAll(eventTarget, listener)](#EventBus+listenAll) ⇒ [EventBus](#EventBus) + * [.listen(eventTarget, eventName, listener)](#EventBus+listen) ⇒ [EventBus](#EventBus) + * [.unlistenAll(eventTarget, listener)](#EventBus+unlistenAll) ⇒ [EventBus](#EventBus) + * [.unlisten(eventTarget, eventName, listener)](#EventBus+unlisten) ⇒ [EventBus](#EventBus) + + +* * * + +### eventBus.fire(eventTarget, eventName, data, [options]) ⇒ [EventBus](#EventBus)  +Fires a new custom event of the specified name, carrying the provided +data. + +Note that this method does not prevent the event listeners to modify the +data in any way. The order in which the event listeners will be executed +is unspecified and should not be relied upon. + +Note that the default options are +{ bubbles: true, cancelable: true }, which is different from the +default values used in the native custom events +({ bubbles: false, cancelable: false }). + +**Kind**: instance method of [EventBus](#EventBus) +**Returns**: [EventBus](#EventBus) - This custom event bus. +**Throws**: + +- Error Thrown if the provided event target cannot be used to + fire the event. + +**See**: https://developer.mozilla.org/en-US/docs/Web/API/Event/Event + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| eventTarget | EventTarget | | The event target at which the event will be dispatched (e.g. element/document/window). | +| eventName | string | | The name of the event to fire. | +| data | \* | | The data to pass to the event listeners. | +| [options] | Object | {} | The override of the default options passed to the constructor of the custom event fired by this event bus. The default options passed to the custom event constructor are { bubbles: true, cancelable: true }. | + + +* * * + +### eventBus.listenAll(eventTarget, listener) ⇒ [EventBus](#EventBus)  +Registers the provided event listener to be executed when any custom +event is fired using the same implementation of the event bus and passes +through the specified event target. + +When the specified event is fired, the event listener will be executed +with the event passed as the first argument. + +The order in which the event listeners will be executed is unspecified +and should not be relied upon. + +**Kind**: instance method of [EventBus](#EventBus) +**Returns**: [EventBus](#EventBus) - This event bus. + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | EventTarget | The event target at which the listener should listen for all event bus events. | +| listener | function | The event listener to register. | + + +* * * + +### eventBus.listen(eventTarget, eventName, listener) ⇒ [EventBus](#EventBus)  +Registers the provided event listener to be executed when the specific +custom event is fired by the same implementation of the event bus and +passes through the specified event target. + +When the specified event is fired, the event listener will be executed +with the event passed as the first argument. + +The order in which the event listeners will be executed is unspecified +and should not be relied upon. + +**Kind**: instance method of [EventBus](#EventBus) +**Returns**: [EventBus](#EventBus) - This event bus. + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | EventTarget | The event target at which the listener should listen for the specified event. | +| eventName | string | The name of the event to listen for. | +| listener | function | The event listener to register. | + + +* * * + +### eventBus.unlistenAll(eventTarget, listener) ⇒ [EventBus](#EventBus)  +Removes the provided event listener from the set of event listeners +executed when the any custom event fired by the same implementation +passes through the specified event target. + +The method has no effect if the listener is not registered at the +specified event target. + +**Kind**: instance method of [EventBus](#EventBus) +**Returns**: [EventBus](#EventBus) - This event bus. + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | EventTarget | The event target at which the event listener listens for events. | +| listener | function | The event listener to deregister. | + + +* * * + +### eventBus.unlisten(eventTarget, eventName, listener) ⇒ [EventBus](#EventBus)  +Removes the provided event listener from the set of event listeners +executed when the specified custom event fired by the same +implementation passes through the specified event target. + +The method has no effect if the listener is not registered for the +specified event at the specified event target. + +**Kind**: instance method of [EventBus](#EventBus) +**Returns**: [EventBus](#EventBus) - This event bus. + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | EventTarget | The event target at which the listener is listening for the event. | +| eventName | string | The name of the event listened for. | +| listener | function | The event listener to deregister. | + + +* * * + diff --git a/docs/_posts/2018-08-31-execution-abstract-execution.md b/docs/_posts/2018-08-31-execution-abstract-execution.md new file mode 100644 index 00000000..0c1077b3 --- /dev/null +++ b/docs/_posts/2018-08-31-execution-abstract-execution.md @@ -0,0 +1,43 @@ +--- +category: "execution" +title: "AbstractExecution" +--- + +## *AbstractExecution ⇐ Execution*  +Basic implementation of the [Execution](Execution) interface. Provides the basic +functionality for appending and validating jobs. + +**Kind**: global abstract class +**Extends**: Execution + +* *[AbstractExecution](#AbstractExecution) ⇐ Execution* + * *[.append()](#AbstractExecution+append)* + * *[.execute()](#AbstractExecution+execute)* + * *[._validateJob(job)](#AbstractExecution+_validateJob) ⇒ boolean* + + +* * * + +### *abstractExecution.append()*  +**Kind**: instance method of [AbstractExecution](#AbstractExecution) + +* * * + +### *abstractExecution.execute()*  +**Kind**: instance method of [AbstractExecution](#AbstractExecution) + +* * * + +### *abstractExecution._validateJob(job) ⇒ boolean*  +Return true if the given job can be executed + +**Kind**: instance method of [AbstractExecution](#AbstractExecution) +**Access**: protected + +| Param | Type | +| --- | --- | +| job | function | + + +* * * + diff --git a/docs/_posts/2018-08-31-execution-execution.md b/docs/_posts/2018-08-31-execution-execution.md new file mode 100644 index 00000000..4d8ce0bb --- /dev/null +++ b/docs/_posts/2018-08-31-execution-execution.md @@ -0,0 +1,42 @@ +--- +category: "execution" +title: "Execution" +--- + +## Execution  +**Kind**: global interface + +* [Execution](#Execution) + * [.append(jobs)](#Execution+append) + * [.execute(...args)](#Execution+execute) ⇒ Promise + + +* * * + +### execution.append(jobs)  +Adds a new job to be executed. The job is appended at the end of the +list of current jobs therefore is executed last. + +**Kind**: instance method of [Execution](#Execution) + +| Param | Type | Description | +| --- | --- | --- | +| jobs | Array.<function(): Promise> | The jobs to be executed. | + + +* * * + +### execution.execute(...args) ⇒ Promise  +Start executing collected jobs. In the end a Promise is returned +with a resulting value. On the returned Promise a catch +method can be called to prevent any unwanted interruption. + +**Kind**: instance method of [Execution](#Execution) + +| Param | Type | Description | +| --- | --- | --- | +| ...args | any | Arguments to be passed when executing jobs | + + +* * * + diff --git a/docs/_posts/2018-08-31-execution-serial-batch.md b/docs/_posts/2018-08-31-execution-serial-batch.md new file mode 100644 index 00000000..37fdff9e --- /dev/null +++ b/docs/_posts/2018-08-31-execution-serial-batch.md @@ -0,0 +1,16 @@ +--- +category: "execution" +title: "SerialBatch" +--- + +## SerialBatch ⇐ AbstractExecution  +**Kind**: global class +**Extends**: AbstractExecution + +* * * + +### serialBatch.execute()  +**Kind**: instance method of [SerialBatch](#SerialBatch) + +* * * + diff --git a/docs/_posts/2018-08-31-extension-abstract-extension.md b/docs/_posts/2018-08-31-extension-abstract-extension.md new file mode 100644 index 00000000..a65d6c62 --- /dev/null +++ b/docs/_posts/2018-08-31-extension-abstract-extension.md @@ -0,0 +1,139 @@ +--- +category: "extension" +title: "AbstractExtension" +--- + +## *AbstractExtension ⇐ Extension*  +Abstract extension + +**Kind**: global abstract class +**Extends**: Extension + +* *[AbstractExtension](#AbstractExtension) ⇐ Extension* + * *[._pageStateManager](#AbstractExtension+_pageStateManager) : PageStateManager* + * *[.status](#AbstractExtension+status) : number* + * *[.params](#AbstractExtension+params) : Object.<string, string>* + * *[.init()](#AbstractExtension+init)* + * *[.destroy()](#AbstractExtension+destroy)* + * *[.activate()](#AbstractExtension+activate)* + * *[.deactivate()](#AbstractExtension+deactivate)* + * **[.load()](#AbstractExtension+load)** + * *[.update()](#AbstractExtension+update)* + * *[.setState()](#AbstractExtension+setState)* + * *[.getState()](#AbstractExtension+getState)* + * *[.setPartialState()](#AbstractExtension+setPartialState)* + * *[.getPartialState()](#AbstractExtension+getPartialState)* + * *[.clearPartialState()](#AbstractExtension+clearPartialState)* + * *[.setRouteParams()](#AbstractExtension+setRouteParams)* + * *[.getRouteParams()](#AbstractExtension+getRouteParams)* + * *[.setPageStateManager()](#AbstractExtension+setPageStateManager)* + * *[.getHttpStatus()](#AbstractExtension+getHttpStatus)* + * *[.getAllowedStateKeys()](#AbstractExtension+getAllowedStateKeys)* + + +* * * + +### *abstractExtension._pageStateManager : PageStateManager*  +State manager. + +**Kind**: instance property of [AbstractExtension](#AbstractExtension) +**Access**: protected + +* * * + +### *abstractExtension.status : number*  +The HTTP response code to send to the client. + +**Kind**: instance property of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.params : Object.<string, string>*  +The route parameters extracted from the current route. + +**Kind**: instance property of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.init()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.destroy()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.activate()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.deactivate()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### **abstractExtension.load()**  +**Kind**: instance abstract method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.update()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.setState()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.getState()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.setPartialState()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.getPartialState()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.clearPartialState()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.setRouteParams()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.getRouteParams()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.setPageStateManager()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.getHttpStatus()*  +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + +### *abstractExtension.getAllowedStateKeys()*  +Returns array of allowed state keys for extension. + +**Kind**: instance method of [AbstractExtension](#AbstractExtension) + +* * * + diff --git a/docs/_posts/2018-08-31-extension-extension.md b/docs/_posts/2018-08-31-extension-extension.md new file mode 100644 index 00000000..68cecb8d --- /dev/null +++ b/docs/_posts/2018-08-31-extension-extension.md @@ -0,0 +1,323 @@ +--- +category: "extension" +title: "Extension" +--- + +## Extension  +**Kind**: global interface +- [Why use extensions](#why-use-extensions) +- [How to use extensions](#how-to-use-extensions) + +---- + +Extensions provide means of extending the page controllers with additional +managed state and logic. An extension has access to the current route +parameters, can specify the resources to load when the page is loading or +being updated, may intercept event bus events and modify the state of the +page just like an ordinary controller, except that the modifications are +restricted to the state fields which the extension explicitly specifies +using its `getAllowedStateKeys()` method. + +## Why use extensions + +Best case to use extension is a component that +requires interception of controller lifecycle events and/or loading external +data. + +Putting the component's logic inside the controller would be unwise for 3 +reasons: + +1. Controller would contain code that is not as clear. For new-commers to +your project it'd seem strange why you're mixing e.g. **HomeController** +logic with **GalleryComponent** logic. +2. Component file and its extension file should be kept together because nothing is +bigger pain than searching for related code in the whole project structure. +3. Component can be used in multiple Views. That means you'd have to +copy & paste the same logic to multiple controllers. + +## How to use extensions + +As mentioned above, the extension file should be next to a file of the component +it's extending. For example: + +``` +app/ + ├─ ... + ├─ component + | ├─ ... + | └─ gallery + | | ├─ Gallery.jsx + | | ├─ gallery.less + | | └─ GalleryExtension.js + | └─ ... + └─ ... +``` + +In the extension file should be plain `class` extending +`ima/extension/AbstractExtension` with the same methods as you'd use in the controller. In addition you should implement `getAllowedStateKeys()` method which returns array of keys the extension is allowed to change in controller's state. + +> **Note:** List and description of controller methods can be seen in [Controller lifecycle](Controller-lifecycle). + +```javascript +// app/component/gallery/GalleryExtension.js +import AbstractExtension from 'ima/extension/AbstractExtension'; + +export default class GalleryExtension extends AbstractExtension { + + load() { + // Where the magic happens... + } +} +``` + +All extensions to be used on a page must be added to the current controller +via `addExtension()` method before the controller is initialized (Good +place for that is the [`init()`](Controller-lifecycle#init--serverclient) method). After that, the extensions will go +through the same lifecycle as the controller. + +> **Note:** Controller and extension methods are called in a series but the controller methods are called first. + +```javascript +import AbstractController from 'ima/controller/AbstractController'; +import GalleryExtension from 'app/component/gallery/GalleryExtension'; + +export default class PostController extends AbstractController { + + init() { + this.addExtension(GalleryExtension); + } +} + +``` + + +* [Extension](#Extension) + * [.init()](#Extension+init) + * [.destroy()](#Extension+destroy) + * [.activate()](#Extension+activate) + * [.deactivate()](#Extension+deactivate) + * [.load()](#Extension+load) ⇒ Object.<string, (Promise\|\*)> + * [.update([prevParams])](#Extension+update) ⇒ Object.<string, (Promise\|\*)> + * [.setState(statePatch)](#Extension+setState) + * [.getState()](#Extension+getState) ⇒ Object.<string, \*> + * [.setPartialState(partialStatePatch)](#Extension+setPartialState) + * [.getPartialState()](#Extension+getPartialState) ⇒ Object.<string, \*> + * [.clearPartialState()](#Extension+clearPartialState) + * [.setPageStateManager(pageStateManager)](#Extension+setPageStateManager) + * [.setRouteParams([params])](#Extension+setRouteParams) + * [.getRouteParams()](#Extension+getRouteParams) ⇒ Object.<string, string> + * [.getAllowedStateKeys()](#Extension+getAllowedStateKeys) ⇒ Array.<string> + + +* * * + +### extension.init()  +Callback for initializing the controller extension after the route +parameters have been set on this extension. + +**Kind**: instance method of [Extension](#Extension) + +* * * + +### extension.destroy()  +Finalization callback, called when the controller is being discarded by +the application. This usually happens when the user navigates to a +different URL. + +This method is the lifecycle counterpart of the [init](#Extension+init) +method. + +The extension should release all resources obtained in the +[init](#Extension+init) method. The extension must release any resources +that might not be released automatically when the extensions's instance +is destroyed by the garbage collector. + +**Kind**: instance method of [Extension](#Extension) + +* * * + +### extension.activate()  +Callback for activating the extension in the UI. This is the last +method invoked during controller (and extensions) initialization, called +after all the promises returned from the [load](#Extension+load) method have +been resolved and the controller has configured the meta manager. + +The extension may register any React and DOM event listeners in this +method. The extension may start receiving event bus event after this +method completes. + +**Kind**: instance method of [Extension](#Extension) + +* * * + +### extension.deactivate()  +Callback for deactivating the extension in the UI. This is the first +method invoked during extension deinitialization. This usually happens +when the user navigates to a different URL. + +This method is the lifecycle counterpart of the [activate](#Extension+activate) +method. + +The extension should deregister listeners registered and release all +resources obtained in the [activate](#Extension+activate) method. + +**Kind**: instance method of [Extension](#Extension) + +* * * + +### extension.load() ⇒ Object.<string, (Promise\|\*)>  +Callback the extension uses to request the resources it needs to render +its related parts of the view. This method is invoked after the +[init](#Extension+init) method. + +The extension should request all resources it needs in this method, and +represent each resource request as a promise that will resolve once the +resource is ready for use (these can be data fetched over HTTP(S), +database connections, etc). + +The method must return a plain flat object. The field names of the +object identify the resources being fetched and prepared, each value +must be either the resource (e.g. view configuration or a value +retrieved synchronously) or a Promise that will resolve to the resource. + +The IMA will use the object to set the state of the controller. + +Any returned promise that gets rejected will redirect the application to +the error page. The error page that will be used depends on the status +code of the error. + +**Kind**: instance method of [Extension](#Extension) +**Returns**: Object.<string, (Promise\|\*)> - A map object of promises + resolved when all resources the extension requires are ready. + The resolved values will be pushed to the controller's state. + +* * * + +### extension.update([prevParams]) ⇒ Object.<string, (Promise\|\*)>  +Callback for updating the extension after a route update. This method +is invoked if the current route has the `onlyUpdate` flag set to `true` and +the current controller and view match those used by the previously active +route, or, the `onlyUpdate` option of the current route is a callback and +returned `true`. + +The method must return an object with the same semantics as the result +of the [load](#Extension+load) method. The controller's state will then be +patched by the returned object. + +The other extension lifecycle callbacks ([init](#Extension+init), +[load](#Extension+load), [activate](#Extension+activate), +[deactivate](#Extension+deactivate), [Extension#deinit](Extension#deinit)) are not call in +case this method is used. + +**Kind**: instance method of [Extension](#Extension) +**Returns**: Object.<string, (Promise\|\*)> - A map object of promises + resolved when all resources the extension requires are ready. + The resolved values will be pushed to the controller's state. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [prevParams] | Object.<string, string> | {} | Previous route parameters. | + + +* * * + +### extension.setState(statePatch)  +Patches the state of the controller using this extension by using the +provided object by copying the provided patch object fields to the +controller's state object. + +Note that the state is not patched recursively but by replacing the +values of the top-level fields of the state object. + +Note that the extension may modify only the fields of the state that it +has specified by its [getAllowedStateKeys](#Extension+getAllowedStateKeys) method. + +**Kind**: instance method of [Extension](#Extension) + +| Param | Type | Description | +| --- | --- | --- | +| statePatch | Object.<string, \*> | Patch of the controller's state to apply. | + + +* * * + +### extension.getState() ⇒ Object.<string, \*>  +Returns the current state of the controller using this extension. + +**Kind**: instance method of [Extension](#Extension) +**Returns**: Object.<string, \*> - The current state of the controller. + +* * * + +### extension.setPartialState(partialStatePatch)  +Patches the partial state of the extension. The extension is able +during its load and update phase receive state from active controller +using this extension and from previously loaded/updated extensions. + +**Kind**: instance method of [Extension](#Extension) + +| Param | Type | Description | +| --- | --- | --- | +| partialStatePatch | Object.<string, \*> | Patch of the controller's state to apply. | + + +* * * + +### extension.getPartialState() ⇒ Object.<string, \*>  +Returns the current partial state of the extension. + +**Kind**: instance method of [Extension](#Extension) +**Returns**: Object.<string, \*> - The current partial state of the extension. + +* * * + +### extension.clearPartialState()  +Clears the current partial state of the extension and sets it value to empty object. + +**Kind**: instance method of [Extension](#Extension) + +* * * + +### extension.setPageStateManager(pageStateManager)  +Sets the state manager used to manage the controller's state.. + +**Kind**: instance method of [Extension](#Extension) + +| Param | Type | Description | +| --- | --- | --- | +| pageStateManager | PageStateManager | The current state manager to use. | + + +* * * + +### extension.setRouteParams([params])  +Sets the current route parameters. This method is invoked before the +[init](#Extension+init) method. + +**Kind**: instance method of [Extension](#Extension) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [params] | Object.<string, string> | {} | The current route parameters. | + + +* * * + +### extension.getRouteParams() ⇒ Object.<string, string>  +Returns the current route parameters. + +**Kind**: instance method of [Extension](#Extension) +**Returns**: Object.<string, string> - The current route parameters. + +* * * + +### extension.getAllowedStateKeys() ⇒ Array.<string>  +Returns the names of the state fields that may be manipulated by this +extension. Manipulations of other fields of the state will be ignored. + +**Kind**: instance method of [Extension](#Extension) +**Returns**: Array.<string> - The names of the state fields that may be manipulated + by this extension. + +* * * + diff --git a/docs/_posts/2018-08-31-http-http-agent-impl.md b/docs/_posts/2018-08-31-http-http-agent-impl.md new file mode 100644 index 00000000..12fd7292 --- /dev/null +++ b/docs/_posts/2018-08-31-http-http-agent-impl.md @@ -0,0 +1,293 @@ +--- +category: "http" +title: "HttpAgentImpl" +--- + +## HttpAgentImpl  +Implementation of the HttpAgent interface with internal caching +of completed and ongoing HTTP requests and cookie storage. + +**Kind**: global class + +* [HttpAgentImpl](#HttpAgentImpl) + * [new HttpAgentImpl(proxy, cache, cookie, config)](#new_HttpAgentImpl_new) + * [._proxy](#HttpAgentImpl+_proxy) : HttpProxy + * [._cache](#HttpAgentImpl+_cache) : Cache + * [._cookie](#HttpAgentImpl+_cookie) : CookieStorage + * [._cacheOptions](#HttpAgentImpl+_cacheOptions) : Object.<string, string> + * [._defaultRequestOptions](#HttpAgentImpl+_defaultRequestOptions) : Object + * [._internalCacheOfPromises](#HttpAgentImpl+_internalCacheOfPromises) : Map.<string, Promise.<{status: number, body: \*, params: {method: string, url: string, transformedUrl: string, data: Object.<string, (boolean\|number\|string)>}, headers: Object.<string, string>, cached: boolean}>> + * [.get()](#HttpAgentImpl+get) + * [.post()](#HttpAgentImpl+post) + * [.put()](#HttpAgentImpl+put) + * [.patch()](#HttpAgentImpl+patch) + * [.delete()](#HttpAgentImpl+delete) + * [.getCacheKey()](#HttpAgentImpl+getCacheKey) + * [.setDefaultHeader()](#HttpAgentImpl+setDefaultHeader) + * [.clearDefaultHeaders()](#HttpAgentImpl+clearDefaultHeaders) + * [._requestWithCheckCache(method, url, data, [options])](#HttpAgentImpl+_requestWithCheckCache) ⇒ Promise.<HttpAgent~Response> + * [._getCachedData(method, url, data)](#HttpAgentImpl+_getCachedData) ⇒ Promise.<HttpAgent~Response> + * [._request(method, url, data, [options])](#HttpAgentImpl+_request) ⇒ Promise.<HttpAgent~Response> + * [._proxyResolved(response)](#HttpAgentImpl+_proxyResolved) ⇒ HttpAgent~Response + * [._proxyRejected(error)](#HttpAgentImpl+_proxyRejected) ⇒ Promise.<HttpAgent~Response> + * [._prepareOptions(options)](#HttpAgentImpl+_prepareOptions) ⇒ HttpAgent~RequestOptions + * [._getCacheKeySuffix(method, url, data)](#HttpAgentImpl+_getCacheKeySuffix) ⇒ string + * [._setCookiesFromResponse(agentResponse)](#HttpAgentImpl+_setCookiesFromResponse) + * [._saveAgentResponseToCache(agentResponse)](#HttpAgentImpl+_saveAgentResponseToCache) + + +* * * + +### new HttpAgentImpl(proxy, cache, cookie, config)  +Initializes the HTTP handler. + + +| Param | Type | Description | +| --- | --- | --- | +| proxy | HttpProxy | The low-level HTTP proxy for sending the HTTP requests. | +| cache | Cache | Cache to use for caching ongoing and completed requests. | +| cookie | CookieStorage | The cookie storage to use internally. | +| config | Object.<string, \*> | Configuration of the HTTP handler for the current application environment, specifying the various default request option values and cache option values. | + + +* * * + +### httpAgentImpl._proxy : HttpProxy  +HTTP proxy, used to execute the HTTP requests. + +**Kind**: instance property of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl._cache : Cache  +Internal request cache, used to cache completed request results. + +**Kind**: instance property of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl._cookie : CookieStorage  +Cookie storage, used to keep track of cookies received from the +server and send them with the subsequent requests to the server. + +**Kind**: instance property of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl._cacheOptions : Object.<string, string>  +Cache options. + +**Kind**: instance property of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl._defaultRequestOptions : Object  +Default request options. + +**Kind**: instance property of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl._internalCacheOfPromises : Map.<string, Promise.<{status: number, body: \*, params: {method: string, url: string, transformedUrl: string, data: Object.<string, (boolean\|number\|string)>}, headers: Object.<string, string>, cached: boolean}>>  +Internal request cache, used to cache ongoing requests. + +**Kind**: instance property of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.get()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.post()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.put()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.patch()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.delete()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.getCacheKey()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.setDefaultHeader()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl.clearDefaultHeaders()  +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +* * * + +### httpAgentImpl._requestWithCheckCache(method, url, data, [options]) ⇒ Promise.<HttpAgent~Response>  +Check cache and if data isnt available then make real request. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: Promise.<HttpAgent~Response> - A promise that resolves to the response + with body parsed as JSON. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method to use. | +| url | string | The URL to which the request should be sent. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to send with the request. | +| [options] | HttpAgent~RequestOptions | Optional request options. | + + +* * * + +### httpAgentImpl._getCachedData(method, url, data) ⇒ Promise.<HttpAgent~Response>  +Tests whether an ongoing or completed HTTP request for the specified URL +and data is present in the internal cache and, if it is, the method +returns a promise that resolves to the response body parsed as JSON. + +The method returns null if no such request is present in the +cache. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: Promise.<HttpAgent~Response> - A promise that will resolve to the + server response with the body parsed as JSON, or null if + no such request is present in the cache. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method used by the request. | +| url | string | The URL to which the request was made. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data sent to the server with the request. | + + +* * * + +### httpAgentImpl._request(method, url, data, [options]) ⇒ Promise.<HttpAgent~Response>  +Sends a new HTTP request using the specified method to the specified +url. The request will carry the provided data as query parameters if the +HTTP method is GET, but the data will be sent as request body for any +other request method. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: Promise.<HttpAgent~Response> - A promise that resolves to the response + with the body parsed as JSON. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | HTTP method to use. | +| url | string | The URL to which the request is sent. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data sent with the request. | +| [options] | HttpAgent~RequestOptions | Optional request options. | + + +* * * + +### httpAgentImpl._proxyResolved(response) ⇒ HttpAgent~Response  +Handles successful completion of an HTTP request by the HTTP proxy. + +The method also updates the internal cookie storage with the cookies +received from the server. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: HttpAgent~Response - The post-processed server response. + +| Param | Type | Description | +| --- | --- | --- | +| response | HttpAgent~Response | Server response. | + + +* * * + +### httpAgentImpl._proxyRejected(error) ⇒ Promise.<HttpAgent~Response>  +Handles rejection of the HTTP request by the HTTP proxy. The method +tests whether there are any remaining tries for the request, and if +there are any, it attempts re-send the request. + +The method rejects the internal request promise if there are no tries +left. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: Promise.<HttpAgent~Response> - A promise that will either resolve to a + server's response (with the body parsed as JSON) if there are + any tries left and the re-tried request succeeds, or rejects + with an error containing details of the cause of the request's + failure. + +| Param | Type | Description | +| --- | --- | --- | +| error | GenericError | The error provided by the HttpProxy, carrying the error parameters, such as the request url, data, method, options and other useful data. | + + +* * * + +### httpAgentImpl._prepareOptions(options) ⇒ HttpAgent~RequestOptions  +Prepares the provided request options object by filling in missing +options with default values and addding extra options used internally. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: HttpAgent~RequestOptions - Request options with set filled-in + default values for missing fields, and extra options used + internally. + +| Param | Type | Description | +| --- | --- | --- | +| options | HttpAgent~RequestOptions | Optional request options. | + + +* * * + +### httpAgentImpl._getCacheKeySuffix(method, url, data) ⇒ string  +Generates cache key suffix for an HTTP request to the specified URL with +the specified data. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) +**Returns**: string - The suffix of a cache key to use for a request to the + specified URL, carrying the specified data. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method used by the request. | +| url | string | The URL to which the request is sent. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data sent with the request. | + + +* * * + +### httpAgentImpl._setCookiesFromResponse(agentResponse)  +Sets all cookies from the Set-Cookie response header to the +cookie storage. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +| Param | Type | Description | +| --- | --- | --- | +| agentResponse | HttpAgent~Response | The response of the server. | + + +* * * + +### httpAgentImpl._saveAgentResponseToCache(agentResponse)  +Saves the server response to the cache to be used as the result of the +next request of the same properties. + +**Kind**: instance method of [HttpAgentImpl](#HttpAgentImpl) + +| Param | Type | Description | +| --- | --- | --- | +| agentResponse | HttpAgent~Response | The response of the server. | + + +* * * + diff --git a/docs/_posts/2018-08-31-http-http-agent.md b/docs/_posts/2018-08-31-http-http-agent.md new file mode 100644 index 00000000..46837a92 --- /dev/null +++ b/docs/_posts/2018-08-31-http-http-agent.md @@ -0,0 +1,196 @@ +--- +category: "http" +title: "HttpAgent" +--- + +## HttpAgent  +**Kind**: global interface + +* [HttpAgent](#HttpAgent) + * _instance_ + * [.get(url, data, [options])](#HttpAgent+get) ⇒ [Promise.<Response>](#HttpAgent..Response) + * [.post(url, data, [options])](#HttpAgent+post) ⇒ [Promise.<Response>](#HttpAgent..Response) + * [.put(url, data, [options])](#HttpAgent+put) ⇒ [Promise.<Response>](#HttpAgent..Response) + * [.patch(url, data, [options])](#HttpAgent+patch) ⇒ [Promise.<Response>](#HttpAgent..Response) + * [.delete(url, data, [options])](#HttpAgent+delete) ⇒ [Promise.<Response>](#HttpAgent..Response) + * [.getCacheKey(method, url, data)](#HttpAgent+getCacheKey) ⇒ string + * [.setDefaultHeader(header, value)](#HttpAgent+setDefaultHeader) ⇒ [HttpAgent](#HttpAgent) + * [.clearDefaultHeaders()](#HttpAgent+clearDefaultHeaders) ⇒ [HttpAgent](#HttpAgent) + * _inner_ + * [~RequestOptions](#HttpAgent..RequestOptions) : Object + * [~Response](#HttpAgent..Response) : Object + + +* * * + +### httpAgent.get(url, data, [options]) ⇒ [Promise.<Response>](#HttpAgent..Response)  +Sends an HTTP GET request to the specified URL, sending the provided +data as query parameters. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [Promise.<Response>](#HttpAgent..Response) - A promise that resolves to the + response. + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to which the request should be made. | +| data | Object.<string, (boolean\|number\|string)> | The data to send to the server as query parameters. | +| [options] | [RequestOptions](#HttpAgent..RequestOptions) | Optional request options. | + + +* * * + +### httpAgent.post(url, data, [options]) ⇒ [Promise.<Response>](#HttpAgent..Response)  +Sends an HTTP POST request to the specified URL, sending the provided +data as the request body. If an object is provided as the request data, +the data will be JSON-encoded. Sending other primitive non-string values +as the request body is not supported. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [Promise.<Response>](#HttpAgent..Response) - A promise that resolves to the + response. + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to which the request should be made. | +| data | string \| Object.<string, \*> | The data to send to the server as the request body. | +| [options] | [RequestOptions](#HttpAgent..RequestOptions) | Optional request options. | + + +* * * + +### httpAgent.put(url, data, [options]) ⇒ [Promise.<Response>](#HttpAgent..Response)  +Sends an HTTP PUT request to the specified URL, sending the provided +data as the request body. If an object is provided as the request data, +the data will be JSON-encoded. Sending other primitive non-string values +as the request body is not supported. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [Promise.<Response>](#HttpAgent..Response) - A promise that resolves to the + response. + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to which the request should be made. | +| data | string \| Object.<string, \*> | The data to send to the server as the request body. | +| [options] | [RequestOptions](#HttpAgent..RequestOptions) | Optional request options. | + + +* * * + +### httpAgent.patch(url, data, [options]) ⇒ [Promise.<Response>](#HttpAgent..Response)  +Sends an HTTP PATCH request to the specified URL, sending the provided +data as the request body. If an object is provided as the request data, +the data will be JSON-encoded. Sending other primitive non-string values +as the request body is not supported. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [Promise.<Response>](#HttpAgent..Response) - A promise that resolves to the + response. + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to which the request should be made. | +| data | string \| Object.<string, \*> | The data to send to the server as the request body. | +| [options] | [RequestOptions](#HttpAgent..RequestOptions) | Optional request options. | + + +* * * + +### httpAgent.delete(url, data, [options]) ⇒ [Promise.<Response>](#HttpAgent..Response)  +Sends an HTTP DELETE request to the specified URL, sending the provided +data as the request body. If an object is provided as the request data, +the data will be JSON-encoded. Sending other primitive non-string values +as the request body is not supported. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [Promise.<Response>](#HttpAgent..Response) - A promise that resolves to the + response. + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to which the request should be made. | +| data | string \| Object.<string, \*> | The data to send to the server as the request body. | +| [options] | [RequestOptions](#HttpAgent..RequestOptions) | Optional request options. | + + +* * * + +### httpAgent.getCacheKey(method, url, data) ⇒ string  +Generates a cache key to use for identifying a request to the specified +URL using the specified HTTP method, submitting the provided data. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: string - The key to use for identifying such a request in the + cache. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method used by the request. | +| url | string | The URL to which the request is sent. | +| data | Object.<string, string> | The data associated with the request. These can be either the query parameters or request body data. | + + +* * * + +### httpAgent.setDefaultHeader(header, value) ⇒ [HttpAgent](#HttpAgent)  +Sets the specified header to be sent with every subsequent HTTP request, +unless explicitly overridden by request options. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [HttpAgent](#HttpAgent) - This HTTP agent. + +| Param | Type | Description | +| --- | --- | --- | +| header | string | The name of the header. | +| value | string | The header value. To provide multiple values, separate them with commas (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2). | + + +* * * + +### httpAgent.clearDefaultHeaders() ⇒ [HttpAgent](#HttpAgent)  +Clears all configured default headers. + +**Kind**: instance method of [HttpAgent](#HttpAgent) +**Returns**: [HttpAgent](#HttpAgent) - This HTTP agent. + +* * * + +### HttpAgent~RequestOptions : Object  +Options for a request sent using the HTTP agent. + +**Kind**: inner typedef of [HttpAgent](#HttpAgent) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| [timeout] | number | Specifies the request timeout in milliseconds. | +| [ttl] | number | Specified how long the request may be cached in milliseconds. | +| [repeatRequest] | number | Specifies the maximum number of tries to repeat the request if the request fails. | +| [headers] | Object.<string, string> | Sets the additional request headers (the keys are case-insensitive header names, the values are header values). | +| [fetchOptions] | Object.<string, \*> | Sets the fetch request options. | +| [cache] | boolean | Flag that enables caching the HTTP request (enabled by default, also applies to requests in progress). | +| [withCredentials] | boolean | Flag that indicates whether the request should be made using credentials such as cookies or authorization headers. | +| [listeners] | Object | Listeners for request events. | +| [postProcessor] | function | Response post-processor applied just before the response is stored in the cache and returned. | + + +* * * + +### HttpAgent~Response : Object  +A response from the server. + +**Kind**: inner typedef of [HttpAgent](#HttpAgent) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| status | number | The HTTP response status code. | +| body | \* | The parsed response body, parsed as JSON. | +| params | HttpProxy~RequestParams | The original request params. | +| headers | Object.<string, string> | The response HTTP headers. | +| cached | boolean | Whether or not the response has been cached. | + + +* * * + diff --git a/docs/_posts/2018-08-31-http-http-proxy.md b/docs/_posts/2018-08-31-http-http-proxy.md new file mode 100644 index 00000000..7971e11b --- /dev/null +++ b/docs/_posts/2018-08-31-http-http-proxy.md @@ -0,0 +1,347 @@ +--- +category: "http" +title: "HttpProxy" +--- + +## HttpProxy  +Middleware proxy between [HttpAgent](HttpAgent) implementations and the +[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), +providing a Promise-oriented API for sending requests. + +**Kind**: global class + +* [HttpProxy](#HttpProxy) + * [new HttpProxy(transformer, window)](#new_HttpProxy_new) + * _instance_ + * [._transformer](#HttpProxy+_transformer) : UrlTransformer + * [._window](#HttpProxy+_window) : Window + * [._defaultHeaders](#HttpProxy+_defaultHeaders) : Map.<string, string> + * [.request(method, url, data, [options])](#HttpProxy+request) ⇒ Promise.<HttpAgent~Response> + * [.setDefaultHeader(header, value)](#HttpProxy+setDefaultHeader) + * [.clearDefaultHeaders()](#HttpProxy+clearDefaultHeaders) + * [.getErrorParams(method, url, data, options, status, body, cause)](#HttpProxy+getErrorParams) ⇒ [ErrorParams](#HttpProxy..ErrorParams) + * [.haveToSetCookiesManually()](#HttpProxy+haveToSetCookiesManually) ⇒ boolean + * [._processResponse(requestParams, response, responseBody)](#HttpProxy+_processResponse) ⇒ HttpAgent~Response + * [._headersToPlainObject(headers)](#HttpProxy+_headersToPlainObject) ⇒ Object.<string, string> + * [._processError(fetchError, requestParams)](#HttpProxy+_processError) ⇒ GenericError + * [._createError(cause, requestParams, status, responseBody)](#HttpProxy+_createError) ⇒ GenericError + * [._getFetchApi()](#HttpProxy+_getFetchApi) ⇒ function + * [._composeRequestParams(method, url, data, options)](#HttpProxy+_composeRequestParams) ⇒ [RequestParams](#HttpProxy..RequestParams) + * [._composeRequestInit(method, data, options)](#HttpProxy+_composeRequestInit) ⇒ RequestInit + * [._getContentType(method, data, options)](#HttpProxy+_getContentType) ⇒ string + * [._composeRequestUrl(url, data)](#HttpProxy+_composeRequestUrl) ⇒ string + * [._shouldRequestHaveBody(method, data)](#HttpProxy+_shouldRequestHaveBody) ⇒ boolean + * _inner_ + * [~RequestParams](#HttpProxy..RequestParams) : Object + * [~ErrorParams](#HttpProxy..ErrorParams) : Object + + +* * * + +### new HttpProxy(transformer, window)  +Initializes the HTTP proxy. + + +| Param | Type | Description | +| --- | --- | --- | +| transformer | UrlTransformer | A transformer of URLs to which requests are made. | +| window | Window | Helper for manipulating the global object `window` regardless of the client/server-side environment. | + + +* * * + +### httpProxy._transformer : UrlTransformer  +A transformer of URLs to which requests are made. + +**Kind**: instance property of [HttpProxy](#HttpProxy) + +* * * + +### httpProxy._window : Window  +Helper for manipulating the global object `window` regardless of the +client/server-side environment. + +**Kind**: instance property of [HttpProxy](#HttpProxy) + +* * * + +### httpProxy._defaultHeaders : Map.<string, string>  +The default HTTP headers to include with the HTTP requests, unless +overridden. + +**Kind**: instance property of [HttpProxy](#HttpProxy) + +* * * + +### httpProxy.request(method, url, data, [options]) ⇒ Promise.<HttpAgent~Response>  +Executes a HTTP request to the specified URL using the specified HTTP +method, carrying the provided data. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: Promise.<HttpAgent~Response> - A promise that resolves to the server + response. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method to use. | +| url | string | The URL to which the request should be made. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to be send to the server. The data will be included as query parameters if the request method is `GET` or `HEAD`, and as a request body for any other request method. | +| [options] | HttpAgent~RequestOptions | Optional request options. | + + +* * * + +### httpProxy.setDefaultHeader(header, value)  +Sets the specified default HTTP header. The header will be sent with all +subsequent HTTP requests unless reconfigured using this method, +overridden by request options, or cleared by +[clearDefaultHeaders](#HttpProxy+clearDefaultHeaders) method. + +**Kind**: instance method of [HttpProxy](#HttpProxy) + +| Param | Type | Description | +| --- | --- | --- | +| header | string | A header name. | +| value | string | A header value. | + + +* * * + +### httpProxy.clearDefaultHeaders()  +Clears all defaults headers sent with all requests. + +**Kind**: instance method of [HttpProxy](#HttpProxy) + +* * * + +### httpProxy.getErrorParams(method, url, data, options, status, body, cause) ⇒ [ErrorParams](#HttpProxy..ErrorParams)  +Gets an object that describes a failed HTTP request, providing +information about both the failure reported by the server and how the +request has been sent to the server. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: [ErrorParams](#HttpProxy..ErrorParams) - An object containing both the details of + the error and the request that lead to it. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method used to make the request. | +| url | string | The URL to which the request has been made. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data sent with the request. | +| options | HttpAgent~RequestOptions | Optional request options. | +| status | number | The HTTP response status code send by the server. | +| body | object | The body of HTTP error response (detailed information). | +| cause | Error | The low-level cause error. | + + +* * * + +### httpProxy.haveToSetCookiesManually() ⇒ boolean  +Returns `true` if cookies have to be processed manually by setting +`Cookie` HTTP header on requests and parsing the `Set-Cookie` HTTP +response header. + +The result of this method depends on the current application +environment, the client-side usually handles cookie processing +automatically, leading this method returning `false`. + +At the client-side, the method tests whether the client has cookies +enabled (which results in cookies being automatically processed by the +browser), and returns `true` or `false` accordingly. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: boolean - `true` if cookies are not processed automatically by + the environment and have to be handled manually by parsing + response headers and setting request headers, otherwise `false`. + +* * * + +### httpProxy._processResponse(requestParams, response, responseBody) ⇒ HttpAgent~Response  +Processes the response received from the server. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: HttpAgent~Response - The server's response along with all related + metadata. + +| Param | Type | Description | +| --- | --- | --- | +| requestParams | [RequestParams](#HttpProxy..RequestParams) | The original request's parameters. | +| response | Response | The Fetch API's `Response` object representing the server's response. | +| responseBody | \* | The server's response body. | + + +* * * + +### httpProxy._headersToPlainObject(headers) ⇒ Object.<string, string>  +Converts the provided Fetch API's `Headers` object to a plain object. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: Object.<string, string> - Converted headers. + +| Param | Type | Description | +| --- | --- | --- | +| headers | Headers | The headers to convert. | + + +* * * + +### httpProxy._processError(fetchError, requestParams) ⇒ GenericError  +Processes the provided Fetch API or internal error and creates an error +to expose to the calling API. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: GenericError - The error to provide to the calling API. + +| Param | Type | Description | +| --- | --- | --- | +| fetchError | Error | The internal error to process. | +| requestParams | [RequestParams](#HttpProxy..RequestParams) | An object representing the complete request parameters used to create and send the HTTP request. | + + +* * * + +### httpProxy._createError(cause, requestParams, status, responseBody) ⇒ GenericError  +Creates an error that represents a failed HTTP request. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: GenericError - The error representing a failed HTTP request. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| cause | Error | | The error's message. | +| requestParams | [RequestParams](#HttpProxy..RequestParams) | | An object representing the complete request parameters used to create and send the HTTP request. | +| status | number | | Server's response HTTP status code. | +| responseBody | \* | | The body of the server's response, if any. | + + +* * * + +### httpProxy._getFetchApi() ⇒ function  +Returns [window.fetch](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) +compatible API to use, depending on the method being used at the server +(polyfill) or client (native/polyfill) side. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: function - An + implementation of the Fetch API to use. + +* * * + +### httpProxy._composeRequestParams(method, url, data, options) ⇒ [RequestParams](#HttpProxy..RequestParams)  +Composes an object representing the HTTP request parameters from the +provided arguments. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: [RequestParams](#HttpProxy..RequestParams) - An object + representing the complete request parameters used to create and + send the HTTP request. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method to use. | +| url | string | The URL to which the request should be sent. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to send with the request. | +| options | HttpAgent~RequestOptions | Optional request options. | + + +* * * + +### httpProxy._composeRequestInit(method, data, options) ⇒ RequestInit  +Composes an init object, which can be used as a second argument of +`window.fetch` method. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: RequestInit - A `RequestInit` object of the Fetch API. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method to use. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to be send with a request. | +| options | HttpAgent~RequestOptions | Options provided by the HTTP agent. | + + +* * * + +### httpProxy._getContentType(method, data, options) ⇒ string  +Gets a `Content-Type` header value for defined method, data and options. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: string - A `Content-Type` header value. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method to use. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to be send with a request. | +| options | HttpAgent~RequestOptions | Options provided by the HTTP agent. | + + +* * * + +### httpProxy._composeRequestUrl(url, data) ⇒ string  +Transforms the provided URL using the current URL transformer and adds +the provided data to the URL's query string. + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: string - The transformed URL with the provided data attached to + its query string. + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to prepare for use with the fetch API. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to be attached to the query string. | + + +* * * + +### httpProxy._shouldRequestHaveBody(method, data) ⇒ boolean  +Checks if a request should have a body (`GET` and `HEAD` requests don't +have a body). + +**Kind**: instance method of [HttpProxy](#HttpProxy) +**Returns**: boolean - `true` if a request has a body, otherwise `false`. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The data to be send with a request. | + + +* * * + +### HttpProxy~RequestParams : Object  +An object representing the complete request parameters used to create and +send the HTTP request. + +**Kind**: inner typedef of [HttpProxy](#HttpProxy) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| method | string | The HTTP method. | +| url | string | The original URL to which to make the request. | +| transformedUrl | string | The actual URL to which to make the request, created by applying the URL transformer to the original URL. | +| data | Object.<string, (boolean\|number\|string\|Date)> | The request data, sent as query or body. | +| options | HttpAgent~RequestOptions | The high-level request options provided by the HTTP agent. | + + +* * * + +### HttpProxy~ErrorParams : Object  +An object that describes a failed HTTP request, providing +information about both the failure reported by the server and how the +request has been sent to the server. + +**Kind**: inner typedef of [HttpProxy](#HttpProxy) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| errorName | string | An error name. | +| status | number | The HTTP response status code send by the server. | +| body | object | The body of HTTP error response (detailed information). | +| cause | Error | The low-level cause error. | +| params | [RequestParams](#HttpProxy..RequestParams) | An object representing the complete request parameters used to create and send the HTTP request. | + + +* * * + diff --git a/docs/_posts/2018-08-31-http-status-code.md b/docs/_posts/2018-08-31-http-status-code.md new file mode 100644 index 00000000..294547d2 --- /dev/null +++ b/docs/_posts/2018-08-31-http-status-code.md @@ -0,0 +1,99 @@ +--- +category: "http" +title: "StatusCode" +--- + +## Members + +
+
OK : number
+

OK

+
+
NO_CONTENT : number
+

No content

+
+
BAD_REQUEST : number
+

Bad request

+
+
UNAUTHORIZED : number
+

Unauthorized

+
+
FORBIDDEN : number
+

Forbidden

+
+
NOT_FOUND : number
+

Not found

+
+
TIMEOUT : number
+

Request timeout

+
+
SERVER_ERROR : number
+

Internal Server Error

+
+
+ +## OK : number  +OK + +**Kind**: global variable + +* * * + +## NO_CONTENT : number  +No content + +**Kind**: global variable + +* * * + +## BAD_REQUEST : number  +Bad request + +**Kind**: global variable + +* * * + +## UNAUTHORIZED : number  +Unauthorized + +**Kind**: global variable + +* * * + +## FORBIDDEN : number  +Forbidden + +**Kind**: global variable + +* * * + +## NOT_FOUND : number  +Not found + +**Kind**: global variable + +* * * + +## TIMEOUT : number  +Request timeout + +**Kind**: global variable + +* * * + +## SERVER_ERROR : number  +Internal Server Error + +**Kind**: global variable + +* * * + +## StatusCode : enum  +HTTP status code constants, representing the HTTP status codes recognized +and processed by this proxy. + +**Kind**: global enum +**See**: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html + +* * * + diff --git a/docs/_posts/2018-08-31-http-url-transformer.md b/docs/_posts/2018-08-31-http-url-transformer.md new file mode 100644 index 00000000..2a1a56cd --- /dev/null +++ b/docs/_posts/2018-08-31-http-url-transformer.md @@ -0,0 +1,69 @@ +--- +category: "http" +title: "UrlTransformer" +--- + +## UrlTransformer  +Utility for transforming URLs according to the configured replacement rules. + +**Kind**: global class + +* [UrlTransformer](#UrlTransformer) + * [new UrlTransformer()](#new_UrlTransformer_new) + * [._rules](#UrlTransformer+_rules) : Object.<string, string> + * [.addRule(pattern, replacement)](#UrlTransformer+addRule) ⇒ [UrlTransformer](#UrlTransformer) + * [.clear()](#UrlTransformer+clear) ⇒ [UrlTransformer](#UrlTransformer) + * [.transform(str)](#UrlTransformer+transform) ⇒ string + + +* * * + +### new UrlTransformer()  +Initializes the URL transformer. + + +* * * + +### urlTransformer._rules : Object.<string, string>  +**Kind**: instance property of [UrlTransformer](#UrlTransformer) + +* * * + +### urlTransformer.addRule(pattern, replacement) ⇒ [UrlTransformer](#UrlTransformer)  +Adds the provided replacement rule to the rules used by this URL +transformer. + +**Kind**: instance method of [UrlTransformer](#UrlTransformer) +**Returns**: [UrlTransformer](#UrlTransformer) - This transformer. + +| Param | Type | Description | +| --- | --- | --- | +| pattern | string | Regexp patter to look for (must be escaped as if for use in the {@linkcode Regexp} constructor). | +| replacement | string | The replacement of the matched patter in any matched URL. | + + +* * * + +### urlTransformer.clear() ⇒ [UrlTransformer](#UrlTransformer)  +Clears all rules. + +**Kind**: instance method of [UrlTransformer](#UrlTransformer) +**Returns**: [UrlTransformer](#UrlTransformer) - This transformer. + +* * * + +### urlTransformer.transform(str) ⇒ string  +Applies all rules registered with this URL transformer to the provided +URL and returns the result. The rules will be applied in the order they +were registered. + +**Kind**: instance method of [UrlTransformer](#UrlTransformer) +**Returns**: string - Transformed URL. + +| Param | Type | Description | +| --- | --- | --- | +| str | string | The URL for transformation. | + + +* * * + diff --git a/docs/_posts/2018-08-31-main.md b/docs/_posts/2018-08-31-main.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-main.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-meta-meta-manager-impl.md b/docs/_posts/2018-08-31-meta-meta-manager-impl.md new file mode 100644 index 00000000..7fc9f339 --- /dev/null +++ b/docs/_posts/2018-08-31-meta-meta-manager-impl.md @@ -0,0 +1,120 @@ +--- +category: "meta" +title: "MetaManagerImpl" +--- + +## MetaManagerImpl  +Default implementation of the MetaManager interface. + +**Kind**: global class + +* [MetaManagerImpl](#MetaManagerImpl) + * [new MetaManagerImpl()](#new_MetaManagerImpl_new) + * [._title](#MetaManagerImpl+_title) : string + * [._metaName](#MetaManagerImpl+_metaName) : Map.<string, string> + * [._metaProperty](#MetaManagerImpl+_metaProperty) : Map.<string, string> + * [._link](#MetaManagerImpl+_link) : Map.<string, string> + * [.setTitle()](#MetaManagerImpl+setTitle) + * [.getTitle()](#MetaManagerImpl+getTitle) + * [.setMetaName()](#MetaManagerImpl+setMetaName) + * [.getMetaName()](#MetaManagerImpl+getMetaName) + * [.getMetaNames()](#MetaManagerImpl+getMetaNames) + * [.setMetaProperty()](#MetaManagerImpl+setMetaProperty) + * [.getMetaProperty()](#MetaManagerImpl+getMetaProperty) + * [.getMetaProperties()](#MetaManagerImpl+getMetaProperties) + * [.setLink()](#MetaManagerImpl+setLink) + * [.getLink()](#MetaManagerImpl+getLink) + * [.getLinks()](#MetaManagerImpl+getLinks) + + +* * * + +### new MetaManagerImpl()  +Initializes the meta page attributes manager. + + +* * * + +### metaManagerImpl._title : string  +The page title. + +**Kind**: instance property of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl._metaName : Map.<string, string>  +Storage of generic meta information. + +**Kind**: instance property of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl._metaProperty : Map.<string, string>  +Storage of specialized meta information. + +**Kind**: instance property of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl._link : Map.<string, string>  +Storage of generic link information. + +**Kind**: instance property of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.setTitle()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getTitle()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.setMetaName()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getMetaName()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getMetaNames()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.setMetaProperty()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getMetaProperty()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getMetaProperties()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.setLink()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getLink()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + +### metaManagerImpl.getLinks()  +**Kind**: instance method of [MetaManagerImpl](#MetaManagerImpl) + +* * * + diff --git a/docs/_posts/2018-08-31-meta-meta-manager.md b/docs/_posts/2018-08-31-meta-meta-manager.md new file mode 100644 index 00000000..e3ad55e6 --- /dev/null +++ b/docs/_posts/2018-08-31-meta-meta-manager.md @@ -0,0 +1,164 @@ +--- +category: "meta" +title: "MetaManager" +--- + +## MetaManager  +**Kind**: global interface + +* [MetaManager](#MetaManager) + * [.setTitle(title)](#MetaManager+setTitle) + * [.getTitle()](#MetaManager+getTitle) ⇒ string + * [.setMetaName(name, value)](#MetaManager+setMetaName) + * [.getMetaName(name)](#MetaManager+getMetaName) ⇒ string + * [.getMetaNames()](#MetaManager+getMetaNames) ⇒ Array.<string> + * [.setMetaProperty(name, value)](#MetaManager+setMetaProperty) + * [.getMetaProperty(name)](#MetaManager+getMetaProperty) ⇒ string + * [.getMetaProperties()](#MetaManager+getMetaProperties) ⇒ Array.<string> + * [.setLink(relation, reference)](#MetaManager+setLink) + * [.getLink(relation)](#MetaManager+getLink) ⇒ string + * [.getLinks()](#MetaManager+getLinks) ⇒ Array.<string> + + +* * * + +### metaManager.setTitle(title)  +Sets the page title. + +**Kind**: instance method of [MetaManager](#MetaManager) + +| Param | Type | Description | +| --- | --- | --- | +| title | string | The new page title. | + + +* * * + +### metaManager.getTitle() ⇒ string  +Returns the page title. The method returns an empty string if no page +title has been set yet. + +Note that the page title is cached internally by the meta manager and +may therefore differ from the current document title if it has been +modified by a 3rd party code. + +**Kind**: instance method of [MetaManager](#MetaManager) +**Returns**: string - The current page title. + +* * * + +### metaManager.setMetaName(name, value)  +Set the specified named meta information property. + +**Kind**: instance method of [MetaManager](#MetaManager) + +| Param | Type | Description | +| --- | --- | --- | +| name | string | Meta information property name, for example keywords. | +| value | string | The meta information value. | + + +* * * + +### metaManager.getMetaName(name) ⇒ string  +Returns the value of the specified named meta information property. The +method returns an empty string for missing meta information (to make the +returned value React-friendly). + +**Kind**: instance method of [MetaManager](#MetaManager) +**Returns**: string - The value of the generic meta information, or an empty + string. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The name of the named meta information property. | + + +* * * + +### metaManager.getMetaNames() ⇒ Array.<string>  +Returns the names of the currently specified named meta information +properties. + +**Kind**: instance method of [MetaManager](#MetaManager) +**Returns**: Array.<string> - The names of the currently specified named meta + information properties. + +* * * + +### metaManager.setMetaProperty(name, value)  +Sets the specified specialized meta information property. + +**Kind**: instance method of [MetaManager](#MetaManager) + +| Param | Type | Description | +| --- | --- | --- | +| name | string | Name of the specialized meta information property. | +| value | string | The value of the meta information property. | + + +* * * + +### metaManager.getMetaProperty(name) ⇒ string  +Returns the value of the specified specialized meta information +property. The method returns an empty string for missing meta +information (to make the returned value React-friendly). + +**Kind**: instance method of [MetaManager](#MetaManager) +**Returns**: string - The value of the specified meta information, or an + empty string. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The name of the specialized meta information property. | + + +* * * + +### metaManager.getMetaProperties() ⇒ Array.<string>  +Returns the names of the currently specified specialized meta +information properties. + +**Kind**: instance method of [MetaManager](#MetaManager) +**Returns**: Array.<string> - The names of the currently specified specialized meta + information properties. + +* * * + +### metaManager.setLink(relation, reference)  +Sets the specified specialized link information. + +**Kind**: instance method of [MetaManager](#MetaManager) + +| Param | Type | Description | +| --- | --- | --- | +| relation | string | The relation of the link target to the current page. | +| reference | string | The reference to the location of the related document, e.g. a URL. | + + +* * * + +### metaManager.getLink(relation) ⇒ string  +Return the reference to the specified related linked document. The +method returns an empty string for missing meta information (to make the +returned value React-friendly). + +**Kind**: instance method of [MetaManager](#MetaManager) +**Returns**: string - The reference to the location of the related document, + e.g. a URL. + +| Param | Type | Description | +| --- | --- | --- | +| relation | string | The relation of the link target to the current page. | + + +* * * + +### metaManager.getLinks() ⇒ Array.<string>  +Returns the relations of the currently set related documents linked to +the current page. + +**Kind**: instance method of [MetaManager](#MetaManager) + +* * * + diff --git a/docs/_posts/2018-08-31-namespace.md b/docs/_posts/2018-08-31-namespace.md new file mode 100644 index 00000000..47e9cb88 --- /dev/null +++ b/docs/_posts/2018-08-31-namespace.md @@ -0,0 +1,83 @@ +--- +category: "general" +title: "namespace" +--- + +## ~~Namespace~~  +***Deprecated*** + +Namespace creation, manipulation and traversal utility. This utility is used +to create semi-global shared namespaces for registering references to +interfaces, classes and constants of the application to provide access to +each other more easily than by using the ES6 import/export mechanism. + +**Kind**: global class + +* ~~[Namespace](#Namespace)~~ + * [new exports.Namespace()](#new_Namespace_new) + * ~~[.namespace(path)](#Namespace+namespace) ⇒ \*~~ + * [.has(path)](#Namespace+has) ⇒ boolean + * [.get(path)](#Namespace+get) ⇒ \* + + +* * * + +### new exports.Namespace()  +Initializes the namespace provider. + +This is a private constructor, you should use the exported ns +instance to create and use namespaces (see the examples). + + +* * * + +### ~~namespace.namespace(path) ⇒ \*~~  +***Deprecated*** + +Verifies that the specified path in namespace exists, creates it if it +does not, and returns the value at the specified path in the namespace. + +The method recursively creates all path parts in the namespaces as empty +plain objects for all path parts that do not exist yet, including the +last one. This means, that if called with a non-existing namespace path +as an argument, the return value will be the last created namespace +object. + +**Kind**: instance method of [Namespace](#Namespace) +**Returns**: \* - The value at the specified path in the namespace. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The namespace path. | + + +* * * + +### namespace.has(path) ⇒ boolean  +Verifies that the specified namespace path point to an existing +namespace or terminal value. + +**Kind**: instance method of [Namespace](#Namespace) +**Returns**: boolean - true if the namespace or terminal value exists + at the specified path. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The namespace path to test. | + + +* * * + +### namespace.get(path) ⇒ \*  +Return value for the specified namespace path point. + +**Kind**: instance method of [Namespace](#Namespace) +**Returns**: \* - The value at the specified path in the namespace. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The namespace path to test. | + + +* * * + diff --git a/docs/_posts/2018-08-31-object-container.md b/docs/_posts/2018-08-31-object-container.md new file mode 100644 index 00000000..2707e70d --- /dev/null +++ b/docs/_posts/2018-08-31-object-container.md @@ -0,0 +1,552 @@ +--- +category: "general" +title: "ObjectContainer" +--- + +## Classes + +
+
ObjectContainer
+

The Object Container is an enhanced dependency injector with support for +aliases and constants, and allowing to reference classes in the application +namespace by specifying their fully qualified names.

+
+
Entry
+

Object container entry, representing either a class, interface, constant or +an alias.

+
+
+ +## ObjectContainer  +The Object Container is an enhanced dependency injector with support for +aliases and constants, and allowing to reference classes in the application +namespace by specifying their fully qualified names. + +**Kind**: global class + +* [ObjectContainer](#ObjectContainer) + * [new ObjectContainer(namespace)](#new_ObjectContainer_new) + * _instance_ + * [._namespace](#ObjectContainer+_namespace) : ima.Namespace + * [._entries](#ObjectContainer+_entries) : Map.<(string\|function(new:\*, ...\*)\|function(...\*): \*), Entry.<\*>> + * [._bindingState](#ObjectContainer+_bindingState) : string + * [.bind(name, classConstructor, [dependencies])](#ObjectContainer+bind) ⇒ [ObjectContainer](#ObjectContainer) + * [.constant(name, value)](#ObjectContainer+constant) ⇒ [ObjectContainer](#ObjectContainer) + * [.inject(classConstructor, dependencies)](#ObjectContainer+inject) ⇒ [ObjectContainer](#ObjectContainer) + * [.provide(interfaceConstructor, implementationConstructor, dependencies)](#ObjectContainer+provide) ⇒ [ObjectContainer](#ObjectContainer) + * [.get(name)](#ObjectContainer+get) ⇒ T + * [.getConstructorOf(name)](#ObjectContainer+getConstructorOf) ⇒ function + * [.has(name)](#ObjectContainer+has) ⇒ boolean + * [.create(name, dependencies)](#ObjectContainer+create) ⇒ T + * [.clear()](#ObjectContainer+clear) ⇒ [ObjectContainer](#ObjectContainer) + * [.setBindingState(bindingState)](#ObjectContainer+setBindingState) + * [._getEntry(name)](#ObjectContainer+_getEntry) ⇒ Entry.<T> + * [._updateEntryValues(classConstructor, entry, dependencies)](#ObjectContainer+_updateEntryValues) + * [._createEntry(classConstructor, [dependencies], options)](#ObjectContainer+_createEntry) ⇒ T + * [._createInstanceFromEntry(entry, [dependencies])](#ObjectContainer+_createInstanceFromEntry) ⇒ T + * [._getEntryFromConstant(compositionName)](#ObjectContainer+_getEntryFromConstant) ⇒ Entry.<\*> + * [._getEntryFromNamespace(path)](#ObjectContainer+_getEntryFromNamespace) ⇒ Entry.<T> + * [._getEntryFromClassConstructor(classConstructor)](#ObjectContainer+_getEntryFromClassConstructor) ⇒ Entry.<T> + * _static_ + * [.PLUGIN_BINDING_STATE](#ObjectContainer.PLUGIN_BINDING_STATE) ⇒ string + * [.IMA_BINDING_STATE](#ObjectContainer.IMA_BINDING_STATE) ⇒ string + * [.APP_BINDING_STATE](#ObjectContainer.APP_BINDING_STATE) ⇒ string + + +* * * + +### new ObjectContainer(namespace)  +Initializes the object container. + + +| Param | Type | Description | +| --- | --- | --- | +| namespace | ima.Namespace | The namespace container, used to access classes and values using their fully qualified names. | + + +* * * + +### objectContainer._namespace : ima.Namespace  +The namespace container, used to access classes and values using +their fully qualified names. + +**Kind**: instance property of [ObjectContainer](#ObjectContainer) + +* * * + +### objectContainer._entries : Map.<(string\|function(new:\*, ...\*)\|function(...\*): \*), Entry.<\*>>  +**Kind**: instance property of [ObjectContainer](#ObjectContainer) + +* * * + +### objectContainer._bindingState : string  +The current binding state. + +The {@linkcode setBindingState()} method may be called for changing +object container binding state only by the bootstrap script. + +**Kind**: instance property of [ObjectContainer](#ObjectContainer) + +* * * + +### objectContainer.bind(name, classConstructor, [dependencies]) ⇒ [ObjectContainer](#ObjectContainer)  +Binds the specified class or factory function and dependencies to the +specified alias. Binding a class or factory function to an alias allows +the class or function to be specied as a dependency by specifying the +alias and creating new instances by referring to the class or function +by the alias. + +Also note that the same class or function may be bound to several +aliases and each may use different dependencies. + +The alias will use the default dependencies bound for the class if no +dependencies are provided. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: [ObjectContainer](#ObjectContainer) - This object container. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| name | string | Alias name. | +| classConstructor | function \| function | The class constructor or a factory function. | +| [dependencies] | Array.<\*> | The dependencies to pass into the constructor or factory function. | + + +* * * + +### objectContainer.constant(name, value) ⇒ [ObjectContainer](#ObjectContainer)  +Defines a new constant registered with this object container. Note that +this is the only way of passing string values to constructors +because the object container treats strings as class, interface, alias +or constant names. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: [ObjectContainer](#ObjectContainer) - This object container. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The constant name. | +| value | \* | The constant value. | + + +* * * + +### objectContainer.inject(classConstructor, dependencies) ⇒ [ObjectContainer](#ObjectContainer)  +Configures the object loader with the specified default dependencies for +the specified class. + +New instances of the class created by this object container will receive +the provided dependencies into constructor unless custom dependencies +are provided. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: [ObjectContainer](#ObjectContainer) - This object container. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| classConstructor | function | The class constructor. | +| dependencies | Array.<\*> | The dependencies to pass into the constructor function. | + + +* * * + +### objectContainer.provide(interfaceConstructor, implementationConstructor, dependencies) ⇒ [ObjectContainer](#ObjectContainer)  +Configures the default implementation of the specified interface to use +when an implementation provider of the specified interface is requested +from this object container. + +The implementation constructor will obtain the provided default +dependencies or the dependencies provided to the create() +method. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: [ObjectContainer](#ObjectContainer) - This object container. +**Template**: Interface +**Template**: Implementation extends Interface + +| Param | Type | Description | +| --- | --- | --- | +| interfaceConstructor | function | The constructor of the interface representing the service. | +| implementationConstructor | function | The constructor of the class implementing the service interface. | +| dependencies | Array.<\*> | The dependencies to pass into the constructor function. | + + +* * * + +### objectContainer.get(name) ⇒ T  +Retrieves the shared instance or value of the specified constant, alias, +class or factory function, interface, or fully qualified namespace path +(the method checks these in this order in case of a name clash). + +The instance or value is created lazily the first time it is requested. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: T - The shared instance or value. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| name | string \| function \| function | The name of the alias, class, interface, or the class, interface or a factory function. | + + +* * * + +### objectContainer.getConstructorOf(name) ⇒ function  +Returns the class constructor function of the specified class. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: function - The constructor function. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| name | string \| function | The name by which the class is registered with this object container. | + + +* * * + +### objectContainer.has(name) ⇒ boolean  +Returns true if the specified object, class or resource is +registered with this object container. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: boolean - true if the specified object, class or + resource is registered with this object container. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| name | string \| function | The resource name. | + + +* * * + +### objectContainer.create(name, dependencies) ⇒ T  +Creates a new instance of the class or retrieves the value generated by +the factory function identified by the provided name, class, interface, +or factory function, passing in the provided dependencies. + +The method uses the dependencies specified when the class, interface or +factory function has been registered with the object container if no +custom dependencies are provided. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: T - Created instance or generated value. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| name | string \| function \| function | The name of the alias, class, interface, or the class, interface or a factory function to use. | +| dependencies | Array.<\*> | The dependencies to pass into the constructor or factory function. | + + +* * * + +### objectContainer.clear() ⇒ [ObjectContainer](#ObjectContainer)  +Clears all entries from this object container and resets the locking +mechanism of this object container. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: [ObjectContainer](#ObjectContainer) - This object container. + +* * * + +### objectContainer.setBindingState(bindingState)  +**Kind**: instance method of [ObjectContainer](#ObjectContainer) + +| Param | Type | +| --- | --- | +| bindingState | string | + + +* * * + +### objectContainer._getEntry(name) ⇒ Entry.<T>  +Retrieves the entry for the specified constant, alias, class or factory +function, interface, or fully qualified namespace path (the method +checks these in this order in case of a name clash). + +The method retrieves an existing entry even if a qualified namespace +path is provided (if the target class or interface has been configured +in this object container). + +The method throws an Error if no such constant, alias, +registry, interface implementation is known to this object container and +the provided identifier is not a valid namespace path specifying an +existing class, interface or value. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: Entry.<T> - The retrieved entry. +**Throws**: + +- Error If no such constant, alias, registry, interface + implementation is known to this object container. + +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| name | string \| function | Name of a constant or alias, factory function, class or interface constructor, or a fully qualified namespace path. | + + +* * * + +### objectContainer._updateEntryValues(classConstructor, entry, dependencies)  +The method update classConstructor and dependencies for defined entry. +The entry throw Error for constants and if you try override dependencies +more than once. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| classConstructor | function \| function | The class constructor or factory function. | +| entry | [Entry](#Entry) | The entry representing the class that should have its instance created or factory faction to use to create a value. | +| dependencies | Array.<\*> | The dependencies to pass into the constructor or factory function. | + + +* * * + +### objectContainer._createEntry(classConstructor, [dependencies], options) ⇒ T  +Creates a new entry for the provided class or factory function, the +provided dependencies and entry options. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: T - Created instance or generated value. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| classConstructor | function \| function | The class constructor or factory function. | +| [dependencies] | Array.<\*> | The dependencies to pass into the constructor or factory function. | +| options | Object | | + + +* * * + +### objectContainer._createInstanceFromEntry(entry, [dependencies]) ⇒ T  +Creates a new instance of the class or retrieves the value generated by +the factory function represented by the provided entry, passing in the +provided dependencies. + +The method uses the dependencies specified by the entry if no custom +dependencies are provided. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: T - Created instance or generated value. +**Template**: T + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| entry | Entry.<T> | | The entry representing the class that should have its instance created or factory faction to use to create a value. | +| [dependencies] | Array.<\*> | [] | The dependencies to pass into the constructor or factory function. | + + +* * * + +### objectContainer._getEntryFromConstant(compositionName) ⇒ Entry.<\*>  +Retrieves the constant value denoted by the provided fully qualified +composition name. + +The method returns the entry for the constant if the constant is registered +with this object container, otherwise return null. + +Finally, if the constant composition name does not resolve to value, +the method return null. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: Entry.<\*> - An entry representing the value at the specified + composition name in the constants. The method returns null + if the specified composition name does not exist in the constants. + +| Param | Type | +| --- | --- | +| compositionName | string | + + +* * * + +### objectContainer._getEntryFromNamespace(path) ⇒ Entry.<T>  +Retrieves the class denoted by the provided fully qualified name within +the application namespace. + +The method then checks whether there are dependecies configured for the +class, no matter whether the class is an implementation class or an +"interface" class. + +The method returns the entry for the class if the class is registered +with this object container, otherwise an unregistered entry is created +and returned. + +Finally, if the namespace path does not resolve to a class, the method +return an unregistered entry resolved to the value denoted by the +namespace path. + +Alternatively, if a constructor function is passed in instead of a +namespace path, the method returns null. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: Entry.<T> - An entry representing the value or class at the + specified path in the namespace. The method returns null + if the specified path does not exist in the namespace. +**Template**: T + +| Param | Type | Description | +| --- | --- | --- | +| path | string \| function | Namespace path pointing to a class or a value in the application namespace, or a constructor function. | + + +* * * + +### objectContainer._getEntryFromClassConstructor(classConstructor) ⇒ Entry.<T>  +Retrieves the class denoted by the provided class constructor. + +The method then checks whether there are defined $dependecies +property for class. Then the class is registered to this object +container. + +The method returns the entry for the class if the specified class +does not have defined $dependencies property return +null. + +**Kind**: instance method of [ObjectContainer](#ObjectContainer) +**Returns**: Entry.<T> - An entry representing the value at the specified + classConstructor. The method returns null + if the specified classConstructor does not have defined + $dependencies. +**Template**: T + +| Param | Type | +| --- | --- | +| classConstructor | function | + + +* * * + +### ObjectContainer.PLUGIN_BINDING_STATE ⇒ string  +Returns constant for plugin binding state. + +When the object container is in plugin binding state, it is impossible +to register new aliases using the {@linkcode bind()} method and register +new constant using the {@linkcode constant()} method, or override the +default class dependencies of any already-configured class using the +{@linkcode inject()} method (classes that were not configured yet may be +configured using the {@linkcode inject()} method or {@linkcode provide()} +method). + +This prevents the unpriviledged code (e.g. 3rd party plugins) from +overriding the default dependency configuration provided by ima, or +overriding the configuration of a 3rd party plugin by another 3rd party +plugin. + +The application itself has always access to the unlocked object +container. + +**Kind**: static property of [ObjectContainer](#ObjectContainer) +**Returns**: string - The plugin binding state. + +* * * + +### ObjectContainer.IMA_BINDING_STATE ⇒ string  +Returns constant for IMA binding state. + +When the object container is in ima binding state, it is possible +to register new aliases using the {@linkcode bind()} method and register +new constant using the {@linkcode constant()} method, or override the +default class dependencies of any already-configured class using the +{@linkcode inject()} method (classes that were not configured yet may be +configured using the {@linkcode inject()} method or {@linkcode provide()} +method). + +**Kind**: static property of [ObjectContainer](#ObjectContainer) +**Returns**: string - The IMA binding state. + +* * * + +### ObjectContainer.APP_BINDING_STATE ⇒ string  +Returns constant for app binding state. + +When the object container is in app binding state, it is possible +to register new aliases using the {@linkcode bind()} method and register +new constant using the {@linkcode constant()} method, or override the +default class dependencies of any already-configured class using the +{@linkcode inject()} method (classes that were not configured yet may be +configured using the {@linkcode inject()} method or {@linkcode provide()} +method). + +**Kind**: static property of [ObjectContainer](#ObjectContainer) +**Returns**: string - The app binding state. + +* * * + +## Entry  +Object container entry, representing either a class, interface, constant or +an alias. + +**Kind**: global class +**Template**: T + +* [Entry](#Entry) + * [new Entry(classConstructor, [dependencies], [options])](#new_Entry_new) + * [.classConstructor](#Entry+classConstructor) : function \| function + * [.sharedInstance](#Entry+sharedInstance) : T + * [._options](#Entry+_options) : Object + * [._dependencies](#Entry+_dependencies) : Array.<\*> + * [._overrideCounter](#Entry+_overrideCounter) : number + + +* * * + +### new Entry(classConstructor, [dependencies], [options])  +Initializes the entry. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| classConstructor | function \| function | | The class constructor or constant value getter. | +| [dependencies] | Array.<\*> | [] | The dependencies to pass into the constructor function. | +| [options] | Object | | The Entry options. | + + +* * * + +### entry.classConstructor : function \| function  +The constructor of the class represented by this entry, or the +getter of the value of the constant represented by this entry. + +**Kind**: instance property of [Entry](#Entry) + +* * * + +### entry.sharedInstance : T  +The shared instance of the class represented by this entry. + +**Kind**: instance property of [Entry](#Entry) + +* * * + +### entry._options : Object  +The Entry options. + +**Kind**: instance property of [Entry](#Entry) + +* * * + +### entry._dependencies : Array.<\*>  +Dependencies of the class constructor of the class represented by +this entry. + +**Kind**: instance property of [Entry](#Entry) + +* * * + +### entry._overrideCounter : number  +The override counter + +**Kind**: instance property of [Entry](#Entry) + +* * * + diff --git a/docs/_posts/2018-08-31-page-abstract-component.md b/docs/_posts/2018-08-31-page-abstract-component.md new file mode 100644 index 00000000..e1917663 --- /dev/null +++ b/docs/_posts/2018-08-31-page-abstract-component.md @@ -0,0 +1,157 @@ +--- +category: "page" +title: "AbstractComponent" +--- + +## *AbstractComponent*  +The base class for all view components. + +**Kind**: global abstract class + +* *[AbstractComponent](#AbstractComponent)* + * *[new AbstractComponent(props, context)](#new_AbstractComponent_new)* + * *[._utils](#AbstractComponent+_utils) : Object.<string, \*>* + * *[.utils](#AbstractComponent+utils) ⇒ Object.<string, \*>* + * *[.localize(key, [params])](#AbstractComponent+localize) ⇒ string* + * *[.link(name, [params])](#AbstractComponent+link) ⇒ string* + * *[.cssClasses(classRules, includeComponentClassName)](#AbstractComponent+cssClasses) ⇒ string* + * *[.fire(eventName, [data])](#AbstractComponent+fire)* + * *[.listen(eventTarget, eventName, listener)](#AbstractComponent+listen)* + * *[.unlisten(eventTarget, eventName, listener)](#AbstractComponent+unlisten)* + + +* * * + +### *new AbstractComponent(props, context)*  +Initializes the component. + + +| Param | Type | Description | +| --- | --- | --- | +| props | Object.<string, \*> | The component properties. | +| context | Object.<string, \*> | The component context. | + + +* * * + +### *abstractComponent._utils : Object.<string, \*>*  +The view utilities, initialized lazily upon first use from either +the context, or the component's props. + +**Kind**: instance property of [AbstractComponent](#AbstractComponent) + +* * * + +### *abstractComponent.utils ⇒ Object.<string, \*>*  +Returns the utilities for the view components. The returned value is the +value bound to the $Utils object container constant. + +**Kind**: instance property of [AbstractComponent](#AbstractComponent) +**Returns**: Object.<string, \*> - The utilities for the view components. + +* * * + +### *abstractComponent.localize(key, [params]) ⇒ string*  +Returns the localized phrase identified by the specified key. The +placeholders in the localization phrase will be replaced by the provided +values. + +**Kind**: instance method of [AbstractComponent](#AbstractComponent) +**Returns**: string - Localized phrase. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | Localization key. | +| [params] | Object.<string, (number\|string)> | Values for replacing the placeholders in the localization phrase. | + + +* * * + +### *abstractComponent.link(name, [params]) ⇒ string*  +Generates an absolute URL using the provided route name (see the +app/config/routes.js file). The provided parameters will +replace the placeholders in the route pattern, while the extraneous +parameters will be appended to the generated URL's query string. + +**Kind**: instance method of [AbstractComponent](#AbstractComponent) +**Returns**: string - The generated URL. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The route name. | +| [params] | Object.<string, (number\|string)> | Router parameters and extraneous parameters to add to the URL as a query string. | + + +* * * + +### *abstractComponent.cssClasses(classRules, includeComponentClassName) ⇒ string*  +Generate a string of CSS classes from the properties of the passed-in +object that resolve to true. + +**Kind**: instance method of [AbstractComponent](#AbstractComponent) +**Returns**: string - String of CSS classes that had their property resolved + to true. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| classRules | string \| Object.<string, boolean> | | CSS classes in a string separated by whitespace, or a map of CSS class names to boolean values. The CSS class name will be included in the result only if the value is true. | +| includeComponentClassName | boolean | false | | + +**Example** +```js +this.cssClasses('my-class my-class-modificator', true); +``` +**Example** +```js +this.cssClasses({ + 'my-class': true, + 'my-class-modificator': this.props.modificator + }, true); +``` + +* * * + +### *abstractComponent.fire(eventName, [data])*  +Creates and sends a new IMA.js DOM custom event from this component. + +**Kind**: instance method of [AbstractComponent](#AbstractComponent) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| eventName | string | | The name of the event. | +| [data] | \* | | Data to send within the event. | + + +* * * + +### *abstractComponent.listen(eventTarget, eventName, listener)*  +Registers the provided event listener for execution whenever an IMA.js +DOM custom event of the specified name occurs at the specified event +target. + +**Kind**: instance method of [AbstractComponent](#AbstractComponent) + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | React.Element \| EventTarget | The react component or event target at which the listener should listen for the event. | +| eventName | string | The name of the event for which to listen. | +| listener | function | The listener for event to register. | + + +* * * + +### *abstractComponent.unlisten(eventTarget, eventName, listener)*  +Deregisters the provided event listener for an IMA.js DOM custom event +of the specified name at the specified event target. + +**Kind**: instance method of [AbstractComponent](#AbstractComponent) + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | React.Element \| EventTarget | The react component or event target at which the listener should listen for the event. | +| eventName | string | The name of the event for which to listen. | +| listener | function | The listener for event to register. | + + +* * * + diff --git a/docs/_posts/2018-08-31-page-abstract-document-view.md b/docs/_posts/2018-08-31-page-abstract-document-view.md new file mode 100644 index 00000000..8ef7c092 --- /dev/null +++ b/docs/_posts/2018-08-31-page-abstract-document-view.md @@ -0,0 +1,72 @@ +--- +category: "page" +title: "AbstractDocumentView" +--- + +## *AbstractDocumentView*  +The base class for document view components. The document view components +create the basic markup, i.e. the html or head elements, +along with an element that will contain the view associated with the current +route. + +Note that the document views are always rendered only at the server-side and +cannot be switched at the client-side. Because of this, the document view +component must be pure and cannot contain a state. + +**Kind**: global abstract class + +* *[AbstractDocumentView](#AbstractDocumentView)* + * **[.masterElementId](#AbstractDocumentView.masterElementId) ⇒ string** + * *[.masterElementId](#AbstractDocumentView.masterElementId)* + * *[.propTypes](#AbstractDocumentView.propTypes) ⇒ Object* + * *[.contextTypes](#AbstractDocumentView.contextTypes)* + + +* * * + +### **AbstractDocumentView.masterElementId ⇒ string**  +Returns the ID of the element (the value of the id attribute) +generated by this component that will contain the rendered page view. + +**Kind**: static abstract property of [AbstractDocumentView](#AbstractDocumentView) +**Returns**: string - The ID of the element generated by this component that + will contain the rendered page view. + +* * * + +### *AbstractDocumentView.masterElementId*  +Setter for the ID of the element (the value of the id attribute) +generated by this component that will contain the rendered page view. + +This setter is used only for compatibility with the public class fields +and can only be used once per component. + +**Kind**: static property of [AbstractDocumentView](#AbstractDocumentView) + +| Param | Type | Description | +| --- | --- | --- | +| masterElementId | string | The ID of the element generated by this component that will contain the rendered page view. | + + +* * * + +### *AbstractDocumentView.propTypes ⇒ Object*  +Returns the expected types of the props passed to this component. + +The metaManager is used to generate the meta tags in the +head and the content of the title element. The +page contains the rendered HTML of the current view. The +revivalSettings contains a JavaScript snippet that initializes +the configuration of the IMA platform at the client-side. + +**Kind**: static property of [AbstractDocumentView](#AbstractDocumentView) +**Returns**: Object - The expected + types of the props passed to this component. + +* * * + +### *AbstractDocumentView.contextTypes*  +**Kind**: static property of [AbstractDocumentView](#AbstractDocumentView) + +* * * + diff --git a/docs/_posts/2018-08-31-page-abstract-pure-component.md b/docs/_posts/2018-08-31-page-abstract-pure-component.md new file mode 100644 index 00000000..a6f588e6 --- /dev/null +++ b/docs/_posts/2018-08-31-page-abstract-pure-component.md @@ -0,0 +1,166 @@ +--- +category: "page" +title: "AbstractPureComponent" +--- + +## *AbstractPureComponent*  +The base class for all pure (state-less) view components. + +Unlike the "regular" components, pure components do not have any external +state, and therefore are pure functions of their props and state. This +allows for some nice optimizations on react's part (see the link). + +Because of this, this class does not provide all the APIs provided by the +{@linkcode AbstractComponent} class (e.g. listen) as there is next +to none use of them with pure components. + +**Kind**: global abstract class +**See**: https://facebook.github.io/react/docs/react-api.html#react.purecomponent + +* *[AbstractPureComponent](#AbstractPureComponent)* + * *[new AbstractPureComponent(props, context)](#new_AbstractPureComponent_new)* + * *[._utils](#AbstractPureComponent+_utils) : Object.<string, \*>* + * *[.utils](#AbstractPureComponent+utils) ⇒ Object.<string, \*>* + * *[.localize(key, [params])](#AbstractPureComponent+localize) ⇒ string* + * *[.link(name, [params])](#AbstractPureComponent+link) ⇒ string* + * *[.cssClasses(classRules, includeComponentClassName)](#AbstractPureComponent+cssClasses) ⇒ string* + * *[.fire(eventName, [data])](#AbstractPureComponent+fire)* + * *[.listen(eventTarget, eventName, listener)](#AbstractPureComponent+listen)* + * *[.unlisten(eventTarget, eventName, listener)](#AbstractPureComponent+unlisten)* + + +* * * + +### *new AbstractPureComponent(props, context)*  +Initializes the component. + + +| Param | Type | Description | +| --- | --- | --- | +| props | Object.<string, \*> | The component properties. | +| context | Object.<string, \*> | The component context. | + + +* * * + +### *abstractPureComponent._utils : Object.<string, \*>*  +The view utilities, initialized lazily upon first use from either +the context, or the component's props. + +**Kind**: instance property of [AbstractPureComponent](#AbstractPureComponent) + +* * * + +### *abstractPureComponent.utils ⇒ Object.<string, \*>*  +Returns the utilities for the view components. The returned value is the +value bound to the $Utils object container constant. + +**Kind**: instance property of [AbstractPureComponent](#AbstractPureComponent) +**Returns**: Object.<string, \*> - The utilities for the view components. + +* * * + +### *abstractPureComponent.localize(key, [params]) ⇒ string*  +Returns the localized phrase identified by the specified key. The +placeholders in the localization phrase will be replaced by the provided +values. + +**Kind**: instance method of [AbstractPureComponent](#AbstractPureComponent) +**Returns**: string - Localized phrase. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | Localization key. | +| [params] | Object.<string, (number\|string)> | Values for replacing the placeholders in the localization phrase. | + + +* * * + +### *abstractPureComponent.link(name, [params]) ⇒ string*  +Generates an absolute URL using the provided route name (see the +app/config/routes.js file). The provided parameters will +replace the placeholders in the route pattern, while the extraneous +parameters will be appended to the generated URL's query string. + +**Kind**: instance method of [AbstractPureComponent](#AbstractPureComponent) +**Returns**: string - The generated URL. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The route name. | +| [params] | Object.<string, (number\|string)> | Router parameters and extraneous parameters to add to the URL as a query string. | + + +* * * + +### *abstractPureComponent.cssClasses(classRules, includeComponentClassName) ⇒ string*  +Generate a string of CSS classes from the properties of the passed-in +object that resolve to true. + +**Kind**: instance method of [AbstractPureComponent](#AbstractPureComponent) +**Returns**: string - String of CSS classes that had their property resolved + to true. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| classRules | string \| Object.<string, boolean> | | CSS classes in a string separated by whitespace, or a map of CSS class names to boolean values. The CSS class name will be included in the result only if the value is true. | +| includeComponentClassName | boolean | false | | + +**Example** +```js +this.cssClasses('my-class my-class-modificator', true); +``` +**Example** +```js +this.cssClasses({ + 'my-class': true, + 'my-class-modificator': this.props.modificator + }, true); +``` + +* * * + +### *abstractPureComponent.fire(eventName, [data])*  +Creates and sends a new IMA.js DOM custom event from this component. + +**Kind**: instance method of [AbstractPureComponent](#AbstractPureComponent) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| eventName | string | | The name of the event. | +| [data] | \* | | Data to send within the event. | + + +* * * + +### *abstractPureComponent.listen(eventTarget, eventName, listener)*  +Registers the provided event listener for execution whenever an IMA.js +DOM custom event of the specified name occurs at the specified event +target. + +**Kind**: instance method of [AbstractPureComponent](#AbstractPureComponent) + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | React.Element \| EventTarget | The react component or event target at which the listener should listen for the event. | +| eventName | string | The name of the event for which to listen. | +| listener | function | The listener for event to register. | + + +* * * + +### *abstractPureComponent.unlisten(eventTarget, eventName, listener)*  +Deregisters the provided event listener for an IMA.js DOM custom event +of the specified name at the specified event target. + +**Kind**: instance method of [AbstractPureComponent](#AbstractPureComponent) + +| Param | Type | Description | +| --- | --- | --- | +| eventTarget | React.Element \| EventTarget | The react component or event target at which the listener should listen for the event. | +| eventName | string | The name of the event for which to listen. | +| listener | function | The listener for event to register. | + + +* * * + diff --git a/docs/_posts/2018-08-31-page-page-factory.md b/docs/_posts/2018-08-31-page-page-factory.md new file mode 100644 index 00000000..7aaca2b9 --- /dev/null +++ b/docs/_posts/2018-08-31-page-page-factory.md @@ -0,0 +1,90 @@ +--- +category: "page" +title: "PageFactory" +--- + +## PageFactory  +Factory for page. + +**Kind**: global class + +* [PageFactory](#PageFactory) + * [new PageFactory(oc)](#new_PageFactory_new) + * [._oc](#PageFactory+_oc) : ObjectContainer + * [.createController(controller)](#PageFactory+createController) ⇒ Controller + * [.createView(view)](#PageFactory+createView) ⇒ function + * [.decorateController(controller)](#PageFactory+decorateController) ⇒ Controller + * [.decoratePageStateManager(pageStateManager, allowedStateKeys)](#PageFactory+decoratePageStateManager) ⇒ PageStateManager + + +* * * + +### new PageFactory(oc)  +Factory used by page management classes. + + +| Param | Type | +| --- | --- | +| oc | ObjectContainer | + + +* * * + +### pageFactory._oc : ObjectContainer  +The current application object container. + +**Kind**: instance property of [PageFactory](#PageFactory) + +* * * + +### pageFactory.createController(controller) ⇒ Controller  +Create new instance of {@linkcode Controller}. + +**Kind**: instance method of [PageFactory](#PageFactory) + +| Param | Type | +| --- | --- | +| controller | string \| function | + + +* * * + +### pageFactory.createView(view) ⇒ function  +Retrieves the specified react component class. + +**Kind**: instance method of [PageFactory](#PageFactory) +**Returns**: function - The react component class + constructor. + +| Param | Type | Description | +| --- | --- | --- | +| view | string \| function | The namespace referring to a react component class, or a react component class constructor. | + + +* * * + +### pageFactory.decorateController(controller) ⇒ Controller  +Returns decorated controller for ease setting seo params in controller. + +**Kind**: instance method of [PageFactory](#PageFactory) + +| Param | Type | +| --- | --- | +| controller | Controller | + + +* * * + +### pageFactory.decoratePageStateManager(pageStateManager, allowedStateKeys) ⇒ PageStateManager  +Returns decorated page state manager for extension. + +**Kind**: instance method of [PageFactory](#PageFactory) + +| Param | Type | +| --- | --- | +| pageStateManager | PageStateManager | +| allowedStateKeys | Array.<string> | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagecomponent-helpers.md b/docs/_posts/2018-08-31-pagecomponent-helpers.md new file mode 100644 index 00000000..b7e1facd --- /dev/null +++ b/docs/_posts/2018-08-31-pagecomponent-helpers.md @@ -0,0 +1,228 @@ +--- +category: "page" +title: "componentHelpers" +--- + +## Functions + +
+
getContextTypes(classConstructor) ⇒ Object.<string, function(...*): boolean>
+

Retrieves the context type declarations for the specified component.

+
+
setContextTypes(classConstructor, contextTypes) ⇒ Object.<string, function(...*): boolean>
+

Overrides the previously associated context type declarations for the +specified component to the provided ones.

+
+
getUtils(props, context) ⇒ Object.<string, *>
+

Retrieves the view utilities from the component's current context or +properties (preferring the context).

+
+
localize(component, key, [params]) ⇒ string
+

Returns the localized phrase identified by the specified key. The +placeholders in the localization phrase will be replaced by the provided +values.

+
+
link(component, name, [params]) ⇒ string
+

Generates an absolute URL using the provided route name (see the +app/config/routes.js file). The provided parameters will +replace the placeholders in the route pattern, while the extraneous +parameters will be appended to the generated URL's query string.

+
+
cssClasses(component, classRules, includeComponentClassName) ⇒ string
+

Generate a string of CSS classes from the properties of the passed-in +object that resolve to true.

+
+
defaultCssClasses(classRules, component) ⇒ string
+

Generate a string of CSS classes from the properties of the passed-in +object that resolve to true.

+
+
fire(component, eventName, [data])
+

Creates and sends a new IMA.js DOM custom event from the provided component.

+
+
listen(component, eventTarget, eventName, listener)
+

Registers the provided event listener for execution whenever an IMA.js +DOM custom event of the specified name occurs at the specified event +target.

+
+
unlisten(component, eventTarget, eventName, listener)
+

Deregisters the provided event listener for an IMA.js DOM custom event +of the specified name at the specified event target.

+
+
+ +## getContextTypes(classConstructor) ⇒ Object.<string, function(...\*): boolean>  +Retrieves the context type declarations for the specified component. + +**Kind**: global function +**Returns**: Object.<string, function(...\*): boolean> - The context type + declarations associated with the specified component. + +| Param | Type | Description | +| --- | --- | --- | +| classConstructor | function | The constructor of the react component. | + + +* * * + +## setContextTypes(classConstructor, contextTypes) ⇒ Object.<string, function(...\*): boolean>  +Overrides the previously associated context type declarations for the +specified component to the provided ones. + +**Kind**: global function +**Returns**: Object.<string, function(...\*): boolean> - The provided context type + declarations. + +| Param | Type | Description | +| --- | --- | --- | +| classConstructor | function | The constructor of the react component. | +| contextTypes | Object.<string, function(...\*): boolean> | The new context type declarations to associate with the specified component. | + + +* * * + +## getUtils(props, context) ⇒ Object.<string, \*>  +Retrieves the view utilities from the component's current context or +properties (preferring the context). + +**Kind**: global function +**Returns**: Object.<string, \*> - The retrieved view utilities. +**Throws**: + +- Error Throw if the view utils cannot be located in the provided + properties nor context. + + +| Param | Type | Description | +| --- | --- | --- | +| props | Object.<string, \*> | The component's current properties. | +| context | Object.<string, \*> | The component's current context. | + + +* * * + +## localize(component, key, [params]) ⇒ string  +Returns the localized phrase identified by the specified key. The +placeholders in the localization phrase will be replaced by the provided +values. + +**Kind**: global function +**Returns**: string - Localized phrase. + +| Param | Type | Description | +| --- | --- | --- | +| component | AbstractComponent \| AbstractPureComponent | The component requiring the localization. | +| key | string | Localization key. | +| [params] | Object.<string, (number\|string)> | Values for replacing the placeholders in the localization phrase. | + + +* * * + +## link(component, name, [params]) ⇒ string  +Generates an absolute URL using the provided route name (see the +app/config/routes.js file). The provided parameters will +replace the placeholders in the route pattern, while the extraneous +parameters will be appended to the generated URL's query string. + +**Kind**: global function +**Returns**: string - The generated URL. + +| Param | Type | Description | +| --- | --- | --- | +| component | AbstractComponent \| AbstractPureComponent | The component requiring the generating of the URL. | +| name | string | The route name. | +| [params] | Object.<string, (number\|string)> | Router parameters and extraneous parameters to add to the URL as a query string. | + + +* * * + +## cssClasses(component, classRules, includeComponentClassName) ⇒ string  +Generate a string of CSS classes from the properties of the passed-in +object that resolve to true. + +**Kind**: global function +**Returns**: string - String of CSS classes that had their property resolved + to true. + +| Param | Type | Description | +| --- | --- | --- | +| component | AbstractComponent \| AbstractPureComponent | The component requiring the composition of the CSS class names. | +| classRules | string \| Object.<string, boolean> | CSS classes in a string separated by whitespace, or a map of CSS class names to boolean values. The CSS class name will be included in the result only if the value is true. | +| includeComponentClassName | boolean | | + +**Example** +```js +this.cssClasses('my-class my-class-modificator', true); +``` +**Example** +```js +this.cssClasses({ + 'my-class': true, + 'my-class-modificator': this.props.modificator + }, true); +``` + +* * * + +## defaultCssClasses(classRules, component) ⇒ string  +Generate a string of CSS classes from the properties of the passed-in +object that resolve to true. + +**Kind**: global function +**Returns**: string - String of CSS classes that had their property resolved + to true. + +| Param | Type | Description | +| --- | --- | --- | +| classRules | string \| Object.<string, boolean> | CSS classes in a string separated by whitespace, or a map of CSS class names to boolean values. The CSS class name will be included in the result only if the value is true. | +| component | AbstractComponent \| AbstractPureComponent \| string | The component requiring the composition of the CSS class names, if it has the className property set and requires its inclusion this time. | + + +* * * + +## fire(component, eventName, [data])  +Creates and sends a new IMA.js DOM custom event from the provided component. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| component | AbstractComponent \| AbstractPureComponent | The component at which's root element the event will originate. | +| eventName | string | The name of the event. | +| [data] | \* | Data to send within the event. | + + +* * * + +## listen(component, eventTarget, eventName, listener)  +Registers the provided event listener for execution whenever an IMA.js +DOM custom event of the specified name occurs at the specified event +target. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| component | AbstractComponent \| AbstractPureComponent | The component requesting the registration of the event listener. | +| eventTarget | React.Element \| EventTarget | The react component or event target at which the listener should listen for the event. | +| eventName | string | The name of the event for which to listen. | +| listener | function | The listener for event to register. | + + +* * * + +## unlisten(component, eventTarget, eventName, listener)  +Deregisters the provided event listener for an IMA.js DOM custom event +of the specified name at the specified event target. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| component | AbstractComponent \| AbstractPureComponent | The component that requested the registration of the event listener. | +| eventTarget | React.Element \| EventTarget | The react component or event target at which the listener should listen for the event. | +| eventName | string | The name of the event for which to listen. | +| listener | function | The listener for event to register. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagecontext.md b/docs/_posts/2018-08-31-pagecontext.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-pagecontext.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-pagehandler-page-handler-registry.md b/docs/_posts/2018-08-31-pagehandler-page-handler-registry.md new file mode 100644 index 00000000..ec380ec4 --- /dev/null +++ b/docs/_posts/2018-08-31-pagehandler-page-handler-registry.md @@ -0,0 +1,3 @@ +--- +--- + diff --git a/docs/_posts/2018-08-31-pagehandler-page-handler.md b/docs/_posts/2018-08-31-pagehandler-page-handler.md new file mode 100644 index 00000000..e7bdc491 --- /dev/null +++ b/docs/_posts/2018-08-31-pagehandler-page-handler.md @@ -0,0 +1,45 @@ +--- +category: "page/handler" +title: "PageHandler" +--- + +## PageHandler  +**Kind**: global class + +* [PageHandler](#PageHandler) + * [.handlePreManagedState(nextManagedPage, managedPage, [action])](#PageHandler+handlePreManagedState) + * [.handlePostManagedState(previousManagedPage, managedPage, [action])](#PageHandler+handlePostManagedState) + + +* * * + +### pageHandler.handlePreManagedState(nextManagedPage, managedPage, [action])  +Called before a PageManager starts to transition from previous page to +a new one. + +**Kind**: instance method of [PageHandler](#PageHandler) + +| Param | Type | Description | +| --- | --- | --- | +| nextManagedPage | ManagedPage | The data of the page that's about to be managed. | +| managedPage | ManagedPage | The currently managed page - soon-to-be previously managed page. | +| [action] | Object | An action object describing what triggered the routing. | + + +* * * + +### pageHandler.handlePostManagedState(previousManagedPage, managedPage, [action])  +Called after a PageManager finishes transition from previous page to +a new one. + +**Kind**: instance method of [PageHandler](#PageHandler) + +| Param | Type | Description | +| --- | --- | --- | +| previousManagedPage | ManagedPage | The data of the page that was previously managed. | +| managedPage | ManagedPage | The currently managed page. | +| [action] | Object | An action object describing what triggered the routing. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagehandler-page-navigation-handler.md b/docs/_posts/2018-08-31-pagehandler-page-navigation-handler.md new file mode 100644 index 00000000..176ad3ce --- /dev/null +++ b/docs/_posts/2018-08-31-pagehandler-page-navigation-handler.md @@ -0,0 +1,88 @@ +--- +category: "page/handler" +title: "PageNavigationHandler" +--- + +## PageNavigationHandler  +**Kind**: global class + +* [PageNavigationHandler](#PageNavigationHandler) + * [new PageNavigationHandler(window)](#new_PageNavigationHandler_new) + * [._window](#PageNavigationHandler+_window) : ima.window.Window + * [.handlePreManagedState()](#PageNavigationHandler+handlePreManagedState) + * [.handlePostManagedState()](#PageNavigationHandler+handlePostManagedState) + * [._saveScrollHistory()](#PageNavigationHandler+_saveScrollHistory) + * [._scrollTo(scroll)](#PageNavigationHandler+_scrollTo) + * [._setAddressBar(url)](#PageNavigationHandler+_setAddressBar) + + +* * * + +### new PageNavigationHandler(window)  + +| Param | Type | Description | +| --- | --- | --- | +| window | Window | The utility for manipulating the global context and global client-side-specific APIs. | + + +* * * + +### pageNavigationHandler._window : ima.window.Window  +The utility for manipulating the global context and global +client-side-specific APIs. + +**Kind**: instance property of [PageNavigationHandler](#PageNavigationHandler) + +* * * + +### pageNavigationHandler.handlePreManagedState()  +**Kind**: instance method of [PageNavigationHandler](#PageNavigationHandler) + +* * * + +### pageNavigationHandler.handlePostManagedState()  +**Kind**: instance method of [PageNavigationHandler](#PageNavigationHandler) + +* * * + +### pageNavigationHandler._saveScrollHistory()  +Save user's scroll state to history. + +Replace scroll values in current state for actual scroll values in +document. + +**Kind**: instance method of [PageNavigationHandler](#PageNavigationHandler) + +* * * + +### pageNavigationHandler._scrollTo(scroll)  +Scrolls to give coordinates on a page. + +**Kind**: instance method of [PageNavigationHandler](#PageNavigationHandler) + +| Param | Type | +| --- | --- | +| scroll | Object | +| [scroll.x] | number | +| [scroll.y] | number | + + +* * * + +### pageNavigationHandler._setAddressBar(url)  +Sets the provided URL to the browser's address bar by pushing a new +state to the history. + +The state object pushed to the history will be an object with the +following structure: {url: string}. The url field will +be set to the provided URL. + +**Kind**: instance method of [PageNavigationHandler](#PageNavigationHandler) + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagemanager-abstract-page-manager.md b/docs/_posts/2018-08-31-pagemanager-abstract-page-manager.md new file mode 100644 index 00000000..c0095dbd --- /dev/null +++ b/docs/_posts/2018-08-31-pagemanager-abstract-page-manager.md @@ -0,0 +1,463 @@ +--- +category: "page/manager" +title: "AbstractPageManager" +--- + +## Classes + +
+
AbstractPageManager
+

Page manager for controller.

+
+
+ +## Typedefs + +
+
RouteOptions : Object
+

An Object used to configure a route

+
+
ManagedPage : Object
+

An object representing a page that's currently managed by PageManager

+
+
+ +## AbstractPageManager  +Page manager for controller. + +**Kind**: global class + +* [AbstractPageManager](#AbstractPageManager) + * [new AbstractPageManager(pageFactory, pageRenderer, pageStateManager, pageHandlerRegistry)](#new_AbstractPageManager_new) + * [._pageFactory](#AbstractPageManager+_pageFactory) : PageFactory + * [._pageRenderer](#AbstractPageManager+_pageRenderer) : PageRenderer + * [._pageStateManager](#AbstractPageManager+_pageStateManager) : PageStateManager + * [._pageHandlerRegistry](#AbstractPageManager+_pageHandlerRegistry) : PageHandlerRegistry + * [._managedPage](#AbstractPageManager+_managedPage) : [ManagedPage](#ManagedPage) + * [._previousManagedPage](#AbstractPageManager+_previousManagedPage) : [ManagedPage](#ManagedPage) + * [.init()](#AbstractPageManager+init) + * [.manage()](#AbstractPageManager+manage) + * [.destroy()](#AbstractPageManager+destroy) + * [._constructManagedPageValue(controller, view, options, params, controllerInstance, decoratedController, viewInstance)](#AbstractPageManager+_constructManagedPageValue) ⇒ [ManagedPage](#ManagedPage) + * [._storeManagedPageSnapshot()](#AbstractPageManager+_storeManagedPageSnapshot) ⇒ [ManagedPage](#ManagedPage) + * [._clearManagedPageValue()](#AbstractPageManager+_clearManagedPageValue) + * [._stripManagedPageValueForPublic(value)](#AbstractPageManager+_stripManagedPageValueForPublic) ⇒ Object + * [._setRestrictedPageStateManager(extension, extensionState)](#AbstractPageManager+_setRestrictedPageStateManager) + * [._initPageSource()](#AbstractPageManager+_initPageSource) + * [._initController()](#AbstractPageManager+_initController) + * [._initExtensions()](#AbstractPageManager+_initExtensions) + * [._clearPartialState()](#AbstractPageManager+_clearPartialState) + * [._loadPageSource()](#AbstractPageManager+_loadPageSource) ⇒ Object.<string, (Promise.<\*>\|\*)> + * [._getLoadedControllerState()](#AbstractPageManager+_getLoadedControllerState) ⇒ Object.<string, (Promise.<\*>\|\*)> + * [._getLoadedExtensionsState(controllerState)](#AbstractPageManager+_getLoadedExtensionsState) ⇒ Object.<string, (Promise.<\*>\|\*)> + * [._activatePageSource()](#AbstractPageManager+_activatePageSource) + * [._activateController()](#AbstractPageManager+_activateController) + * [._activateExtensions()](#AbstractPageManager+_activateExtensions) + * [._updatePageSource()](#AbstractPageManager+_updatePageSource) ⇒ Promise.<{status: number, content: ?string}> + * [._getUpdatedControllerState()](#AbstractPageManager+_getUpdatedControllerState) ⇒ Object.<string, (Promise.<\*>\|\*)> + * [._getUpdatedExtensionsState(controllerState)](#AbstractPageManager+_getUpdatedExtensionsState) ⇒ Object.<string, (Promise\|\*)> + * [._deactivatePageSource()](#AbstractPageManager+_deactivatePageSource) + * [._deactivateController()](#AbstractPageManager+_deactivateController) + * [._deactivateExtensions()](#AbstractPageManager+_deactivateExtensions) + * [._destroyPageSource()](#AbstractPageManager+_destroyPageSource) + * [._destroyController()](#AbstractPageManager+_destroyController) + * [._destroyExtensions()](#AbstractPageManager+_destroyExtensions) + * [._clearComponentState(options)](#AbstractPageManager+_clearComponentState) + * [._onChangeStateHandler(state)](#AbstractPageManager+_onChangeStateHandler) + * [._hasOnlyUpdate(controller, view, options)](#AbstractPageManager+_hasOnlyUpdate) ⇒ boolean + * [._runPreManageHandlers(nextManagedPage, action)](#AbstractPageManager+_runPreManageHandlers) ⇒ Promise.<any> + * [._runPostManageHandlers(previousManagedPage)](#AbstractPageManager+_runPostManageHandlers) + + +* * * + +### new AbstractPageManager(pageFactory, pageRenderer, pageStateManager, pageHandlerRegistry)  +Initializes the page manager. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| pageFactory | PageFactory | | Factory used by the page manager to create instances of the controller for the current route, and decorate the controllers and page state managers. | +| pageRenderer | PageRenderer | | The current renderer of the page. | +| pageStateManager | PageStateManager | | The current page state manager. | +| pageHandlerRegistry | HandlerRegistry | | Instance of HandlerRegistry that holds a list of pre-manage and post-manage handlers. | + + +* * * + +### abstractPageManager._pageFactory : PageFactory  +Factory used by the page manager to create instances of the +controller for the current route, and decorate the controllers and +page state managers. + +**Kind**: instance property of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._pageRenderer : PageRenderer  +The current renderer of the page. + +**Kind**: instance property of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._pageStateManager : PageStateManager  +The current page state manager. + +**Kind**: instance property of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._pageHandlerRegistry : PageHandlerRegistry  +A registry that holds a list of pre-manage and post-manage handlers. + +**Kind**: instance property of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._managedPage : [ManagedPage](#ManagedPage)  +Details of the currently managed page. + +**Kind**: instance property of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._previousManagedPage : [ManagedPage](#ManagedPage)  +Snapshot of the previously managed page before it was replaced with +a new one + +**Kind**: instance property of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager.init()  +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) + +* * * + +### abstractPageManager.manage()  +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) + +* * * + +### abstractPageManager.destroy()  +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) + +* * * + +### abstractPageManager._constructManagedPageValue(controller, view, options, params, controllerInstance, decoratedController, viewInstance) ⇒ [ManagedPage](#ManagedPage)  +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | Description | +| --- | --- | --- | +| controller | string \| function | | +| view | string \| function | | +| options | [RouteOptions](#RouteOptions) | | +| params | Object.<string, string> | The route parameters. | +| controllerInstance | AbstractController | | +| decoratedController | ControllerDecorator | | +| viewInstance | React.Component | | + + +* * * + +### abstractPageManager._storeManagedPageSnapshot() ⇒ [ManagedPage](#ManagedPage)  +Creates a cloned version of currently managed page and stores it in +a helper property. +Snapshot is used in manager handlers to easily determine differences +between the current and the previous state. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._clearManagedPageValue()  +Clear value from managed page. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._stripManagedPageValueForPublic(value) ⇒ Object  +Removes properties we do not want to propagate outside of the page manager + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | Description | +| --- | --- | --- | +| value | [ManagedPage](#ManagedPage) | The managed page object to strip down | + + +* * * + +### abstractPageManager._setRestrictedPageStateManager(extension, extensionState)  +Set page state manager to extension which has restricted rights to set +global state. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) + +| Param | Type | +| --- | --- | +| extension | ima.extension.Extension | +| extensionState | Object.<string, \*> | + + +* * * + +### abstractPageManager._initPageSource()  +Initialize page source so call init method on controller and his +extensions. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._initController()  +Initializes managed instance of controller with the provided parameters. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._initExtensions()  +Initialize extensions for managed instance of controller with the +provided parameters. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._clearPartialState()  +Clears partialState of extensions for managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._loadPageSource() ⇒ Object.<string, (Promise.<\*>\|\*)>  +Load page source so call load method on controller and his extensions. +Merge loaded state and render it. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._getLoadedControllerState() ⇒ Object.<string, (Promise.<\*>\|\*)>  +Load controller state from managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._getLoadedExtensionsState(controllerState) ⇒ Object.<string, (Promise.<\*>\|\*)>  +Load extensions state from managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | +| --- | --- | +| controllerState | Object.<string, \*> | + + +* * * + +### abstractPageManager._activatePageSource()  +Activate page source so call activate method on controller and his +extensions. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._activateController()  +Activate managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._activateExtensions()  +Activate extensions for managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._updatePageSource() ⇒ Promise.<{status: number, content: ?string}>  +Update page source so call update method on controller and his +extensions. Merge updated state and render it. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._getUpdatedControllerState() ⇒ Object.<string, (Promise.<\*>\|\*)>  +Return updated controller state for current page controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._getUpdatedExtensionsState(controllerState) ⇒ Object.<string, (Promise\|\*)>  +Return updated extensions state for current page controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | +| --- | --- | +| controllerState | Object.<string, \*> | + + +* * * + +### abstractPageManager._deactivatePageSource()  +Deactivate page source so call deactivate method on controller and his +extensions. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._deactivateController()  +Deactivate last managed instance of controller only If controller was +activated. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._deactivateExtensions()  +Deactivate extensions for last managed instance of controller only if +they were activated. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._destroyPageSource()  +Destroy page source so call destroy method on controller and his +extensions. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._destroyController()  +Destroy last managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._destroyExtensions()  +Destroy extensions for last managed instance of controller. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +* * * + +### abstractPageManager._clearComponentState(options)  +The method clear state on current renderred component to DOM. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) + +| Param | Type | Description | +| --- | --- | --- | +| options | [RouteOptions](#RouteOptions) | The current route options. | + + +* * * + +### abstractPageManager._onChangeStateHandler(state)  +On change event handler set state to view. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) + +| Param | Type | +| --- | --- | +| state | Object.<string, \*> | + + +* * * + +### abstractPageManager._hasOnlyUpdate(controller, view, options) ⇒ boolean  +Return true if manager has to update last managed controller and view. + +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | +| --- | --- | +| controller | string \| function | +| view | string \| function | +| options | [RouteOptions](#RouteOptions) | + + +* * * + +### abstractPageManager._runPreManageHandlers(nextManagedPage, action) ⇒ Promise.<any>  +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | +| --- | --- | +| nextManagedPage | [ManagedPage](#ManagedPage) | +| action | Object | + + +* * * + +### abstractPageManager._runPostManageHandlers(previousManagedPage)  +**Kind**: instance method of [AbstractPageManager](#AbstractPageManager) +**Access**: protected + +| Param | Type | +| --- | --- | +| previousManagedPage | [ManagedPage](#ManagedPage) | + + +* * * + +## RouteOptions : Object  +An Object used to configure a route + +**Kind**: global typedef + +* * * + +## ManagedPage : Object  +An object representing a page that's currently managed by PageManager + +**Kind**: global typedef + +* * * + diff --git a/docs/_posts/2018-08-31-pagemanager-client-page-manager.md b/docs/_posts/2018-08-31-pagemanager-client-page-manager.md new file mode 100644 index 00000000..5880d14c --- /dev/null +++ b/docs/_posts/2018-08-31-pagemanager-client-page-manager.md @@ -0,0 +1,156 @@ +--- +category: "page/manager" +title: "ClientPageManager" +--- + +## ClientPageManager  +Page manager for controller on the client side. + +**Kind**: global class + +* [ClientPageManager](#ClientPageManager) + * [new ClientPageManager(pageFactory, pageRenderer, stateManager, handlerRegistry, window, eventBus)](#new_ClientPageManager_new) + * [._window](#ClientPageManager+_window) : ima.window.Window + * [._eventBus](#ClientPageManager+_eventBus) : ima.event.EventBus + * [._boundOnCustomEventHandler()](#ClientPageManager+_boundOnCustomEventHandler) : function + * [.init()](#ClientPageManager+init) + * [.manage()](#ClientPageManager+manage) + * [.destroy()](#ClientPageManager+destroy) + * [._onCustomEventHandler(event)](#ClientPageManager+_onCustomEventHandler) + * [._parseCustomEvent(event)](#ClientPageManager+_parseCustomEvent) ⇒ Object + * [._handleEventWithController(method, data)](#ClientPageManager+_handleEventWithController) ⇒ boolean + * [._handleEventWithExtensions(method, data)](#ClientPageManager+_handleEventWithExtensions) ⇒ boolean + + +* * * + +### new ClientPageManager(pageFactory, pageRenderer, stateManager, handlerRegistry, window, eventBus)  +Initializes the client-side page manager. + + +| Param | Type | Description | +| --- | --- | --- | +| pageFactory | PageFactory | Factory used by the page manager to create instances of the controller for the current route, and decorate the controllers and page state managers. | +| pageRenderer | PageRenderer | The current renderer of the page. | +| stateManager | PageStateManager | The current page state manager. | +| handlerRegistry | HandlerRegistry | Instance of HandlerRegistry that holds a list of pre-manage and post-manage handlers. | +| window | Window | The utility for manipulating the global context and global client-side-specific APIs. | +| eventBus | EventBus | The event bus for dispatching and listening for custom IMA events propagated through the DOM. | + + +* * * + +### clientPageManager._window : ima.window.Window  +The utility for manipulating the global context and global +client-side-specific APIs. + +**Kind**: instance property of [ClientPageManager](#ClientPageManager) + +* * * + +### clientPageManager._eventBus : ima.event.EventBus  +The event bus for dispatching and listening for custom IMA events +propagated through the DOM. + +**Kind**: instance property of [ClientPageManager](#ClientPageManager) + +* * * + +### clientPageManager._boundOnCustomEventHandler() : function  +Event listener for the custom DOM events used by the event bus, +bound to this instance. + +**Kind**: instance method of [ClientPageManager](#ClientPageManager) + +* * * + +### clientPageManager.init()  +**Kind**: instance method of [ClientPageManager](#ClientPageManager) + +* * * + +### clientPageManager.manage()  +**Kind**: instance method of [ClientPageManager](#ClientPageManager) + +* * * + +### clientPageManager.destroy()  +**Kind**: instance method of [ClientPageManager](#ClientPageManager) + +* * * + +### clientPageManager._onCustomEventHandler(event)  +Custom DOM event handler. + +The handler invokes the event listener in the active controller, if such +listener is present. The name of the controller's listener method is +created by turning the first symbol of the event's name to upper case, +and then prefixing the result with the 'on' prefix. + +For example: for an event named 'toggle' the controller's listener +would be named 'onToggle'. + +The controller's listener will be invoked with the event's data as an +argument. + +**Kind**: instance method of [ClientPageManager](#ClientPageManager) + +| Param | Type | Description | +| --- | --- | --- | +| event | CustomEvent | The encountered event bus DOM event. | + + +* * * + +### clientPageManager._parseCustomEvent(event) ⇒ Object  +Extracts the details of the provided event bus custom DOM event, along +with the expected name of the current controller's method for +intercepting the event. + +**Kind**: instance method of [ClientPageManager](#ClientPageManager) +**Returns**: Object - The event's + details. + +| Param | Type | Description | +| --- | --- | --- | +| event | CustomEvent | The encountered event bus custom DOM event. | + + +* * * + +### clientPageManager._handleEventWithController(method, data) ⇒ boolean  +Attempts to handle the currently processed event bus custom DOM event +using the current controller. The method returns true if the +event is handled by the controller. + +**Kind**: instance method of [ClientPageManager](#ClientPageManager) +**Returns**: boolean - true if the event has been handled by the + controller, false if the controller does not have a + method for processing the event. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The name of the method the current controller should use to process the currently processed event bus custom DOM event. | +| data | Object.<string, \*> | The custom event's data. | + + +* * * + +### clientPageManager._handleEventWithExtensions(method, data) ⇒ boolean  +Attempts to handle the currently processed event bus custom DOM event +using the registered extensions of the current controller. The method +returns true if the event is handled by the controller. + +**Kind**: instance method of [ClientPageManager](#ClientPageManager) +**Returns**: boolean - true if the event has been handled by one of + the controller's extensions, false if none of the + controller's extensions has a method for processing the event. + +| Param | Type | Description | +| --- | --- | --- | +| method | string | The name of the method the current controller should use to process the currently processed event bus custom DOM event. | +| data | Object.<string, \*> | The custom event's data. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagemanager-page-manager.md b/docs/_posts/2018-08-31-pagemanager-page-manager.md new file mode 100644 index 00000000..6f3379c1 --- /dev/null +++ b/docs/_posts/2018-08-31-pagemanager-page-manager.md @@ -0,0 +1,61 @@ +--- +category: "page/manager" +title: "PageManager" +--- + +## PageManager  +The page manager is a utility for managing the current controller and its +view. + +**Kind**: global class + +* [PageManager](#PageManager) + * [.init()](#PageManager+init) + * [.manage(controller, view, options, [params], [action])](#PageManager+manage) ⇒ Promise.<{status: number, content: ?string, pageState: Object.<string, \*>}> + * [.destroy()](#PageManager+destroy) + + +* * * + +### pageManager.init()  +Initializes the page manager. + +**Kind**: instance method of [PageManager](#PageManager) + +* * * + +### pageManager.manage(controller, view, options, [params], [action]) ⇒ Promise.<{status: number, content: ?string, pageState: Object.<string, \*>}>  +Starts to manage the provided controller and its view. The manager +stops the management of any previously managed controller and view. + +The controller and view will be initialized and rendered either into the +UI (at the client-side) or to the response to send to the client (at the +server-side). + +**Kind**: instance method of [PageManager](#PageManager) +**Returns**: Promise.<{status: number, content: ?string, pageState: Object.<string, \*>}> - A promise that will resolve to information about the rendered page. + The status will contain the HTTP status code to send to the + client (at the server side) or determine the type of error page + to navigate to (at the client side). + The content field will contain the rendered markup of + the page at the server-side, or null at the client-side. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| controller | string \| function | | The alias, namespace path, or constructor of the controller to manage. | +| view | string \| function | | The alias, namespace path, or constructor of the page view to manage. | +| options | Object | | The current route options. | +| [params] | Object.<string, string> | {} | The route parameters of the current route. | +| [action] | Object | | An action object describing what triggered the routing. | + + +* * * + +### pageManager.destroy()  +Finalization callback, called when the page manager is being discarded. +This usually happens when the page is hot-reloaded at the client side. + +**Kind**: instance method of [PageManager](#PageManager) + +* * * + diff --git a/docs/_posts/2018-08-31-pagemanager-server-page-manager.md b/docs/_posts/2018-08-31-pagemanager-server-page-manager.md new file mode 100644 index 00000000..ebb290fa --- /dev/null +++ b/docs/_posts/2018-08-31-pagemanager-server-page-manager.md @@ -0,0 +1,12 @@ +--- +category: "page/manager" +title: "ServerPageManager" +--- + +## ServerPageManager  +Page manager for controller on the server side. + +**Kind**: global class + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-abstract-page-renderer.md b/docs/_posts/2018-08-31-pagerenderer-abstract-page-renderer.md new file mode 100644 index 00000000..2a3e3433 --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-abstract-page-renderer.md @@ -0,0 +1,148 @@ +--- +category: "page/renderer" +title: "AbstractPageRenderer" +--- + +## AbstractPageRenderer  +Base class for implementations of the {@linkcode PageRenderer} interface. + +**Kind**: global class + +* [AbstractPageRenderer](#AbstractPageRenderer) + * [new AbstractPageRenderer(factory, Helper, ReactDOM, settings)](#new_AbstractPageRenderer_new) + * [._factory](#AbstractPageRenderer+_factory) : PageRendererFactory + * [._Helper](#AbstractPageRenderer+_Helper) : Vendor.$Helper + * [._ReactDOM](#AbstractPageRenderer+_ReactDOM) : Vendor.ReactDOM + * [._settings](#AbstractPageRenderer+_settings) : Object.<string, \*> + * [._reactiveView](#AbstractPageRenderer+_reactiveView) : React.Component + * *[.mount()](#AbstractPageRenderer+mount)* + * [.update()](#AbstractPageRenderer+update) + * [.unmount()](#AbstractPageRenderer+unmount) + * [.clearState()](#AbstractPageRenderer+clearState) + * [.setState()](#AbstractPageRenderer+setState) + * [._generateViewProps(view, [state])](#AbstractPageRenderer+_generateViewProps) ⇒ Object.<string, \*> + * [._getWrappedPageView(controller, view, routeOptions)](#AbstractPageRenderer+_getWrappedPageView) + * [._getDocumentView(documentView)](#AbstractPageRenderer+_getDocumentView) ⇒ function + + +* * * + +### new AbstractPageRenderer(factory, Helper, ReactDOM, settings)  +Initializes the abstract page renderer. + + +| Param | Type | Description | +| --- | --- | --- | +| factory | PageRendererFactory | Factory for receive $Utils to view. | +| Helper | vendor.$Helper | The IMA.js helper methods. | +| ReactDOM | vendor.ReactDOM | React framework instance, will be used to render the page. | +| settings | Object.<string, \*> | Application settings for the current application environment. | + + +* * * + +### abstractPageRenderer._factory : PageRendererFactory  +Factory for receive $Utils to view. + +**Kind**: instance property of [AbstractPageRenderer](#AbstractPageRenderer) +**Access**: protected + +* * * + +### abstractPageRenderer._Helper : Vendor.$Helper  +The IMA.js helper methods. + +**Kind**: instance property of [AbstractPageRenderer](#AbstractPageRenderer) +**Access**: protected + +* * * + +### abstractPageRenderer._ReactDOM : Vendor.ReactDOM  +Rect framework instance, used to render the page. + +**Kind**: instance property of [AbstractPageRenderer](#AbstractPageRenderer) +**Access**: protected + +* * * + +### abstractPageRenderer._settings : Object.<string, \*>  +Application setting for the current application environment. + +**Kind**: instance property of [AbstractPageRenderer](#AbstractPageRenderer) +**Access**: protected + +* * * + +### abstractPageRenderer._reactiveView : React.Component  +**Kind**: instance property of [AbstractPageRenderer](#AbstractPageRenderer) +**Access**: protected + +* * * + +### *abstractPageRenderer.mount()*  +**Kind**: instance abstract method of [AbstractPageRenderer](#AbstractPageRenderer) + +* * * + +### abstractPageRenderer.update()  +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) + +* * * + +### abstractPageRenderer.unmount()  +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) + +* * * + +### abstractPageRenderer.clearState()  +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) + +* * * + +### abstractPageRenderer.setState()  +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) + +* * * + +### abstractPageRenderer._generateViewProps(view, [state]) ⇒ Object.<string, \*>  +Generate properties for view from state. + +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) +**Access**: protected + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| view | function | | The page view React component to wrap. | +| [state] | Object.<string, \*> | {} | | + + +* * * + +### abstractPageRenderer._getWrappedPageView(controller, view, routeOptions)  +Returns wrapped page view component with managed root view and view adapter. + +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) + +| Param | Type | Description | +| --- | --- | --- | +| controller | ControllerDecorator | | +| view | function | | +| routeOptions | Object | The current route options. | + + +* * * + +### abstractPageRenderer._getDocumentView(documentView) ⇒ function  +Returns the class constructor of the specified document view component. + +**Kind**: instance method of [AbstractPageRenderer](#AbstractPageRenderer) +**Returns**: function - The constructor of the document + view component. + +| Param | Type | Description | +| --- | --- | --- | +| documentView | function \| string | The namespace path pointing to the document view component, or the constructor of the document view component. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-blank-managed-root-view.md b/docs/_posts/2018-08-31-pagerenderer-blank-managed-root-view.md new file mode 100644 index 00000000..6659bd5c --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-blank-managed-root-view.md @@ -0,0 +1,20 @@ +--- +category: "page/renderer" +title: "BlankManagedRootView" +--- + +## BlankManagedRootView  +Blank managed root view does not nothing except for rendering the current +page view. + +This is the default managed root view. + +**Kind**: global class + +* * * + +### blankManagedRootView.render()  +**Kind**: instance method of [BlankManagedRootView](#BlankManagedRootView) + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-client-page-renderer.md b/docs/_posts/2018-08-31-pagerenderer-client-page-renderer.md new file mode 100644 index 00000000..741222e8 --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-client-page-renderer.md @@ -0,0 +1,191 @@ +--- +category: "page/renderer" +title: "ClientPageRenderer" +--- + +## ClientPageRenderer  +Client-side page renderer. The renderer attempts to reuse the markup sent by +server if possible. + +**Kind**: global class + +* [ClientPageRenderer](#ClientPageRenderer) + * [new ClientPageRenderer(factory, Helper, ReactDOM, settings, window)](#new_ClientPageRenderer_new) + * [._firstTime](#ClientPageRenderer+_firstTime) : boolean + * [._window](#ClientPageRenderer+_window) : Window + * [._viewContainer](#ClientPageRenderer+_viewContainer) : HTMLElement + * [.mount()](#ClientPageRenderer+mount) + * [.update()](#ClientPageRenderer+update) + * [.unmount()](#ClientPageRenderer+unmount) + * [._handleError(error)](#ClientPageRenderer+_handleError) + * [._patchPromisesToState(controller, patchedPromises)](#ClientPageRenderer+_patchPromisesToState) + * [._renderToDOM(controller, view, routeOptions)](#ClientPageRenderer+_renderToDOM) + * [._separatePromisesAndValues(dataMap)](#ClientPageRenderer+_separatePromisesAndValues) ⇒ Object + * [._updateMetaAttributes(metaManager)](#ClientPageRenderer+_updateMetaAttributes) + * [._updateMetaNameAttributes(metaManager)](#ClientPageRenderer+_updateMetaNameAttributes) + * [._updateMetaPropertyAttributes(metaManager)](#ClientPageRenderer+_updateMetaPropertyAttributes) + * [._updateMetaLinkAttributes(metaManager)](#ClientPageRenderer+_updateMetaLinkAttributes) + + +* * * + +### new ClientPageRenderer(factory, Helper, ReactDOM, settings, window)  +Initializes the client-side page renderer. + + +| Param | Type | Description | +| --- | --- | --- | +| factory | PageRendererFactory | Factory for receive $Utils to view. | +| Helper | vendor.$Helper | The IMA.js helper methods. | +| ReactDOM | vendor.ReactDOM | React framework instance to use to render the page on the client side. | +| settings | Object.<string, \*> | The application setting for the current application environment. | +| window | Window | Helper for manipulating the global object (window) regardless of the client/server-side environment. | + + +* * * + +### clientPageRenderer._firstTime : boolean  +Flag signalling that the page is being rendered for the first time. + +**Kind**: instance property of [ClientPageRenderer](#ClientPageRenderer) + +* * * + +### clientPageRenderer._window : Window  +Helper for manipulating the global object (window) +regardless of the client/server-side environment. + +**Kind**: instance property of [ClientPageRenderer](#ClientPageRenderer) + +* * * + +### clientPageRenderer._viewContainer : HTMLElement  +The HTML element containing the current application view for the +current route. + +**Kind**: instance property of [ClientPageRenderer](#ClientPageRenderer) + +* * * + +### clientPageRenderer.mount()  +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +* * * + +### clientPageRenderer.update()  +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +* * * + +### clientPageRenderer.unmount()  +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +* * * + +### clientPageRenderer._handleError(error)  +Show error to console in $Debug mode and re-throw that error +for other error handler. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) +**Throws**: + +- Error Re-throws the handled error. + + +| Param | Type | +| --- | --- | +| error | Error | + + +* * * + +### clientPageRenderer._patchPromisesToState(controller, patchedPromises)  +Patch promise values to controller state. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +| Param | Type | +| --- | --- | +| controller | ControllerDecorator | +| patchedPromises | Object.<string, Promise.<\*>> | + + +* * * + +### clientPageRenderer._renderToDOM(controller, view, routeOptions)  +Renders the current route to DOM. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +| Param | Type | Description | +| --- | --- | --- | +| controller | ControllerDecorator | | +| view | function | | +| routeOptions | Object | The current route options. | + + +* * * + +### clientPageRenderer._separatePromisesAndValues(dataMap) ⇒ Object  +Separate promises and values from provided data map. Values will be use +for default page state. Promises will be patched to state after their +resolve. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) +**Returns**: Object - Return separated promises and other values. + +| Param | Type | Description | +| --- | --- | --- | +| dataMap | Object.<string, \*> | A map of data. | + + +* * * + +### clientPageRenderer._updateMetaAttributes(metaManager)  +Updates the title and the contents of the meta elements used for SEO. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +| Param | Type | Description | +| --- | --- | --- | +| metaManager | MetaManager | meta attributes storage providing the new values for page meta elements and title. | + + +* * * + +### clientPageRenderer._updateMetaNameAttributes(metaManager)  +Updates the contents of the generic meta elements used for SEO. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +| Param | Type | Description | +| --- | --- | --- | +| metaManager | MetaManager | meta attributes storage providing the new values for page meta elements and title. | + + +* * * + +### clientPageRenderer._updateMetaPropertyAttributes(metaManager)  +Updates the contents of the specialized meta elements used for SEO. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +| Param | Type | Description | +| --- | --- | --- | +| metaManager | MetaManager | meta attributes storage providing the new values for page meta elements and title. | + + +* * * + +### clientPageRenderer._updateMetaLinkAttributes(metaManager)  +Updates the href of the specialized link elements used for SEO. + +**Kind**: instance method of [ClientPageRenderer](#ClientPageRenderer) + +| Param | Type | Description | +| --- | --- | --- | +| metaManager | MetaManager | meta attributes storage providing the new values for page meta elements and title. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-page-renderer-factory.md b/docs/_posts/2018-08-31-pagerenderer-page-renderer-factory.md new file mode 100644 index 00000000..9d476c7b --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-page-renderer-factory.md @@ -0,0 +1,141 @@ +--- +category: "page/renderer" +title: "PageRendererFactory" +--- + +## PageRendererFactory  +Factory for page render. + +**Kind**: global class + +* [PageRendererFactory](#PageRendererFactory) + * [new PageRendererFactory(oc, React)](#new_PageRendererFactory_new) + * [._oc](#PageRendererFactory+_oc) : ObjectContainer + * [._React](#PageRendererFactory+_React) : React + * [.getUtils()](#PageRendererFactory+getUtils) + * [.getDocumentView(documentView)](#PageRendererFactory+getDocumentView) ⇒ function + * [.getManagedRootView(managedRootView)](#PageRendererFactory+getManagedRootView) ⇒ function + * [._resolveClassConstructor(view)](#PageRendererFactory+_resolveClassConstructor) ⇒ function + * [.wrapView(view, props)](#PageRendererFactory+wrapView) ⇒ React.Element + * [.createReactElementFactory(view)](#PageRendererFactory+createReactElementFactory) ⇒ function + + +* * * + +### new PageRendererFactory(oc, React)  +Initializes the factory used by the page renderer. + + +| Param | Type | Description | +| --- | --- | --- | +| oc | ObjectContainer | The application's dependency injector - the object container. | +| React | React | The React framework instance to use to render the page. | + + +* * * + +### pageRendererFactory._oc : ObjectContainer  +The application's dependency injector - the object container. + +**Kind**: instance property of [PageRendererFactory](#PageRendererFactory) + +* * * + +### pageRendererFactory._React : React  +Rect framework instance, used to render the page. + +**Kind**: instance property of [PageRendererFactory](#PageRendererFactory) +**Access**: protected + +* * * + +### pageRendererFactory.getUtils()  +Return object of services which are defined for alias $Utils. + +**Kind**: instance method of [PageRendererFactory](#PageRendererFactory) + +* * * + +### pageRendererFactory.getDocumentView(documentView) ⇒ function  +Returns the class constructor of the specified document view component. +Document view may be specified as a namespace path or as a class +constructor. + +**Kind**: instance method of [PageRendererFactory](#PageRendererFactory) +**Returns**: function - The constructor of the document + view component. + +| Param | Type | Description | +| --- | --- | --- | +| documentView | function \| string | The namespace path pointing to the document view component, or the constructor of the document view component. | + + +* * * + +### pageRendererFactory.getManagedRootView(managedRootView) ⇒ function  +Returns the class constructor of the specified managed root view +component. Managed root view may be specified as a namespace +path or as a class constructor. + +**Kind**: instance method of [PageRendererFactory](#PageRendererFactory) +**Returns**: function - The constructor of the managed + root view component. + +| Param | Type | Description | +| --- | --- | --- | +| managedRootView | function \| string | The namespace path pointing to the managed root view component, or the constructor of the React component. | + + +* * * + +### pageRendererFactory._resolveClassConstructor(view) ⇒ function  +Returns the class constructor of the specified view component. +View may be specified as a namespace path or as a class +constructor. + +**Kind**: instance method of [PageRendererFactory](#PageRendererFactory) +**Returns**: function - The constructor of the view + component. + +| Param | Type | Description | +| --- | --- | --- | +| view | function | The namespace path pointing to the view component, or the constructor of the React.Component. | + + +* * * + +### pageRendererFactory.wrapView(view, props) ⇒ React.Element  +Wraps the provided view into the view adapter so it can access the state +passed from controller through the props property instead of the +state property. + +**Kind**: instance method of [PageRendererFactory](#PageRendererFactory) +**Returns**: React.Element - View adapter handling passing the controller's + state to an instance of the specified page view through + properties. + +| Param | Type | Description | +| --- | --- | --- | +| view | function \| string | The namespace path pointing to the view component, or the constructor of the React.Component. | +| props | Object | The initial props to pass to the view. | + + +* * * + +### pageRendererFactory.createReactElementFactory(view) ⇒ function  +Return a function that produces ReactElements of a given type. +Like React.createElement. + +**Kind**: instance method of [PageRendererFactory](#PageRendererFactory) +**Returns**: function - The created factory + function. The factory accepts an object containing the + component's properties as the argument and returns a rendered + component. + +| Param | Type | Description | +| --- | --- | --- | +| view | string \| function | The react component for which a factory function should be created. | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-page-renderer.md b/docs/_posts/2018-08-31-pagerenderer-page-renderer.md new file mode 100644 index 00000000..6913ec1a --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-page-renderer.md @@ -0,0 +1,115 @@ +--- +category: "page/renderer" +title: "PageRenderer" +--- + +## PageRenderer  +The page renderer is a utility for rendering the page at either the +client-side or the server-side, handling the differences in the environment. + +**Kind**: global class + +* [PageRenderer](#PageRenderer) + * [.mount(controller, view, pageResources, routeOptions)](#PageRenderer+mount) ⇒ Promise.<{status: number, content: ?string, pageState: Object.<string, ?>}> + * [.update(controller, resourcesUpdate)](#PageRenderer+update) ⇒ Promise.<{status: number, content: ?string, pageState: Object.<string, \*>}> + * [.unmount()](#PageRenderer+unmount) + * [.setState([state])](#PageRenderer+setState) + * [.clearState()](#PageRenderer+clearState) + + +* * * + +### pageRenderer.mount(controller, view, pageResources, routeOptions) ⇒ Promise.<{status: number, content: ?string, pageState: Object.<string, ?>}>  +Renders the page using the provided controller and view. The actual +behavior of this method differs at the client-side and the at +server-side in the following way: + +At the server, the method first waits for all the resources to load, and +then renders the page to a string containing HTML markup to send to the +client. + +At the client, the method uses the already available resources to render +the page into DOM, re-using the DOM created from the HTML markup send by +the server if possible. After this the method will re-render the page +every time another resource being loaded finishes its loading and +becomes available. + +Note that the method renders the page at the client-side only after all +resources have been loaded if this is the first time this method is +invoked at the client. + +**Kind**: instance method of [PageRenderer](#PageRenderer) +**Returns**: Promise.<{status: number, content: ?string, pageState: Object.<string, ?>}> - A promise that will resolve to information about the + rendered page. The status will contain the HTTP status + code to send to the client (at the server side) or determine the + type of error page to navigate to (at the client side). + The content field will contain the rendered markup of + the page at the server-side, or null at the client-side. + +| Param | Type | Description | +| --- | --- | --- | +| controller | Controller | The current page controller. | +| view | React.Component | The page's view. | +| pageResources | Object.<string, (\*\|Promise.<\*>)> | The resources for the view loaded by the controller. | +| routeOptions | Object | The current route options. | + + +* * * + +### pageRenderer.update(controller, resourcesUpdate) ⇒ Promise.<{status: number, content: ?string, pageState: Object.<string, \*>}>  +Handles update of the current route that does not replace the current +controller and view. + +The method will use the already available resource to update the +controller's state and the view immediately. After that, the method will +update the controller's state and view with every resource that becomes +resolved. + +**Kind**: instance method of [PageRenderer](#PageRenderer) +**Returns**: Promise.<{status: number, content: ?string, pageState: Object.<string, \*>}> - A promise that will resolve to information about the + rendered page. The status will contain the HTTP status + code to send to the client (at the server side) or determine the + type of error page to navigate to (at the client side). + The content field will contain the rendered markup of + the page at the server-side, or null at the client-side. + +| Param | Type | Description | +| --- | --- | --- | +| controller | Controller | The current page controller. | +| resourcesUpdate | Object.<string, (\*\|Promise.<\*>)> | The resources that represent the update the of current state according to the current route and its parameters. | + + +* * * + +### pageRenderer.unmount()  +Unmounts the view from the DOM. + +This method has no effect at the server-side. + +**Kind**: instance method of [PageRenderer](#PageRenderer) + +* * * + +### pageRenderer.setState([state])  +Sets the provided state to the currently rendered view. + +This method has no effect at the server-side. + +**Kind**: instance method of [PageRenderer](#PageRenderer) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [state] | Object.<string, \*> | {} | The state to set to the currently rendered view. | + + +* * * + +### pageRenderer.clearState()  +Clears the state to the currently rendered view. + +This method has no effect at the server-side. + +**Kind**: instance method of [PageRenderer](#PageRenderer) + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-server-page-renderer.md b/docs/_posts/2018-08-31-pagerenderer-server-page-renderer.md new file mode 100644 index 00000000..e8996e74 --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-server-page-renderer.md @@ -0,0 +1,150 @@ +--- +category: "page/renderer" +title: "ServerPageRenderer" +--- + +## ima ⇐ AbstractPageRenderer  +Server-side page renderer. The renderer renders the page into the HTML +markup and sends it to the client. + +**Extends**: AbstractPageRenderer +**Implements**: PageRenderer +**Submodule**: ima.page + +* [ima](#module_ima) ⇐ AbstractPageRenderer + * [~ServerPageRenderer](#module_ima..ServerPageRenderer) + * [new ServerPageRenderer(factory, Helper, ReactDOMServer, settings, response, cache)](#new_module_ima..ServerPageRenderer_new) + * [._response](#module_ima..ServerPageRenderer+_response) : Response + * [._cache](#module_ima..ServerPageRenderer+_cache) : Cache + * [._getRevivalSettings()](#module_ima..ServerPageRenderer+_getRevivalSettings) ⇒ string + * [._wrapEachKeyToPromise([dataMap])](#module_ima..ServerPageRenderer+_wrapEachKeyToPromise) ⇒ Object.<string, Promise> + * [._renderPage(controller, view, pageState, routeOptions)](#module_ima..ServerPageRenderer+_renderPage) ⇒ Object + * [._renderPageContentToString(controller, view, routeOptions)](#module_ima..ServerPageRenderer+_renderPageContentToString) ⇒ string + * *[~mount()](#module_ima..mount)* + * [~update()](#module_ima..update) + * [~unmount()](#module_ima..unmount) + + +* * * + +### ima~ServerPageRenderer  +**Kind**: inner class of [ima](#module_ima) + +* [~ServerPageRenderer](#module_ima..ServerPageRenderer) + * [new ServerPageRenderer(factory, Helper, ReactDOMServer, settings, response, cache)](#new_module_ima..ServerPageRenderer_new) + * [._response](#module_ima..ServerPageRenderer+_response) : Response + * [._cache](#module_ima..ServerPageRenderer+_cache) : Cache + * [._getRevivalSettings()](#module_ima..ServerPageRenderer+_getRevivalSettings) ⇒ string + * [._wrapEachKeyToPromise([dataMap])](#module_ima..ServerPageRenderer+_wrapEachKeyToPromise) ⇒ Object.<string, Promise> + * [._renderPage(controller, view, pageState, routeOptions)](#module_ima..ServerPageRenderer+_renderPage) ⇒ Object + * [._renderPageContentToString(controller, view, routeOptions)](#module_ima..ServerPageRenderer+_renderPageContentToString) ⇒ string + + +* * * + +#### new ServerPageRenderer(factory, Helper, ReactDOMServer, settings, response, cache)  +Initializes the server-side page renderer. + + +| Param | Type | Description | +| --- | --- | --- | +| factory | PageRendererFactory | Factory for receive $Utils to view. | +| Helper | vendor.$Helper | The IMA.js helper methods. | +| ReactDOMServer | vendor.ReactDOMServer | React framework instance to use to render the page on the server side. | +| settings | Object.<string, \*> | Application setting for the current application environment. | +| response | Response | Utility for sending the page markup to the client as a response to the current HTTP request. | +| cache | Cache | Resource cache caching the results of HTTP requests made by services used by the rendered page. | + + +* * * + +#### serverPageRenderer._response : Response  +Utility for sending the page markup to the client as a response to +the current HTTP request. + +**Kind**: instance property of [ServerPageRenderer](#module_ima..ServerPageRenderer) + +* * * + +#### serverPageRenderer._cache : Cache  +The resource cache, caching the results of all HTTP requests made by +the services using by the rendered page. The state of the cache will +then be serialized and sent to the client to re-initialize the page +at the client side. + +**Kind**: instance property of [ServerPageRenderer](#module_ima..ServerPageRenderer) + +* * * + +#### serverPageRenderer._getRevivalSettings() ⇒ string  +The javascript code will include a settings the "revival" data for the +application at the client-side. + +**Kind**: instance method of [ServerPageRenderer](#module_ima..ServerPageRenderer) +**Returns**: string - The javascript code to include into the + rendered page. + +* * * + +#### serverPageRenderer._wrapEachKeyToPromise([dataMap]) ⇒ Object.<string, Promise>  +Creates a copy of the provided data map object that has the values of +its fields wrapped into Promises. + +The the values that are already Promises will referenced directly +without wrapping then into another Promise. + +**Kind**: instance method of [ServerPageRenderer](#module_ima..ServerPageRenderer) +**Returns**: Object.<string, Promise> - A copy of the provided data map that + has all its values wrapped into promises. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [dataMap] | Object.<string, \*> | {} | A map of data that should have its values wrapped into Promises. | + + +* * * + +#### serverPageRenderer._renderPage(controller, view, pageState, routeOptions) ⇒ Object  +Render page after all promises from loaded resources is resolved. + +**Kind**: instance method of [ServerPageRenderer](#module_ima..ServerPageRenderer) + +| Param | Type | +| --- | --- | +| controller | AbstractController | +| view | React.Component | +| pageState | Object.<string, \*> | +| routeOptions | Object.<string, \*> | + + +* * * + +#### serverPageRenderer._renderPageContentToString(controller, view, routeOptions) ⇒ string  +Render page content to a string containing HTML markup. + +**Kind**: instance method of [ServerPageRenderer](#module_ima..ServerPageRenderer) + +| Param | Type | +| --- | --- | +| controller | AbstractController | +| view | function | +| routeOptions | Object.<string, \*> | + + +* * * + +### *ima~mount()*  +**Kind**: inner abstract method of [ima](#module_ima) + +* * * + +### ima~update()  +**Kind**: inner method of [ima](#module_ima) + +* * * + +### ima~unmount()  +**Kind**: inner method of [ima](#module_ima) + +* * * + diff --git a/docs/_posts/2018-08-31-pagerenderer-view-adapter.md b/docs/_posts/2018-08-31-pagerenderer-view-adapter.md new file mode 100644 index 00000000..7b36c87f --- /dev/null +++ b/docs/_posts/2018-08-31-pagerenderer-view-adapter.md @@ -0,0 +1,80 @@ +--- +category: "page/renderer" +title: "ViewAdapter" +--- + +## ViewAdapter  +An adapter component providing the current page controller's state to the +page view component through its properties. + +**Kind**: global class + +* [ViewAdapter](#ViewAdapter) + * [new ViewAdapter(props)](#new_ViewAdapter_new) + * _instance_ + * [.state](#ViewAdapter+state) : Object.<string, \*> + * [._view](#ViewAdapter+_view) : function + * [.componentWillReceiveProps()](#ViewAdapter+componentWillReceiveProps) + * [.componentDidCatch()](#ViewAdapter+componentDidCatch) + * [.render()](#ViewAdapter+render) + * [.getChildContext()](#ViewAdapter+getChildContext) + * _static_ + * [.childContextTypes](#ViewAdapter.childContextTypes) ⇒ Object + + +* * * + +### new ViewAdapter(props)  +Initializes the adapter component. + + +| Param | Type | Description | +| --- | --- | --- | +| props | Object | Component properties, containing the actual page view and the initial page state to pass to the view. | + + +* * * + +### viewAdapter.state : Object.<string, \*>  +The current page state as provided by the controller. + +**Kind**: instance property of [ViewAdapter](#ViewAdapter) + +* * * + +### viewAdapter._view : function  +The actual page view to render. + +**Kind**: instance property of [ViewAdapter](#ViewAdapter) + +* * * + +### viewAdapter.componentWillReceiveProps()  +**Kind**: instance method of [ViewAdapter](#ViewAdapter) + +* * * + +### viewAdapter.componentDidCatch()  +Fixes an issue where when there's an error in React component, +the defined ErrorPage may not get re-rendered and white +blank page appears instead. + +**Kind**: instance method of [ViewAdapter](#ViewAdapter) + +* * * + +### viewAdapter.render()  +**Kind**: instance method of [ViewAdapter](#ViewAdapter) + +* * * + +### viewAdapter.getChildContext()  +**Kind**: instance method of [ViewAdapter](#ViewAdapter) + +* * * + +### ViewAdapter.childContextTypes ⇒ Object  +**Kind**: static property of [ViewAdapter](#ViewAdapter) + +* * * + diff --git a/docs/_posts/2018-08-31-pagestate-events.md b/docs/_posts/2018-08-31-pagestate-events.md new file mode 100644 index 00000000..50e54d6d --- /dev/null +++ b/docs/_posts/2018-08-31-pagestate-events.md @@ -0,0 +1,45 @@ +--- +category: "page/state" +title: "Events" +--- + +## Constants + +
+
BEFORE_CHANGE_STATE : string
+

PateStateManager fire event $IMA.$Dispatcher.beforeChangeState before +state is patched. Event's data contain +{ oldState: Object<string, >, newState: Object<string, >, +pathState: Object<string, *> }.

+
+
AFTER_CHANGE_STATE : string
+

Router fire event $IMA.$Dispatcher.afterChangeState after state +is patched. Event's data contain {newState: Object<string, *>.

+
+
+ +## Events : enum  +Events constants, which is firing to app. + +**Kind**: global enum + +* * * + +## BEFORE_CHANGE_STATE : string  +PateStateManager fire event $IMA.$Dispatcher.beforeChangeState before +state is patched. Event's data contain +{ oldState: Object, newState: Object, +pathState: Object }. + +**Kind**: global constant + +* * * + +## AFTER_CHANGE_STATE : string  +Router fire event $IMA.$Dispatcher.afterChangeState after state +is patched. Event's data contain {newState: Object. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-pagestate-page-state-manager-decorator.md b/docs/_posts/2018-08-31-pagestate-page-state-manager-decorator.md new file mode 100644 index 00000000..d91a9208 --- /dev/null +++ b/docs/_posts/2018-08-31-pagestate-page-state-manager-decorator.md @@ -0,0 +1,69 @@ +--- +category: "page/state" +title: "PageStateManagerDecorator" +--- + +## PageStateManagerDecorator  +Decorator for page state manager, which add logic for limiting Extension +competence. + +**Kind**: global class + +* [PageStateManagerDecorator](#PageStateManagerDecorator) + * [new PageStateManagerDecorator(pageStateManager, allowedStateKeys)](#new_PageStateManagerDecorator_new) + * [._pageStateManager](#PageStateManagerDecorator+_pageStateManager) : PageStateManager + * [._allowedStateKeys](#PageStateManagerDecorator+_allowedStateKeys) : Array.<string> + * [.clear()](#PageStateManagerDecorator+clear) + * [.setState()](#PageStateManagerDecorator+setState) + * [.getState()](#PageStateManagerDecorator+getState) + * [.getAllStates()](#PageStateManagerDecorator+getAllStates) + + +* * * + +### new PageStateManagerDecorator(pageStateManager, allowedStateKeys)  +Initializes the page state manager decorator. + + +| Param | Type | +| --- | --- | +| pageStateManager | PageStateManager | +| allowedStateKeys | Array.<string> | + + +* * * + +### pageStateManagerDecorator._pageStateManager : PageStateManager  +The current page state manager. + +**Kind**: instance property of [PageStateManagerDecorator](#PageStateManagerDecorator) + +* * * + +### pageStateManagerDecorator._allowedStateKeys : Array.<string>  +Array of access keys for state. + +**Kind**: instance property of [PageStateManagerDecorator](#PageStateManagerDecorator) + +* * * + +### pageStateManagerDecorator.clear()  +**Kind**: instance method of [PageStateManagerDecorator](#PageStateManagerDecorator) + +* * * + +### pageStateManagerDecorator.setState()  +**Kind**: instance method of [PageStateManagerDecorator](#PageStateManagerDecorator) + +* * * + +### pageStateManagerDecorator.getState()  +**Kind**: instance method of [PageStateManagerDecorator](#PageStateManagerDecorator) + +* * * + +### pageStateManagerDecorator.getAllStates()  +**Kind**: instance method of [PageStateManagerDecorator](#PageStateManagerDecorator) + +* * * + diff --git a/docs/_posts/2018-08-31-pagestate-page-state-manager-impl.md b/docs/_posts/2018-08-31-pagestate-page-state-manager-impl.md new file mode 100644 index 00000000..551c62fd --- /dev/null +++ b/docs/_posts/2018-08-31-pagestate-page-state-manager-impl.md @@ -0,0 +1,110 @@ +--- +category: "page/state" +title: "PageStateManagerImpl" +--- + +## PageStateManagerImpl  +The implementation of the {@linkcode PageStateManager} interface. + +**Kind**: global class + +* [PageStateManagerImpl](#PageStateManagerImpl) + * [new PageStateManagerImpl(dispatcher)](#new_PageStateManagerImpl_new) + * [._states](#PageStateManagerImpl+_states) : Array.<Object.<string, \*>> + * [._cursor](#PageStateManagerImpl+_cursor) : number + * [.onChange](#PageStateManagerImpl+onChange) : function + * [._dispatcher](#PageStateManagerImpl+_dispatcher) : Dispatcher + * [.clear()](#PageStateManagerImpl+clear) + * [.setState()](#PageStateManagerImpl+setState) + * [.getState()](#PageStateManagerImpl+getState) + * [.getAllStates()](#PageStateManagerImpl+getAllStates) + * [._eraseExcessHistory()](#PageStateManagerImpl+_eraseExcessHistory) + * [._pushToHistory(newState)](#PageStateManagerImpl+_pushToHistory) + * [._callOnChangeCallback(newState)](#PageStateManagerImpl+_callOnChangeCallback) + + +* * * + +### new PageStateManagerImpl(dispatcher)  +Initializes the page state manager. + + +| Param | Type | Description | +| --- | --- | --- | +| dispatcher | Dispatcher | Dispatcher fires events to app. | + + +* * * + +### pageStateManagerImpl._states : Array.<Object.<string, \*>>  +**Kind**: instance property of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl._cursor : number  +**Kind**: instance property of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl.onChange : function  +**Kind**: instance property of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl._dispatcher : Dispatcher  +**Kind**: instance property of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl.clear()  +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl.setState()  +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl.getState()  +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl.getAllStates()  +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl._eraseExcessHistory()  +Erase the oldest state from storage only if it exceed max +defined size of history. + +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +* * * + +### pageStateManagerImpl._pushToHistory(newState)  +Push new state to history storage. + +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +| Param | Type | +| --- | --- | +| newState | Object.<string, \*> | + + +* * * + +### pageStateManagerImpl._callOnChangeCallback(newState)  +Call registered callback function on (@codelink onChange) with newState. + +**Kind**: instance method of [PageStateManagerImpl](#PageStateManagerImpl) + +| Param | Type | +| --- | --- | +| newState | Object.<string, \*> | + + +* * * + diff --git a/docs/_posts/2018-08-31-pagestate-page-state-manager.md b/docs/_posts/2018-08-31-pagestate-page-state-manager.md new file mode 100644 index 00000000..db81415c --- /dev/null +++ b/docs/_posts/2018-08-31-pagestate-page-state-manager.md @@ -0,0 +1,59 @@ +--- +category: "page/state" +title: "PageStateManager" +--- + +## PageStateManager  +Manager of the current page state and state history. + +**Kind**: global class + +* [PageStateManager](#PageStateManager) + * [.clear()](#PageStateManager+clear) + * [.setState(statePatch)](#PageStateManager+setState) + * [.getState()](#PageStateManager+getState) ⇒ Object.<string, \*> + * [.getAllStates()](#PageStateManager+getAllStates) ⇒ Array.<Object.<string, \*>> + + +* * * + +### pageStateManager.clear()  +Clears the state history. + +**Kind**: instance method of [PageStateManager](#PageStateManager) + +* * * + +### pageStateManager.setState(statePatch)  +Sets a new page state by applying the provided patch to the current +state. + +**Kind**: instance method of [PageStateManager](#PageStateManager) + +| Param | Type | Description | +| --- | --- | --- | +| statePatch | Object.<string, \*> | The patch of the current state. | + + +* * * + +### pageStateManager.getState() ⇒ Object.<string, \*>  +Returns the current page state. + +**Kind**: instance method of [PageStateManager](#PageStateManager) +**Returns**: Object.<string, \*> - The current page state. + +* * * + +### pageStateManager.getAllStates() ⇒ Array.<Object.<string, \*>>  +Returns the recorded history of page states. The states will be +chronologically sorted from the oldest to the newest. + +Note that the implementation may limit the size of the recorded history, +therefore the complete history may not be available. + +**Kind**: instance method of [PageStateManager](#PageStateManager) +**Returns**: Array.<Object.<string, \*>> - The recorded history of page states. + +* * * + diff --git a/docs/_posts/2018-08-31-router-abstract-router.md b/docs/_posts/2018-08-31-router-abstract-router.md new file mode 100644 index 00000000..254d8737 --- /dev/null +++ b/docs/_posts/2018-08-31-router-abstract-router.md @@ -0,0 +1,260 @@ +--- +category: "router" +title: "AbstractRouter" +--- + +## *AbstractRouter*  +The basic implementation of the Router interface, providing the +common or default functionality for parts of the API. + +**Kind**: global abstract class + +* *[AbstractRouter](#AbstractRouter)* + * *[new AbstractRouter(pageManager, factory, dispatcher)](#new_AbstractRouter_new)* + * *[._pageManager](#AbstractRouter+_pageManager) : PageManager* + * *[._factory](#AbstractRouter+_factory) : RouteFactory* + * *[._dispatcher](#AbstractRouter+_dispatcher) : Dispatcher* + * *[._protocol](#AbstractRouter+_protocol) : string* + * *[._host](#AbstractRouter+_host) : string* + * *[._root](#AbstractRouter+_root) : string* + * *[._languagePartPath](#AbstractRouter+_languagePartPath) : string* + * *[._routes](#AbstractRouter+_routes) : Map.<string, Route>* + * *[.init()](#AbstractRouter+init)* + * *[.add()](#AbstractRouter+add)* + * *[.remove()](#AbstractRouter+remove)* + * *[.getPath()](#AbstractRouter+getPath)* + * *[.getUrl()](#AbstractRouter+getUrl)* + * *[.getBaseUrl()](#AbstractRouter+getBaseUrl)* + * *[.getDomain()](#AbstractRouter+getDomain)* + * *[.getHost()](#AbstractRouter+getHost)* + * *[.getProtocol()](#AbstractRouter+getProtocol)* + * *[.getCurrentRouteInfo()](#AbstractRouter+getCurrentRouteInfo)* + * **[.listen()](#AbstractRouter+listen)** + * **[.redirect()](#AbstractRouter+redirect)** + * *[.link()](#AbstractRouter+link)* + * *[.route()](#AbstractRouter+route)* + * *[.handleError()](#AbstractRouter+handleError)* + * *[.handleNotFound()](#AbstractRouter+handleNotFound)* + * *[.isClientError()](#AbstractRouter+isClientError)* + * *[.isRedirection()](#AbstractRouter+isRedirection)* + * *[._extractRoutePath(path)](#AbstractRouter+_extractRoutePath) ⇒ string* + * *[._handle(route, params, options, [action])](#AbstractRouter+_handle) ⇒ Promise.<Object.<string, \*>>* + * *[._getRouteByPath(path)](#AbstractRouter+_getRouteByPath) ⇒ Route* + + +* * * + +### *new AbstractRouter(pageManager, factory, dispatcher)*  +Initializes the router. + + +| Param | Type | Description | +| --- | --- | --- | +| pageManager | PageManager | The page manager handling UI rendering, and transitions between pages if at the client side. | +| factory | RouteFactory | Factory for routes. | +| dispatcher | Dispatcher | Dispatcher fires events to app. | + + +* * * + +### *abstractRouter._pageManager : PageManager*  +The page manager handling UI rendering, and transitions between +pages if at the client side. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._factory : RouteFactory*  +Factory for routes. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._dispatcher : Dispatcher*  +Dispatcher fires events to app. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._protocol : string*  +The current protocol used to access the application, terminated by a +colon (for example https:). + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._host : string*  +The application's host. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._root : string*  +The URL path pointing to the application's root. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._languagePartPath : string*  +The URL path fragment used as a suffix to the _root field +that specifies the current language. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._routes : Map.<string, Route>*  +Storage of all known routes. The key are the route names. + +**Kind**: instance property of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.init()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.add()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.remove()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getPath()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getUrl()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getBaseUrl()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getDomain()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getHost()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getProtocol()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.getCurrentRouteInfo()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### **abstractRouter.listen()**  +**Kind**: instance abstract method of [AbstractRouter](#AbstractRouter) + +* * * + +### **abstractRouter.redirect()**  +**Kind**: instance abstract method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.link()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.route()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.handleError()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.handleNotFound()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.isClientError()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter.isRedirection()*  +**Kind**: instance method of [AbstractRouter](#AbstractRouter) + +* * * + +### *abstractRouter._extractRoutePath(path) ⇒ string*  +Strips the URL path part that points to the application's root (base +URL) from the provided path. + +**Kind**: instance method of [AbstractRouter](#AbstractRouter) +**Returns**: string - URL path relative to the application's base URL. +**Access**: protected + +| Param | Type | Description | +| --- | --- | --- | +| path | string | Relative or absolute URL path. | + + +* * * + +### *abstractRouter._handle(route, params, options, [action]) ⇒ Promise.<Object.<string, \*>>*  +Handles the provided route and parameters by initializing the route's +controller and rendering its state via the route's view. + +The result is then sent to the client if used at the server side, or +displayed if used as the client side. + +**Kind**: instance method of [AbstractRouter](#AbstractRouter) +**Returns**: Promise.<Object.<string, \*>> - A promise that resolves when the + page is rendered and the result is sent to the client, or + displayed if used at the client side. + +| Param | Type | Description | +| --- | --- | --- | +| route | Route | The route that should have its associated controller rendered via the associated view. | +| params | Object.<string, (Error\|string)> | Parameters extracted from the URL path and query. | +| options | Object | The options overrides route options defined in the routes.js configuration file. | +| [action] | Object | An action object describing what triggered this routing. | + + +* * * + +### *abstractRouter._getRouteByPath(path) ⇒ Route*  +Returns the route matching the provided URL path part. The path may +contain a query. + +**Kind**: instance method of [AbstractRouter](#AbstractRouter) +**Returns**: Route - The route matching the path, or null if no such + route exists. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path. | + + +* * * + diff --git a/docs/_posts/2018-08-31-router-client-router.md b/docs/_posts/2018-08-31-router-client-router.md new file mode 100644 index 00000000..4fb82a7b --- /dev/null +++ b/docs/_posts/2018-08-31-router-client-router.md @@ -0,0 +1,247 @@ +--- +category: "router" +title: "ClientRouter" +--- + +## Classes + +
+
ClientRouter
+

The client-side implementation of the Router interface.

+
+
+ +## Constants + +
+
CLICK : string
+

Name of the event produced when the user clicks the page using the +mouse, or touches the page and the touch event is not stopped.

+
+
POP_STATE : string
+

Name of the event fired when the user navigates back in the history.

+
+
REDIRECT : string
+
+
CLICK : string
+
+
POP_STATE : string
+
+
MOUSE_LEFT_BUTTON : number
+

The number used as the index of the mouse left button in DOM +MouseEvents.

+
+
+ +## ClientRouter  +The client-side implementation of the Router interface. + +**Kind**: global class + +* [ClientRouter](#ClientRouter) + * [new ClientRouter(pageManager, factory, dispatcher, window)](#new_ClientRouter_new) + * [._window](#ClientRouter+_window) : Window + * [.init()](#ClientRouter+init) + * [.getUrl()](#ClientRouter+getUrl) + * [.getPath()](#ClientRouter+getPath) + * [.listen()](#ClientRouter+listen) + * [.redirect()](#ClientRouter+redirect) + * [.route()](#ClientRouter+route) + * [.handleError()](#ClientRouter+handleError) + * [.handleNotFound()](#ClientRouter+handleNotFound) + * [._handleFatalError(error)](#ClientRouter+_handleFatalError) + * [._handleClick(event)](#ClientRouter+_handleClick) + * [._getAnchorElement(target)](#ClientRouter+_getAnchorElement) ⇒ Node + * [._isHashLink(targetUrl)](#ClientRouter+_isHashLink) ⇒ boolean + * [._isSameDomain([url])](#ClientRouter+_isSameDomain) ⇒ boolean + + +* * * + +### new ClientRouter(pageManager, factory, dispatcher, window)  +Initializes the client-side router. + + +| Param | Type | Description | +| --- | --- | --- | +| pageManager | PageManager | The page manager handling UI rendering, and transitions between pages if at the client side. | +| factory | RouteFactory | Factory for routes. | +| dispatcher | Dispatcher | Dispatcher fires events to app. | +| window | Window | The current global client-side APIs provider. | + + +* * * + +### clientRouter._window : Window  +Helper for accessing the native client-side APIs. + +**Kind**: instance property of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.init()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.getUrl()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.getPath()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.listen()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.redirect()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.route()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.handleError()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter.handleNotFound()  +**Kind**: instance method of [ClientRouter](#ClientRouter) + +* * * + +### clientRouter._handleFatalError(error)  +Handle a fatal error application state. IMA handle fatal error when IMA +handle error. + +**Kind**: instance method of [ClientRouter](#ClientRouter) + +| Param | Type | +| --- | --- | +| error | Error | + + +* * * + +### clientRouter._handleClick(event)  +Handles a click event. The method performs navigation to the target +location of the anchor (if it has one). + +The navigation will be handled by the router if the protocol and domain +of the anchor's target location (href) is the same as the current, +otherwise the method results in a hard redirect. + +**Kind**: instance method of [ClientRouter](#ClientRouter) + +| Param | Type | Description | +| --- | --- | --- | +| event | MouseEvent | The click event. | + + +* * * + +### clientRouter._getAnchorElement(target) ⇒ Node  +The method determines whether an anchor element or a child of an anchor +element has been clicked, and if it was, the method returns anchor +element else null. + +**Kind**: instance method of [ClientRouter](#ClientRouter) + +| Param | Type | +| --- | --- | +| target | Node | + + +* * * + +### clientRouter._isHashLink(targetUrl) ⇒ boolean  +Tests whether the provided target URL contains only an update of the +hash fragment of the current URL. + +**Kind**: instance method of [ClientRouter](#ClientRouter) +**Returns**: boolean - true if the navigation to target URL would + result only in updating the hash fragment of the current URL. + +| Param | Type | Description | +| --- | --- | --- | +| targetUrl | string | The target URL. | + + +* * * + +### clientRouter._isSameDomain([url]) ⇒ boolean  +Tests whether the the protocol and domain of the provided URL are the +same as the current. + +**Kind**: instance method of [ClientRouter](#ClientRouter) +**Returns**: boolean - true if the protocol and domain of the + provided URL are the same as the current. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [url] | string | "''" | The URL. | + + +* * * + +## Events : enum  +Names of the DOM events the router responds to. + +**Kind**: global enum + +* * * + +## ActionTypes : enum  +Name of actions that can trigger routing + +**Kind**: global enum + +* * * + +## CLICK : string  +Name of the event produced when the user clicks the page using the +mouse, or touches the page and the touch event is not stopped. + +**Kind**: global constant + +* * * + +## POP_STATE : string  +Name of the event fired when the user navigates back in the history. + +**Kind**: global constant + +* * * + +## REDIRECT : string  +**Kind**: global constant + +* * * + +## CLICK : string  +**Kind**: global constant + +* * * + +## POP_STATE : string  +**Kind**: global constant + +* * * + +## MOUSE_LEFT_BUTTON : number  +The number used as the index of the mouse left button in DOM +MouseEvents. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-router-events.md b/docs/_posts/2018-08-31-router-events.md new file mode 100644 index 00000000..71293e03 --- /dev/null +++ b/docs/_posts/2018-08-31-router-events.md @@ -0,0 +1,63 @@ +--- +category: "router" +title: "Events" +--- + +## Constants + +
+
BEFORE_HANDLE_ROUTE : string
+

Router fire event $IMA.$Router.beforeHandleRoute before page +manager handle the route. Event's data contain +{ params: Object<string, string>, route: ima.router.Route, +path: string, options: Object<string, *>}}. The path is current +path, the params are params extracted from path, the +route is handle route for path and the options is route +additional options.

+
+
AFTER_HANDLE_ROUTE : string
+

Router fire event $IMA.$Router.afterHandleRoute after page +manager handle the route. Event's data contain +{response: Object<string, >, params: Object<string, string>, +route: ima.router.Route, path: string, options: Object<string, >}}. +The response is page render result. The path is current +path, the params are params extracted from path, the +route is handle route for path and the options is route +additional options.

+
+
+ +## Events : enum  +Events constants, which is firing to app. + +**Kind**: global enum + +* * * + +## BEFORE_HANDLE_ROUTE : string  +Router fire event $IMA.$Router.beforeHandleRoute before page +manager handle the route. Event's data contain +{ params: Object, route: ima.router.Route, +path: string, options: Object}}. The path is current +path, the params are params extracted from path, the +route is handle route for path and the options is route +additional options. + +**Kind**: global constant + +* * * + +## AFTER_HANDLE_ROUTE : string  +Router fire event $IMA.$Router.afterHandleRoute after page +manager handle the route. Event's data contain +{response: Object, params: Object, +route: ima.router.Route, path: string, options: Object}}. +The response is page render result. The path is current +path, the params are params extracted from path, the +route is handle route for path and the options is route +additional options. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-router-request.md b/docs/_posts/2018-08-31-router-request.md new file mode 100644 index 00000000..917aa5ee --- /dev/null +++ b/docs/_posts/2018-08-31-router-request.md @@ -0,0 +1,116 @@ +--- +category: "router" +title: "Request" +--- + +## Request  +Wrapper for the ExpressJS request, exposing only the necessary minimum. + +**Kind**: global class + +* [Request](#Request) + * [new Request()](#new_Request_new) + * [._request](#Request+_request) : Express.Request + * [.init(request)](#Request+init) + * [.getPath()](#Request+getPath) ⇒ string + * [.getCookieHeader()](#Request+getCookieHeader) ⇒ string + * [.getFile()](#Request+getFile) ⇒ Object.<string, \*> + * [.getFiles()](#Request+getFiles) ⇒ Object.<string, \*> + * [.getBody()](#Request+getBody) ⇒ string + * [.getHeader(header)](#Request+getHeader) ⇒ string + * [.getIP()](#Request+getIP) ⇒ string + * [.getIPs()](#Request+getIPs) ⇒ Array.<string> + + +* * * + +### new Request()  +Initializes the request. + + +* * * + +### request._request : Express.Request  +The current ExpressJS request object, or null if running at +the client side. + +**Kind**: instance property of [Request](#Request) + +* * * + +### request.init(request)  +Initializes the request using the provided ExpressJS request object. + +**Kind**: instance method of [Request](#Request) + +| Param | Type | Description | +| --- | --- | --- | +| request | Express.Request | The ExpressJS request object representing the current request. Use null at the client side. | + + +* * * + +### request.getPath() ⇒ string  +Returns the path part of the URL to which the request was made. + +**Kind**: instance method of [Request](#Request) +**Returns**: string - The path to which the request was made. + +* * * + +### request.getCookieHeader() ⇒ string  +Returns the Cookie HTTP header value. + +**Kind**: instance method of [Request](#Request) +**Returns**: string - The value of the Cookie header. + +* * * + +### request.getFile() ⇒ Object.<string, \*>  +Returns uploaded file to server and meta information. + +**Kind**: instance method of [Request](#Request) + +* * * + +### request.getFiles() ⇒ Object.<string, \*>  +Returns upaloaded files to server with their meta information. + +**Kind**: instance method of [Request](#Request) + +* * * + +### request.getBody() ⇒ string  +Returns body of request. + +**Kind**: instance method of [Request](#Request) + +* * * + +### request.getHeader(header) ⇒ string  +Returns the specified HTTP request header. + +**Kind**: instance method of [Request](#Request) + +| Param | Type | +| --- | --- | +| header | string | + + +* * * + +### request.getIP() ⇒ string  +Returns the remote IP address of the request. + +**Kind**: instance method of [Request](#Request) + +* * * + +### request.getIPs() ⇒ Array.<string>  +Returns array of IP addresses specified in the “X-Forwarded-For” +request header. + +**Kind**: instance method of [Request](#Request) + +* * * + diff --git a/docs/_posts/2018-08-31-router-response.md b/docs/_posts/2018-08-31-router-response.md new file mode 100644 index 00000000..3cb022ec --- /dev/null +++ b/docs/_posts/2018-08-31-router-response.md @@ -0,0 +1,220 @@ +--- +category: "router" +title: "Response" +--- + +## Response  +Wrapper for the ExpressJS response, exposing only the necessary minimum. + +**Kind**: global class + +* [Response](#Response) + * [new Response()](#new_Response_new) + * [._response](#Response+_response) : Express.Response + * [._isSent](#Response+_isSent) : boolean + * [._status](#Response+_status) : number + * [._content](#Response+_content) : string + * [._pageState](#Response+_pageState) : Object.<string, \*> + * [._internalCookieStorage](#Response+_internalCookieStorage) : Map.<string, {value: string, options: {domain: string=, expires: (number\|string)=}}> + * [._cookieTransformFunction](#Response+_cookieTransformFunction) : Object + * [.init(response, [cookieTransformFunction])](#Response+init) ⇒ ima.router.Response + * [.redirect(url, [status])](#Response+redirect) ⇒ [Response](#Response) + * [.status(httpStatus)](#Response+status) ⇒ [Response](#Response) + * [.send(content)](#Response+send) ⇒ [Response](#Response) + * [.setPageState(pageState)](#Response+setPageState) ⇒ [Response](#Response) + * [.setCookie(name, value, options)](#Response+setCookie) ⇒ [Response](#Response) + * [.getResponseParams()](#Response+getResponseParams) ⇒ Object + * [.isResponseSent()](#Response+isResponseSent) ⇒ boolean + * [._setCookieHeaders()](#Response+_setCookieHeaders) + * [._prepareCookieOptionsForExpress(options)](#Response+_prepareCookieOptionsForExpress) ⇒ Object + + +* * * + +### new Response()  +Initializes the response. + + +* * * + +### response._response : Express.Response  +The ExpressJS response object, or null if running at the +client side. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response._isSent : boolean  +It is flag for sent response for request. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response._status : number  +HTTP Status code. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response._content : string  +The content of response. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response._pageState : Object.<string, \*>  +The rendered page state. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response._internalCookieStorage : Map.<string, {value: string, options: {domain: string=, expires: (number\|string)=}}>  +Internal cookie storage for Set-Cookie header. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response._cookieTransformFunction : Object  +Transform function for cookie value. + +**Kind**: instance property of [Response](#Response) + +* * * + +### response.init(response, [cookieTransformFunction]) ⇒ ima.router.Response  +Initializes this response wrapper with the provided ExpressJS response +object. + +**Kind**: instance method of [Response](#Response) +**Returns**: ima.router.Response - This response. + +| Param | Type | Description | +| --- | --- | --- | +| response | Express.Response | The ExpressJS response, or null if the code is running at the client side. | +| [cookieTransformFunction] | Object | | + + +* * * + +### response.redirect(url, [status]) ⇒ [Response](#Response)  +Redirects the client to the specified location, with the specified +redirect HTTP response code. + +For full list of HTTP response status codes see +http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html + +Use this method only at the server side. + +**Kind**: instance method of [Response](#Response) +**Returns**: [Response](#Response) - This response. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| url | string | | The URL to which the client should be redirected. | +| [status] | number | 302 | The HTTP status code to send to the client. | + + +* * * + +### response.status(httpStatus) ⇒ [Response](#Response)  +Sets the HTTP status code that will be sent to the client when the +response is sent. + +For full list of available response codes see +http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html + +Use this method only at the server side. + +**Kind**: instance method of [Response](#Response) +**Returns**: [Response](#Response) - This response. + +| Param | Type | Description | +| --- | --- | --- | +| httpStatus | number | HTTP response status code to send to the client. | + + +* * * + +### response.send(content) ⇒ [Response](#Response)  +Sends the response to the client with the provided content. Use this +method only at the server side. + +**Kind**: instance method of [Response](#Response) +**Returns**: [Response](#Response) - This response. + +| Param | Type | Description | +| --- | --- | --- | +| content | string | The response body. | + + +* * * + +### response.setPageState(pageState) ⇒ [Response](#Response)  +Sets the rendered page state. + +**Kind**: instance method of [Response](#Response) +**Returns**: [Response](#Response) - This response. + +| Param | Type | Description | +| --- | --- | --- | +| pageState | Object.<string, \*> | The rendered page state. | + + +* * * + +### response.setCookie(name, value, options) ⇒ [Response](#Response)  +Sets a cookie, which will be sent to the client with the response. + +**Kind**: instance method of [Response](#Response) +**Returns**: [Response](#Response) - This response. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The cookie name. | +| value | boolean \| number \| string | The cookie value, will be converted to string. | +| options | Object | Cookie attributes. Only the attributes listed in the type annotation of this field are supported. For documentation and full list of cookie attributes see http://tools.ietf.org/html/rfc2965#page-5 | + + +* * * + +### response.getResponseParams() ⇒ Object  +Return object which contains response status, content and rendered +page state. + +**Kind**: instance method of [Response](#Response) + +* * * + +### response.isResponseSent() ⇒ boolean  +Return true if response is sent from server to client. + +**Kind**: instance method of [Response](#Response) + +* * * + +### response._setCookieHeaders()  +Set cookie headers for response. + +**Kind**: instance method of [Response](#Response) + +* * * + +### response._prepareCookieOptionsForExpress(options) ⇒ Object  +Prepares cookie options for Express. + +**Kind**: instance method of [Response](#Response) +**Returns**: Object - Cookie options prepared for Express. + +| Param | Type | Description | +| --- | --- | --- | +| options | Object | Cookie attributes. Only the attributes listed in the type annotation of this field are supported. For documentation and full list of cookie attributes see http://tools.ietf.org/html/rfc2965#page-5 | + + +* * * + diff --git a/docs/_posts/2018-08-31-router-route-factory.md b/docs/_posts/2018-08-31-router-route-factory.md new file mode 100644 index 00000000..f4d54cb3 --- /dev/null +++ b/docs/_posts/2018-08-31-router-route-factory.md @@ -0,0 +1,29 @@ +--- +category: "router" +title: "RouteFactory" +--- + +## RouteFactory  +Utility factory used by router to create routes. + +**Kind**: global class + +* * * + +### routeFactory.createRoute(name, pathExpression, controller, view, options) ⇒ Route  +Create new instance of ima.router.Route. + +**Kind**: instance method of [RouteFactory](#RouteFactory) +**Returns**: Route - The constructed route. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The unique name of this route, identifying it among the rest of the routes in the application. | +| pathExpression | string | A path expression specifying the URL path part matching this route (must not contain a query string), optionally containing named parameter placeholders specified as :parameterName. | +| controller | string | The full name of Object Container alias identifying the controller associated with this route. | +| view | string | The full name or Object Container alias identifying the view class associated with this route. | +| options | Object | The route additional options. | + + +* * * + diff --git a/docs/_posts/2018-08-31-router-route-names.md b/docs/_posts/2018-08-31-router-route-names.md new file mode 100644 index 00000000..44eba5ee --- /dev/null +++ b/docs/_posts/2018-08-31-router-route-names.md @@ -0,0 +1,43 @@ +--- +category: "router" +title: "RouteNames" +--- + +## Constants + +
+
NOT_FOUND : string
+

The internal route name used for the "not found" error page (the 4XX +HTTP status code error page).

+
+
ERROR : string
+

The internal route name used for the error page (the 5XX HTTP status +code error page).

+
+
+ +## RouteNames : enum  +HTTP status code constants, representing the HTTP status codes recognized +and processed by this proxy. + +**Kind**: global enum +**See**: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html + +* * * + +## NOT_FOUND : string  +The internal route name used for the "not found" error page (the 4XX +HTTP status code error page). + +**Kind**: global constant + +* * * + +## ERROR : string  +The internal route name used for the error page (the 5XX HTTP status +code error page). + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-router-route.md b/docs/_posts/2018-08-31-router-route.md new file mode 100644 index 00000000..f993de22 --- /dev/null +++ b/docs/_posts/2018-08-31-router-route.md @@ -0,0 +1,663 @@ +--- +category: "router" +title: "Route" +--- + +## Classes + +
+
Route
+

Utility for representing and manipulating a single route in the router's +configuration.

+
+
+ +## Constants + +
+
CONTROL_CHARACTERS_REGEXP : RegExp
+

Regular expression matching all control characters used in regular +expressions. The regular expression is used to match these characters in +path expressions and replace them appropriately so the path expression can +be compiled to a regular expression.

+
+
LOOSE_SLASHES_REGEXP : RegExp
+

Regular expression used to match and remove the starting and trailing +forward slashes from a path expression or a URL path.

+
+
PARAMS_REGEXP_UNIVERSAL : RegExp
+

Regular expression used to match the parameter names from a path expression.

+
+
PARAMS_REGEXP_REQUIRED : RegExp
+

Regular expression used to match the required parameter names from a path expression.

+
+
PARAMS_REGEXP_CORE_NAME : RegExp
+

Regular expression used to separate a camelCase parameter name

+
+
PARAMS_START_PATTERN : String
+

Regular expression used to match start of parameter names from a path expression.

+
+
PARAMS_END_PATTERN : String
+

Regular expression used to match end of parameter names from a path expression.

+
+
PARAMS_NEVER_MATCH_REGEXP : RegExp
+

Regular expression used to never match the parameter names from a path expression. +It's used for wrong parameters order (optional vs. required ones)

+
+
PARAMS_MAIN_REGEXP : RegExp
+

Regular expression used to match all main parameter names from a path expression.

+
+
SUBPARAMS_REQUIRED_REGEXP : Object.<String, RegExp>
+

Regular expression used to match the required subparameter names from a path expression. +(e.g. for path '/:paramA-:paramB/:nextParam' are subparametres 'paramA' and 'paramB')

+
+
SUBPARAMS_OPT_REGEXP : Object.<String, RegExp>
+

Regular expression used to match the optional parameter names from a path expression.

+
+
PARAMS_REGEXP_OPT : RegExp
+

Regular expression used to match the parameter names from a path expression.

+
+
+ +## Route  +Utility for representing and manipulating a single route in the router's +configuration. + +**Kind**: global class + +* [Route](#Route) + * [new Route(name, pathExpression, controller, view, options)](#new_Route_new) + * [._name](#Route+_name) : string + * [._pathExpression](#Route+_pathExpression) : string + * [._controller](#Route+_controller) : string + * [._view](#Route+_view) : React.Component + * [._options](#Route+_options) : Object + * [._trimmedPathExpression](#Route+_trimmedPathExpression) : string + * [._parameterNames](#Route+_parameterNames) : Array.<string> + * [._hasParameters](#Route+_hasParameters) : boolean + * [._matcher](#Route+_matcher) : RegExp + * [.toPath([params])](#Route+toPath) ⇒ string + * [.getName()](#Route+getName) ⇒ string + * [.getController()](#Route+getController) ⇒ string + * [.getView()](#Route+getView) ⇒ string + * [.getOptions()](#Route+getOptions) ⇒ Object + * [.getPathExpression()](#Route+getPathExpression) ⇒ string + * [.matches(path)](#Route+matches) ⇒ boolean + * [.extractParameters(path)](#Route+extractParameters) ⇒ Object.<string, ?string> + * [._substituteRequiredParamInPath(path, paramName, paramValue)](#Route+_substituteRequiredParamInPath) ⇒ string + * [._substituteOptionalParamInPath(path, paramName, paramValue)](#Route+_substituteOptionalParamInPath) ⇒ string + * [._cleanUnusedOptionalParams(path)](#Route+_cleanUnusedOptionalParams) ⇒ string + * [._isOptionalParamInPath(path, paramName)](#Route+_isOptionalParamInPath) ⇒ boolean + * [._isRequiredParamInPath(path, paramName)](#Route+_isRequiredParamInPath) ⇒ boolean + * [._getClearParamName(rawParam)](#Route+_getClearParamName) ⇒ string + * [._getSubparamPattern(delimeter)](#Route+_getSubparamPattern) ⇒ string + * [._checkOptionalParamsOrder(allMainParams)](#Route+_checkOptionalParamsOrder) ⇒ boolean + * [._checkParametersOrder(clearedPathExpr)](#Route+_checkParametersOrder) ⇒ Bool + * [._replaceOptionalParametersInPath(path, optionalParams)](#Route+_replaceOptionalParametersInPath) ⇒ string + * [._replaceRequiredSubParametersInPath(path, clearedPathExpr)](#Route+_replaceRequiredSubParametersInPath) ⇒ string + * [._replaceOptionalSubParametersInPath(path, optionalSubparamsOthers, optionalSubparamsLast)](#Route+_replaceOptionalSubParametersInPath) ⇒ string + * [._compileToRegExp(pathExpression)](#Route+_compileToRegExp) ⇒ RegExp + * [._getParameters(path)](#Route+_getParameters) ⇒ Object.<string, string> + * [._extractParameters(parameterValues)](#Route+_extractParameters) ⇒ Object.<string, ?string> + * [._decodeURIParameter(parameterValue)](#Route+_decodeURIParameter) ⇒ string + * [._cleanOptParamName(paramName)](#Route+_cleanOptParamName) ⇒ string + * [._isParamOptional(paramName)](#Route+_isParamOptional) ⇒ boolean + * [._getQuery(path)](#Route+_getQuery) ⇒ Object.<string, ?string> + * [._getTrimmedPath(path)](#Route+_getTrimmedPath) ⇒ string + * [._getParameterNames(pathExpression)](#Route+_getParameterNames) ⇒ Array.<string> + + +* * * + +### new Route(name, pathExpression, controller, view, options)  +Initializes the route. + + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The unique name of this route, identifying it among the rest of the routes in the application. | +| pathExpression | string | A path expression specifying the URL path part matching this route (must not contain a query string), optionally containing named parameter placeholders specified as :parameterName. | +| controller | string | The full name of Object Container alias identifying the controller associated with this route. | +| view | string | The full name or Object Container alias identifying the view class associated with this route. | +| options | Object | The route additional options. | + + +* * * + +### route._name : string  +The unique name of this route, identifying it among the rest of the +routes in the application. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._pathExpression : string  +The original URL path expression from which this route was created. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._controller : string  +The full name of Object Container alias identifying the controller +associated with this route. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._view : React.Component  +The full name or Object Container alias identifying the view class +associated with this route. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._options : Object  +The route additional options. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._trimmedPathExpression : string  +The path expression with the trailing slashes trimmed. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._parameterNames : Array.<string>  +The names of the parameters in this route. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._hasParameters : boolean  +Set to true if this route contains parameters in its path. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route._matcher : RegExp  +A regexp used to match URL path against this route and extract the +parameter values from the matched URL paths. + +**Kind**: instance property of [Route](#Route) + +* * * + +### route.toPath([params]) ⇒ string  +Creates the URL and query parts of a URL by substituting the route's +parameter placeholders by the provided parameter value. + +The extraneous parameters that do not match any of the route's +placeholders will be appended as the query string. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - Path and, if necessary, query parts of the URL + representing this route with its parameters replaced by the + provided parameter values. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [params] | Object.<string, (number\|string)> | {} | The route parameter values. | + + +* * * + +### route.getName() ⇒ string  +Returns the unique identifying name of this route. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - The name of the route, identifying it. + +* * * + +### route.getController() ⇒ string  +Returns the full name of the controller to use when this route is +matched by the current URL, or an Object Container-registered alias of +the controller. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - The name of alias of the controller. + +* * * + +### route.getView() ⇒ string  +Returns the full name of the view class or an Object +Container-registered alias for the view class, representing the view to +use when this route is matched by the current URL. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - The name or alias of the view class. + +* * * + +### route.getOptions() ⇒ Object  +Return route additional options. + +**Kind**: instance method of [Route](#Route) + +* * * + +### route.getPathExpression() ⇒ string  +Returns the path expression, which is the parametrized pattern matching +the URL paths matched by this route. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - The path expression. + +* * * + +### route.matches(path) ⇒ boolean  +Tests whether the provided URL path matches this route. The provided +path may contain the query. + +**Kind**: instance method of [Route](#Route) +**Returns**: boolean - true if the provided path matches this route. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path. | + + +* * * + +### route.extractParameters(path) ⇒ Object.<string, ?string>  +Extracts the parameter values from the provided path. The method +extracts both the in-path parameters and parses the query, allowing the +query parameters to override the in-path parameters. + +The method returns an empty hash object if the path does not match this +route. + +**Kind**: instance method of [Route](#Route) +**Returns**: Object.<string, ?string> - Map of parameter names to parameter + values. + +| Param | Type | +| --- | --- | +| path | string | + + +* * * + +### route._substituteRequiredParamInPath(path, paramName, paramValue) ⇒ string  +Replace required parameter placeholder in path with parameter value. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - New path. + +| Param | Type | +| --- | --- | +| path | string | +| paramName | string | +| paramValue | string | + + +* * * + +### route._substituteOptionalParamInPath(path, paramName, paramValue) ⇒ string  +Replace optional param placeholder in path with parameter value. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - New path. + +| Param | Type | +| --- | --- | +| path | string | +| paramName | string | +| paramValue | string | + + +* * * + +### route._cleanUnusedOptionalParams(path) ⇒ string  +Remove unused optional param placeholders in path. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - New path. + +| Param | Type | +| --- | --- | +| path | string | + + +* * * + +### route._isOptionalParamInPath(path, paramName) ⇒ boolean  +Returns true, if paramName is placed in path. + +**Kind**: instance method of [Route](#Route) + +| Param | Type | +| --- | --- | +| path | string | +| paramName | string | + + +* * * + +### route._isRequiredParamInPath(path, paramName) ⇒ boolean  +Returns true, if paramName is placed in path and it's required. + +**Kind**: instance method of [Route](#Route) + +| Param | Type | +| --- | --- | +| path | string | +| paramName | string | + + +* * * + +### route._getClearParamName(rawParam) ⇒ string  +Extract clear parameter name, e.q. '?name' or 'name' + +**Kind**: instance method of [Route](#Route) + +| Param | Type | +| --- | --- | +| rawParam | string | + + +* * * + +### route._getSubparamPattern(delimeter) ⇒ string  +Get pattern for subparameter. + +**Kind**: instance method of [Route](#Route) + +| Param | Type | Description | +| --- | --- | --- | +| delimeter | string | Parameters delimeter | + + +* * * + +### route._checkOptionalParamsOrder(allMainParams) ⇒ boolean  +Check if all optional params are below required ones + +**Kind**: instance method of [Route](#Route) + +| Param | Type | +| --- | --- | +| allMainParams | array.<string> | + + +* * * + +### route._checkParametersOrder(clearedPathExpr) ⇒ Bool  +Check if main parametres have correct order. +It means that required param cannot follow optional one. + +**Kind**: instance method of [Route](#Route) +**Returns**: Bool - Returns TRUE if order is correct. + +| Param | Type | Description | +| --- | --- | --- | +| clearedPathExpr | string | The cleared URL path (removed first and last slash, ...). | + + +* * * + +### route._replaceOptionalParametersInPath(path, optionalParams) ⇒ string  +Convert main optional parameters to capture sequences + +**Kind**: instance method of [Route](#Route) +**Returns**: string - RegExp pattern. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path. | +| optionalParams | array.<string> | List of main optimal parameter expressions | + + +* * * + +### route._replaceRequiredSubParametersInPath(path, clearedPathExpr) ⇒ string  +Convert required subparameters to capture sequences + +**Kind**: instance method of [Route](#Route) +**Returns**: string - RegExp pattern. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path (route definition). | +| clearedPathExpr | string | The original cleared URL path. | + + +* * * + +### route._replaceOptionalSubParametersInPath(path, optionalSubparamsOthers, optionalSubparamsLast) ⇒ string  +Convert optional subparameters to capture sequences + +**Kind**: instance method of [Route](#Route) +**Returns**: string - RegExp pattern. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path (route definition). | +| optionalSubparamsOthers | array.<string> | List of all subparam. expressions but last ones | +| optionalSubparamsLast | array.<string> | List of last subparam. expressions | + + +* * * + +### route._compileToRegExp(pathExpression) ⇒ RegExp  +Compiles the path expression to a regular expression that can be used +for easier matching of URL paths against this route, and extracting the +path parameter values from the URL path. + +**Kind**: instance method of [Route](#Route) +**Returns**: RegExp - The compiled regular expression. + +| Param | Type | Description | +| --- | --- | --- | +| pathExpression | string | The path expression to compile. | + + +* * * + +### route._getParameters(path) ⇒ Object.<string, string>  +Parses the provided path and extract the in-path parameters. The method +decodes the parameters and returns them in a hash object. + +**Kind**: instance method of [Route](#Route) +**Returns**: Object.<string, string> - The parsed path parameters. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path. | + + +* * * + +### route._extractParameters(parameterValues) ⇒ Object.<string, ?string>  +Extract parameters from given path. + +**Kind**: instance method of [Route](#Route) +**Returns**: Object.<string, ?string> - Params object. + +| Param | Type | +| --- | --- | +| parameterValues | Array.<string> | + + +* * * + +### route._decodeURIParameter(parameterValue) ⇒ string  +Decoding parameters. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - decodedValue + +| Param | Type | +| --- | --- | +| parameterValue | string | + + +* * * + +### route._cleanOptParamName(paramName) ⇒ string  +Returns optional param name without "?" + +**Kind**: instance method of [Route](#Route) +**Returns**: string - Strict param name without "?" + +| Param | Type | Description | +| --- | --- | --- | +| paramName | string | Full param name with "?" | + + +* * * + +### route._isParamOptional(paramName) ⇒ boolean  +Checks if parameter is optional or not. + +**Kind**: instance method of [Route](#Route) +**Returns**: boolean - return true if is optional, otherwise false + +| Param | Type | +| --- | --- | +| paramName | string | + + +* * * + +### route._getQuery(path) ⇒ Object.<string, ?string>  +Extracts and decodes the query parameters from the provided URL path and +query. + +**Kind**: instance method of [Route](#Route) +**Returns**: Object.<string, ?string> - Parsed query parameters. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The URL path, including the optional query string (if any). | + + +* * * + +### route._getTrimmedPath(path) ⇒ string  +Trims the trailing forward slash from the provided URL path. + +**Kind**: instance method of [Route](#Route) +**Returns**: string - Trimmed path. + +| Param | Type | Description | +| --- | --- | --- | +| path | string | The path to trim. | + + +* * * + +### route._getParameterNames(pathExpression) ⇒ Array.<string>  +Extracts the parameter names from the provided path expression. + +**Kind**: instance method of [Route](#Route) +**Returns**: Array.<string> - The names of the parameters defined in the provided + path expression. + +| Param | Type | Description | +| --- | --- | --- | +| pathExpression | string | The path expression. | + + +* * * + +## CONTROL_CHARACTERS_REGEXP : RegExp  +Regular expression matching all control characters used in regular +expressions. The regular expression is used to match these characters in +path expressions and replace them appropriately so the path expression can +be compiled to a regular expression. + +**Kind**: global constant + +* * * + +## LOOSE_SLASHES_REGEXP : RegExp  +Regular expression used to match and remove the starting and trailing +forward slashes from a path expression or a URL path. + +**Kind**: global constant + +* * * + +## PARAMS_REGEXP_UNIVERSAL : RegExp  +Regular expression used to match the parameter names from a path expression. + +**Kind**: global constant + +* * * + +## PARAMS_REGEXP_REQUIRED : RegExp  +Regular expression used to match the required parameter names from a path expression. + +**Kind**: global constant + +* * * + +## PARAMS_REGEXP_CORE_NAME : RegExp  +Regular expression used to separate a camelCase parameter name + +**Kind**: global constant + +* * * + +## PARAMS_START_PATTERN : String  +Regular expression used to match start of parameter names from a path expression. + +**Kind**: global constant + +* * * + +## PARAMS_END_PATTERN : String  +Regular expression used to match end of parameter names from a path expression. + +**Kind**: global constant + +* * * + +## PARAMS_NEVER_MATCH_REGEXP : RegExp  +Regular expression used to never match the parameter names from a path expression. +It's used for wrong parameters order (optional vs. required ones) + +**Kind**: global constant + +* * * + +## PARAMS_MAIN_REGEXP : RegExp  +Regular expression used to match all main parameter names from a path expression. + +**Kind**: global constant + +* * * + +## SUBPARAMS_REQUIRED_REGEXP : Object.<String, RegExp>  +Regular expression used to match the required subparameter names from a path expression. +(e.g. for path '/:paramA-:paramB/:nextParam' are subparametres 'paramA' and 'paramB') + +**Kind**: global constant + +* * * + +## SUBPARAMS_OPT_REGEXP : Object.<String, RegExp>  +Regular expression used to match the optional parameter names from a path expression. + +**Kind**: global constant + +* * * + +## PARAMS_REGEXP_OPT : RegExp  +Regular expression used to match the parameter names from a path expression. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-router-router.md b/docs/_posts/2018-08-31-router-router.md new file mode 100644 index 00000000..13c83d25 --- /dev/null +++ b/docs/_posts/2018-08-31-router-router.md @@ -0,0 +1,286 @@ +--- +category: "router" +title: "Router" +--- + +## Router  +**Kind**: global interface + +* [Router](#Router) + * [.init(config)](#Router+init) + * [.add(name, pathExpression, controller, view, [options])](#Router+add) ⇒ [Router](#Router) + * [.remove(name)](#Router+remove) ⇒ [Router](#Router) + * [.getPath()](#Router+getPath) ⇒ string + * [.getUrl()](#Router+getUrl) ⇒ string + * [.getBaseUrl()](#Router+getBaseUrl) ⇒ string + * [.getDomain()](#Router+getDomain) ⇒ string + * [.getHost()](#Router+getHost) ⇒ string + * [.getProtocol()](#Router+getProtocol) ⇒ string + * [.getCurrentRouteInfo()](#Router+getCurrentRouteInfo) ⇒ Object + * [.listen()](#Router+listen) ⇒ [Router](#Router) + * [.redirect(url, [options], [action])](#Router+redirect) + * [.link(routeName, params)](#Router+link) ⇒ string + * [.route(path, [options], [action])](#Router+route) ⇒ Promise.<Object.<string, \*>> + * [.handleError(params, [options])](#Router+handleError) ⇒ Promise.<Object.<string, \*>> + * [.handleNotFound(params, [options])](#Router+handleNotFound) ⇒ Promise.<Object.<string, \*>> + * [.isClientError(reason)](#Router+isClientError) ⇒ boolean + * [.isRedirection(reason)](#Router+isRedirection) ⇒ boolean + + +* * * + +### router.init(config)  +Initializes the router with the provided configuration. + +**Kind**: instance method of [Router](#Router) + +| Param | Type | Description | +| --- | --- | --- | +| config | Object | Router configuration. The $Protocol field must be the current protocol used to access the application, terminated by a collon (for example https:). The $Root field must specify the URL path pointing to the application's root. The $LanguagePartPath field must be the URL path fragment used as a suffix to the $Root field that specifies the current language. The $Host field must be the application's domain (and the port number if other than the default is used) in the following form: `${protocol//${host}`}. | + + +* * * + +### router.add(name, pathExpression, controller, view, [options]) ⇒ [Router](#Router)  +Adds a new route to router. + +**Kind**: instance method of [Router](#Router) +**Returns**: [Router](#Router) - This router. +**Throws**: + +- ImaError Thrown if a route with the same name already exists. + + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The unique name of this route, identifying it among the rest of the routes in the application. | +| pathExpression | string | A path expression specifying the URL path part matching this route (must not contain a query string), optionally containing named parameter placeholders specified as :parameterName. The name of the parameter is terminated by a forward slash (/) or the end of the path expression string. The path expression may also contain optional parameters, which are specified as :?parameterName. It is recommended to specify the optional parameters at the end of the path expression. | +| controller | string | The full name of Object Container alias identifying the controller associated with this route. | +| view | string | The full name or Object Container alias identifying the view class associated with this route. | +| [options] | Object | Additional route options, specified how the navigation to the route will be handled. The onlyUpdate can be either a flag signalling whether the current controller and view instances should be kept if they match the ones used by the previous route; or a callback function that will receive the previous controller and view identifiers used in the previously matching route, and returns a boolean representing the value of the flag. This flag is disabled by default. The autoScroll flag signals whether the page should be scrolled to the top when the navigation takes place. This flag is enabled by default. The allowSPA flag can be used to make the route always served from the server and never using the SPA page even if the server is overloaded. This is useful for routes that use different document views (specified by the documentView option), for example for rendering the content of iframes. | + + +* * * + +### router.remove(name) ⇒ [Router](#Router)  +Removes the specified route from the router's known routes. + +**Kind**: instance method of [Router](#Router) +**Returns**: [Router](#Router) - This router. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The route's unique name, identifying the route to remove. | + + +* * * + +### router.getPath() ⇒ string  +Returns the current path part of the current URL, including the query +string (if any). + +**Kind**: instance method of [Router](#Router) +**Returns**: string - The path and query parts of the current URL. + +* * * + +### router.getUrl() ⇒ string  +Returns the current absolute URL (including protocol, host, query, etc). + +**Kind**: instance method of [Router](#Router) +**Returns**: string - The current absolute URL. + +* * * + +### router.getBaseUrl() ⇒ string  +Returns the application's absolute base URL, pointing to the public root +of the application. + +**Kind**: instance method of [Router](#Router) +**Returns**: string - The application's base URL. + +* * * + +### router.getDomain() ⇒ string  +Returns the application's domain in the following form +`${protocol//${host}`}. + +**Kind**: instance method of [Router](#Router) +**Returns**: string - The current application's domain. + +* * * + +### router.getHost() ⇒ string  +Returns application's host (domain and, if necessary, the port number). + +**Kind**: instance method of [Router](#Router) +**Returns**: string - The current application's host. + +* * * + +### router.getProtocol() ⇒ string  +Returns the current protocol used to access the application, terminated +by a colon (for example https:). + +**Kind**: instance method of [Router](#Router) +**Returns**: string - The current application protocol used to access the + application. + +* * * + +### router.getCurrentRouteInfo() ⇒ Object  +Returns the information about the currently active route. + +**Kind**: instance method of [Router](#Router) +**Returns**: Object - The information about the current route. +**Throws**: + +- ImaError Thrown if a route is not define for current path. + + +* * * + +### router.listen() ⇒ [Router](#Router)  +Registers event listeners at the client side window object allowing the +router to capture user's history (history pop state - going "back") and +page (clicking links) navigation. + +The router will start processing the navigation internally, handling the +user's navigation to display the page related to the URL resulting from +the user's action. + +Note that the router will not prevent forms from being submitted to the +server. + +The effects of this method cannot be reverted. This method has no effect +at the server side. + +**Kind**: instance method of [Router](#Router) +**Returns**: [Router](#Router) - This router. + +* * * + +### router.redirect(url, [options], [action])  +Redirects the client to the specified location. + +At the server side the method results in responding to the client with a +redirect HTTP status code and the Location header. + +At the client side the method updates the current URL by manipulating +the browser history (if the target URL is at the same domain and +protocol as the current one) or performs a hard redirect (if the target +URL points to a different protocol or domain). + +The method will result in the router handling the new URL and routing +the client to the related page if the URL is set at the client side and +points to the same domain and protocol. + +**Kind**: instance method of [Router](#Router) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| url | string | | The URL to which the client should be redirected. | +| [options] | Object | {} | The options overrides route options defined in the routes.js configuration file. | +| [action] | Object | | An action object describing what triggered this routing. | + + +* * * + +### router.link(routeName, params) ⇒ string  +Generates an absolute URL (including protocol, domain, etc) for the +specified route by substituting the route's parameter placeholders with +the provided parameter values. + +**Kind**: instance method of [Router](#Router) +**Returns**: string - An absolute URL for the specified route and parameters. + +| Param | Type | Description | +| --- | --- | --- | +| routeName | string | The unique name of the route, identifying the route to use. | +| params | Object.<string, string> | Parameter values for the route's parameter placeholders. Extraneous parameters will be added as URL query. | + + +* * * + +### router.route(path, [options], [action]) ⇒ Promise.<Object.<string, \*>>  +Routes the application to the route matching the providing path, renders +the route page and sends the result to the client. + +**Kind**: instance method of [Router](#Router) +**Returns**: Promise.<Object.<string, \*>> - A promise resolved + when the error has been handled and the response has been sent + to the client, or displayed if used at the client side. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| path | string | | The URL path part received from the client, with optional query. | +| [options] | Object | {} | The options overrides route options defined in the routes.js configuration file. | +| [action] | Object | | An action object describing what triggered this routing. | + + +* * * + +### router.handleError(params, [options]) ⇒ Promise.<Object.<string, \*>>  +Handles an internal server error by responding with the appropriate +"internal server error" error page. + +**Kind**: instance method of [Router](#Router) +**Returns**: Promise.<Object.<string, \*>> - A promise resolved when the error + has been handled and the response has been sent to the client, + or displayed if used at the client side. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| params | Object.<string, (Error\|string)> | | Parameters extracted from the current URL path and query. | +| [options] | Object | {} | The options overrides route options defined in the routes.js configuration file. | + + +* * * + +### router.handleNotFound(params, [options]) ⇒ Promise.<Object.<string, \*>>  +Handles a "not found" error by responding with the appropriate "not +found" error page. + +**Kind**: instance method of [Router](#Router) +**Returns**: Promise.<Object.<string, \*>> - A promise resolved + when the error has been handled and the response has been sent + to the client, or displayed if used at the client side. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| params | Object.<string, (Error\|string)> | | Parameters extracted from the current URL path and query. | +| [options] | Object | {} | The options overrides route options defined in the routes.js configuration file. | + + +* * * + +### router.isClientError(reason) ⇒ boolean  +Tests, if possible, whether the specified error was caused by the +client's action (for example wrong URL or request encoding) or by a +failure at the server side. + +**Kind**: instance method of [Router](#Router) +**Returns**: boolean - true if the error was caused the action of the + client. + +| Param | Type | Description | +| --- | --- | --- | +| reason | ImaError \| Error | The encountered error. | + + +* * * + +### router.isRedirection(reason) ⇒ boolean  +Tests, if possible, whether the specified error lead to redirection. + +**Kind**: instance method of [Router](#Router) +**Returns**: boolean - true if the error was caused the action of the + redirection. + +| Param | Type | Description | +| --- | --- | --- | +| reason | ImaError \| Error | The encountered error. | + + +* * * + diff --git a/docs/_posts/2018-08-31-router-server-router.md b/docs/_posts/2018-08-31-router-server-router.md new file mode 100644 index 00000000..303a9a0d --- /dev/null +++ b/docs/_posts/2018-08-31-router-server-router.md @@ -0,0 +1,65 @@ +--- +category: "router" +title: "ServerRouter" +--- + +## ServerRouter  +The server-side implementation of the Router interface. + +**Kind**: global class + +* [ServerRouter](#ServerRouter) + * [new ServerRouter(pageManager, factory, dispatcher, request, response)](#new_ServerRouter_new) + * [._request](#ServerRouter+_request) : Request + * [._response](#ServerRouter+_response) : Response + * [.getPath()](#ServerRouter+getPath) + * [.listen()](#ServerRouter+listen) + * [.redirect()](#ServerRouter+redirect) + + +* * * + +### new ServerRouter(pageManager, factory, dispatcher, request, response)  +Initializes the router. + + +| Param | Type | Description | +| --- | --- | --- | +| pageManager | PageManager | The current page manager. | +| factory | RouteFactory | The router factory used to create routes. | +| dispatcher | Dispatcher | Dispatcher fires events to app. | +| request | Request | The current HTTP request. | +| response | Response | The current HTTP response. | + + +* * * + +### serverRouter._request : Request  +The current HTTP request. + +**Kind**: instance property of [ServerRouter](#ServerRouter) + +* * * + +### serverRouter._response : Response  +The current HTTP response. + +**Kind**: instance property of [ServerRouter](#ServerRouter) + +* * * + +### serverRouter.getPath()  +**Kind**: instance method of [ServerRouter](#ServerRouter) + +* * * + +### serverRouter.listen()  +**Kind**: instance method of [ServerRouter](#ServerRouter) + +* * * + +### serverRouter.redirect()  +**Kind**: instance method of [ServerRouter](#ServerRouter) + +* * * + diff --git a/docs/_posts/2018-08-31-storage-cookie-storage.md b/docs/_posts/2018-08-31-storage-cookie-storage.md new file mode 100644 index 00000000..6bfbeb19 --- /dev/null +++ b/docs/_posts/2018-08-31-storage-cookie-storage.md @@ -0,0 +1,331 @@ +--- +category: "storage" +title: "CookieStorage" +--- + +## Classes + +
+
CookieStorage
+

Storage of cookies, mirroring the cookies to the current request / response +at the server side and the document.cookie property at the client +side. The storage caches the cookies internally.

+
+
+ +## Constants + +
+
MAX_EXPIRE_DATE : Date
+

Implementation note: This is the largest possible safe value that has been +tested, used to represent "infinity".

+
+
COOKIE_SEPARATOR : string
+

Separator used to separate cookie declarations in the Cookie HTTP +header or the return value of the document.cookie property.

+
+
+ +## CookieStorage  +Storage of cookies, mirroring the cookies to the current request / response +at the server side and the document.cookie property at the client +side. The storage caches the cookies internally. + +**Kind**: global class + +* [CookieStorage](#CookieStorage) + * [new CookieStorage(window, request, response)](#new_CookieStorage_new) + * [._window](#CookieStorage+_window) : Window + * [._request](#CookieStorage+_request) : Request + * [._response](#CookieStorage+_response) : Response + * [._options](#CookieStorage+_options) : Object + * [._transformFunction](#CookieStorage+_transformFunction) : Object + * [.init(options, transformFunction)](#CookieStorage+init) + * [.has()](#CookieStorage+has) + * [.get()](#CookieStorage+get) + * [.set(name, value, [options])](#CookieStorage+set) + * [.delete(name, [options])](#CookieStorage+delete) ⇒ Storage + * [.clear()](#CookieStorage+clear) + * [.keys()](#CookieStorage+keys) + * [.size()](#CookieStorage+size) + * [.getCookiesStringForCookieHeader()](#CookieStorage+getCookiesStringForCookieHeader) ⇒ string + * [.parseFromSetCookieHeader(setCookieHeader)](#CookieStorage+parseFromSetCookieHeader) + * [._parse()](#CookieStorage+_parse) + * [._firstLetterToLowerCase(word)](#CookieStorage+_firstLetterToLowerCase) ⇒ string + * [._generateCookieString(name, value, options)](#CookieStorage+_generateCookieString) ⇒ string + * [._getExpirationAsDate(expiration)](#CookieStorage+_getExpirationAsDate) ⇒ Date + * [._extractCookie(cookieString)](#CookieStorage+_extractCookie) ⇒ Object + * [._extractNameAndValue(pair, pairIndex)](#CookieStorage+_extractNameAndValue) ⇒ Array.<?(boolean\|string\|Date)> + * [._sanitizeCookieValue(value)](#CookieStorage+_sanitizeCookieValue) ⇒ string + * [._recomputeCookieMaxAgeAndExpires(options)](#CookieStorage+_recomputeCookieMaxAgeAndExpires) + + +* * * + +### new CookieStorage(window, request, response)  +Initializes the cookie storage. + + +| Param | Type | Description | +| --- | --- | --- | +| window | Window | The window utility. | +| request | Request | The current HTTP request. | +| response | Response | The current HTTP response. | + + +* * * + +### cookieStorage._window : Window  +The window utility used to determine whether the IMA is being run +at the client or at the server. + +**Kind**: instance property of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage._request : Request  +The current HTTP request. This field is used at the server side. + +**Kind**: instance property of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage._response : Response  +The current HTTP response. This field is used at the server side. + +**Kind**: instance property of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage._options : Object  +The overriding cookie attribute values. + +**Kind**: instance property of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage._transformFunction : Object  +Transform encode and decode functions for cookie value. + +**Kind**: instance property of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage.init(options, transformFunction)  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +| Param | Type | +| --- | --- | +| options | Object | +| transformFunction | Object | + + +* * * + +### cookieStorage.has()  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage.get()  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage.set(name, value, [options])  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The key identifying the storage entry. | +| value | \* | The storage entry value. | +| [options] | Object | The cookie options. The maxAge is the maximum age in seconds of the cookie before it will be deleted, the expires is an alternative to that, specifying the moment at which the cookie will be discarded. The domain and path specify the cookie's domain and path. The httpOnly and secure flags set the flags of the same name of the cookie. | + + +* * * + +### cookieStorage.delete(name, [options]) ⇒ Storage  +Deletes the cookie identified by the specified name. + +**Kind**: instance method of [CookieStorage](#CookieStorage) +**Returns**: Storage - This storage. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | Name identifying the cookie. | +| [options] | Object | The cookie options. The domain and path specify the cookie's domain and path. The httpOnly and secure flags set the flags of the same name of the cookie. | + + +* * * + +### cookieStorage.clear()  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage.keys()  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage.size()  +**Kind**: instance method of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage.getCookiesStringForCookieHeader() ⇒ string  +Returns all cookies in this storage serialized to a string compatible +with the Cookie HTTP header. + +**Kind**: instance method of [CookieStorage](#CookieStorage) +**Returns**: string - All cookies in this storage serialized to a string + compatible with the Cookie HTTP header. + +* * * + +### cookieStorage.parseFromSetCookieHeader(setCookieHeader)  +Parses cookies from the provided Set-Cookie HTTP header value. + +The parsed cookies will be set to the internal storage, and the current +HTTP response (via the Set-Cookie HTTP header) if at the server +side, or the browser (via the document.cookie property). + +**Kind**: instance method of [CookieStorage](#CookieStorage) + +| Param | Type | Description | +| --- | --- | --- | +| setCookieHeader | string | The value of the Set-Cookie HTTP header. | + + +* * * + +### cookieStorage._parse()  +Parses cookies from a cookie string and sets the parsed cookies to the +internal storage. + +The method obtains the cookie string from the request's Cookie +HTTP header when used at the server side, and the document.cookie +property at the client side. + +**Kind**: instance method of [CookieStorage](#CookieStorage) + +* * * + +### cookieStorage._firstLetterToLowerCase(word) ⇒ string  +Creates a copy of the provided word (or text) that has its first +character converted to lower case. + +**Kind**: instance method of [CookieStorage](#CookieStorage) +**Returns**: string - A copy of the provided string with its first character + converted to lower case. + +| Param | Type | Description | +| --- | --- | --- | +| word | string | The word (or any text) that should have its first character converted to lower case. | + + +* * * + +### cookieStorage._generateCookieString(name, value, options) ⇒ string  +Generates a string representing the specified cookied, usable either +with the document.cookie property or the Set-Cookie HTTP +header. + +(Note that the Cookie HTTP header uses a slightly different +syntax.) + +**Kind**: instance method of [CookieStorage](#CookieStorage) +**Returns**: string - A string representing the cookie. Setting this string + to the document.cookie property will set the cookie to + the browser's cookie storage. + +| Param | Type | Description | +| --- | --- | --- | +| name | string | The cookie name. | +| value | boolean \| number \| string | The cookie value, will be converted to string. | +| options | Object | Cookie attributes. Only the attributes listed in the type annotation of this field are supported. For documentation and full list of cookie attributes see http://tools.ietf.org/html/rfc2965#page-5 | + + +* * * + +### cookieStorage._getExpirationAsDate(expiration) ⇒ Date  +Converts the provided cookie expiration to a Date instance. + +**Kind**: instance method of [CookieStorage](#CookieStorage) +**Returns**: Date - Cookie expiration as a Date instance. + +| Param | Type | Description | +| --- | --- | --- | +| expiration | number \| string \| Date | Cookie expiration in seconds from now, or as a string compatible with the Date constructor. | + + +* * * + +### cookieStorage._extractCookie(cookieString) ⇒ Object  +Extract cookie name, value and options from cookie string. + +**Kind**: instance method of [CookieStorage](#CookieStorage) + +| Param | Type | Description | +| --- | --- | --- | +| cookieString | string | The value of the Set-Cookie HTTP header. | + + +* * * + +### cookieStorage._extractNameAndValue(pair, pairIndex) ⇒ Array.<?(boolean\|string\|Date)>  +Extract name and value for defined pair and pair index. + +**Kind**: instance method of [CookieStorage](#CookieStorage) + +| Param | Type | +| --- | --- | +| pair | string | +| pairIndex | number | + + +* * * + +### cookieStorage._sanitizeCookieValue(value) ⇒ string  +Sanitize cookie value by rules in +(@see http://tools.ietf.org/html/rfc6265#section-4r.1.1). Erase all +invalid characters from cookie value. + +**Kind**: instance method of [CookieStorage](#CookieStorage) +**Returns**: string - Sanitized value + +| Param | Type | Description | +| --- | --- | --- | +| value | string | Cookie value | + + +* * * + +### cookieStorage._recomputeCookieMaxAgeAndExpires(options)  +Recomputes cookie's attributes maxAge and expires between each other. + +**Kind**: instance method of [CookieStorage](#CookieStorage) + +| Param | Type | Description | +| --- | --- | --- | +| options | Object | Cookie attributes. Only the attributes listed in the type annotation of this field are supported. For documentation and full list of cookie attributes see http://tools.ietf.org/html/rfc2965#page-5 | + + +* * * + +## MAX_EXPIRE_DATE : Date  +Implementation note: This is the largest possible safe value that has been +tested, used to represent "infinity". + +**Kind**: global constant + +* * * + +## COOKIE_SEPARATOR : string  +Separator used to separate cookie declarations in the Cookie HTTP +header or the return value of the document.cookie property. + +**Kind**: global constant + +* * * + diff --git a/docs/_posts/2018-08-31-storage-map-storage.md b/docs/_posts/2018-08-31-storage-map-storage.md new file mode 100644 index 00000000..89a48696 --- /dev/null +++ b/docs/_posts/2018-08-31-storage-map-storage.md @@ -0,0 +1,80 @@ +--- +category: "storage" +title: "MapStorage" +--- + +## MapStorage  +Implementation of the Storage interface that relies on the +native Map for storage. + +**Kind**: global class + +* [MapStorage](#MapStorage) + * [new MapStorage()](#new_MapStorage_new) + * [._storage](#MapStorage+_storage) : Map.<string, \*> + * [.init()](#MapStorage+init) + * [.has()](#MapStorage+has) + * [.get()](#MapStorage+get) + * [.set()](#MapStorage+set) + * [.delete()](#MapStorage+delete) + * [.clear()](#MapStorage+clear) + * [.keys()](#MapStorage+keys) + * [.size()](#MapStorage+size) + + +* * * + +### new MapStorage()  +Initializes the map storage. + + +* * * + +### mapStorage._storage : Map.<string, \*>  +The internal storage of entries. + +**Kind**: instance property of [MapStorage](#MapStorage) +**Access**: protected + +* * * + +### mapStorage.init()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.has()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.get()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.set()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.delete()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.clear()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.keys()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + +### mapStorage.size()  +**Kind**: instance method of [MapStorage](#MapStorage) + +* * * + diff --git a/docs/_posts/2018-08-31-storage-session-map-storage.md b/docs/_posts/2018-08-31-storage-session-map-storage.md new file mode 100644 index 00000000..5ac28b3f --- /dev/null +++ b/docs/_posts/2018-08-31-storage-session-map-storage.md @@ -0,0 +1,94 @@ +--- +category: "storage" +title: "SessionMapStorage" +--- + +## SessionMapStorage  +The SessionMap storage is an implementation of the +Storage interface acting as a synchronization proxy between +the underlying map storage and the sessionStorage DOM storage. + +**Kind**: global class + +* [SessionMapStorage](#SessionMapStorage) + * [new SessionMapStorage(map, session)](#new_SessionMapStorage_new) + * [._map](#SessionMapStorage+_map) : MapStorage + * [._session](#SessionMapStorage+_session) : SessionStorage + * [.init()](#SessionMapStorage+init) + * [.has()](#SessionMapStorage+has) + * [.get()](#SessionMapStorage+get) + * [.set()](#SessionMapStorage+set) + * [.delete()](#SessionMapStorage+delete) + * [.clear()](#SessionMapStorage+clear) + * [.keys()](#SessionMapStorage+keys) + * [.size()](#SessionMapStorage+size) + + +* * * + +### new SessionMapStorage(map, session)  +Initializes the storage. + + +| Param | Type | Description | +| --- | --- | --- | +| map | MapStorage | The map storage to use. | +| session | SessionStorage | The session storage to use. | + + +* * * + +### sessionMapStorage._map : MapStorage  +The map storage, synced with the session storage. + +**Kind**: instance property of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage._session : SessionStorage  +The session storage, synced with the map storage. + +**Kind**: instance property of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.init()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.has()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.get()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.set()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.delete()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.clear()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.keys()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + +### sessionMapStorage.size()  +**Kind**: instance method of [SessionMapStorage](#SessionMapStorage) + +* * * + diff --git a/docs/_posts/2018-08-31-storage-session-storage.md b/docs/_posts/2018-08-31-storage-session-storage.md new file mode 100644 index 00000000..75f4c90e --- /dev/null +++ b/docs/_posts/2018-08-31-storage-session-storage.md @@ -0,0 +1,157 @@ +--- +category: "storage" +title: "SessionStorage" +--- + +## Classes + +
+
SessionStorage
+

Implementation of the Storage interface that relies on the +native sessionStorage DOM storage for storing its entries.

+
+
StorageIterator
+

Implementation of the iterator protocol and the iterable protocol for DOM +storage keys.

+
+
+ +## SessionStorage  +Implementation of the Storage interface that relies on the +native sessionStorage DOM storage for storing its entries. + +**Kind**: global class + +* [SessionStorage](#SessionStorage) + * [new SessionStorage(window)](#new_SessionStorage_new) + * [._storage](#SessionStorage+_storage) : Storage + * [.init()](#SessionStorage+init) + * [.has()](#SessionStorage+has) + * [.get()](#SessionStorage+get) + * [.set()](#SessionStorage+set) + * [.delete()](#SessionStorage+delete) + * [.clear()](#SessionStorage+clear) + * [.keys()](#SessionStorage+keys) + * [.size()](#SessionStorage+size) + * [._deleteOldestEntry()](#SessionStorage+_deleteOldestEntry) + + +* * * + +### new SessionStorage(window)  +Initializes the session storage. + + +| Param | Type | +| --- | --- | +| window | Window | + + +* * * + +### sessionStorage._storage : Storage  +The DOM storage providing the actual storage of the entries. + +**Kind**: instance property of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.init()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.has()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.get()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.set()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.delete()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.clear()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.keys()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage.size()  +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +### sessionStorage._deleteOldestEntry()  +Deletes the oldest entry in this storage. + +**Kind**: instance method of [SessionStorage](#SessionStorage) + +* * * + +## StorageIterator  +Implementation of the iterator protocol and the iterable protocol for DOM +storage keys. + +**Kind**: global class +**See**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols + +* [StorageIterator](#StorageIterator) + * [new StorageIterator(storage)](#new_StorageIterator_new) + * [._storage](#StorageIterator+_storage) : Storage + * [._currentKeyIndex](#StorageIterator+_currentKeyIndex) : number + * [.next()](#StorageIterator+next) ⇒ Object + + +* * * + +### new StorageIterator(storage)  +Initializes the DOM storage iterator. + + +| Param | Type | Description | +| --- | --- | --- | +| storage | Storage | The DOM storage to iterate through. | + + +* * * + +### storageIterator._storage : Storage  +The DOM storage being iterated. + +**Kind**: instance property of [StorageIterator](#StorageIterator) + +* * * + +### storageIterator._currentKeyIndex : number  +The current index of the DOM storage key this iterator will return +next. + +**Kind**: instance property of [StorageIterator](#StorageIterator) + +* * * + +### storageIterator.next() ⇒ Object  +Iterates to the next item. This method implements the iterator protocol. + +**Kind**: instance method of [StorageIterator](#StorageIterator) +**Returns**: Object - The next value in + the sequence and whether the iterator is done iterating through + the values. + +* * * + diff --git a/docs/_posts/2018-08-31-storage-storage.md b/docs/_posts/2018-08-31-storage-storage.md new file mode 100644 index 00000000..4e634ca1 --- /dev/null +++ b/docs/_posts/2018-08-31-storage-storage.md @@ -0,0 +1,121 @@ +--- +category: "storage" +title: "Storage" +--- + +## Storage  +**Kind**: global interface + +* [Storage](#Storage) + * [.init()](#Storage+init) ⇒ [Storage](#Storage) + * [.has(key)](#Storage+has) ⇒ boolean + * [.get(key)](#Storage+get) ⇒ \* + * [.set(key, value)](#Storage+set) ⇒ [Storage](#Storage) + * [.delete(key)](#Storage+delete) ⇒ [Storage](#Storage) + * [.clear()](#Storage+clear) ⇒ [Storage](#Storage) + * [.keys()](#Storage+keys) ⇒ Iterator.<string> + * [.size()](#Storage+size) ⇒ number + + +* * * + +### storage.init() ⇒ [Storage](#Storage)  +This method is used to finalize the initialization of the storage after +the dependencies provided through the constructor have been prepared for +use. + +This method must be invoked only once and it must be the first method +invoked on this instance. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: [Storage](#Storage) - This storage. + +* * * + +### storage.has(key) ⇒ boolean  +Returns true if the entry identified by the specified key exists +in this storage. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: boolean - true if the storage entry exists. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the storage entry. | + + +* * * + +### storage.get(key) ⇒ \*  +Retrieves the value of the entry identified by the specified . The +method returns undefined if the entry does not exists. + +Entries set to the undefined value can be tested for existence +using the has method. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: \* - The value of the storage entry. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the storage entry. | + + +* * * + +### storage.set(key, value) ⇒ [Storage](#Storage)  +Sets the storage entry identified by the specified key to the provided +value. The method creates the entry if it does not exist already. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: [Storage](#Storage) - This storage. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the storage entry. | +| value | \* | The storage entry value. | + + +* * * + +### storage.delete(key) ⇒ [Storage](#Storage)  +Deletes the entry identified by the specified key from this storage. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: [Storage](#Storage) - This storage. + +| Param | Type | Description | +| --- | --- | --- | +| key | string | The key identifying the storage entry. | + + +* * * + +### storage.clear() ⇒ [Storage](#Storage)  +Clears the storage of all entries. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: [Storage](#Storage) - This storage. + +* * * + +### storage.keys() ⇒ Iterator.<string>  +Returns an iterator for traversing the keys in this storage. The order +in which the keys are traversed is undefined. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: Iterator.<string> - An iterator for traversing the keys in this + storage. The iterator also implements the iterable protocol, + returning itself as its own iterator, allowing it to be used in + a for..of loop. + +* * * + +### storage.size() ⇒ number  +Returns the number of entries in this storage. + +**Kind**: instance method of [Storage](#Storage) +**Returns**: number - The number of entries in this storage. + +* * * + diff --git a/docs/_posts/2018-08-31-storage-weak-map-storage.md b/docs/_posts/2018-08-31-storage-weak-map-storage.md new file mode 100644 index 00000000..9efea4dd --- /dev/null +++ b/docs/_posts/2018-08-31-storage-weak-map-storage.md @@ -0,0 +1,152 @@ +--- +category: "storage" +title: "WeakMapStorage" +--- + +## Classes + +
+
WeakMapStorage
+

A specialization of the MapStorage storage mimicking the native +WeakMap using its internal garbage collector used once the size of +the storage reaches the configured threshold.

+
+
WeakRef
+

A simple reference wrapper that emulates a weak reference. We seem to have +no other option, since WeakMap and WeakSet are not enumerable (so what is +the point of WeakMap and WeakSet if you still need to manage the keys?!) and +there is no native way to create a weak reference.

+
+
+ +## WeakMapStorage  +A specialization of the MapStorage storage mimicking the native +WeakMap using its internal garbage collector used once the size of +the storage reaches the configured threshold. + +**Kind**: global class + +* [WeakMapStorage](#WeakMapStorage) + * [new WeakMapStorage(config)](#new_WeakMapStorage_new) + * [._entryTtl](#WeakMapStorage+_entryTtl) : number + * [.has()](#WeakMapStorage+has) + * [.get()](#WeakMapStorage+get) + * [.set()](#WeakMapStorage+set) + * [.delete()](#WeakMapStorage+delete) + * [.keys()](#WeakMapStorage+keys) + * [.size()](#WeakMapStorage+size) + * [._discardExpiredEntries()](#WeakMapStorage+_discardExpiredEntries) + + +* * * + +### new WeakMapStorage(config)  +Initializes the storage. + + +| Param | Type | Description | +| --- | --- | --- | +| config | Object | Weak map storage configuration. The fields have the following meaning: - entryTtl The time-to-live of a storage entry in milliseconds. | + + +* * * + +### weakMapStorage._entryTtl : number  +The time-to-live of a storage entry in milliseconds. + +**Kind**: instance property of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage.has()  +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage.get()  +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage.set()  +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage.delete()  +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage.keys()  +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage.size()  +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +### weakMapStorage._discardExpiredEntries()  +Deletes all expired entries from this storage. + +**Kind**: instance method of [WeakMapStorage](#WeakMapStorage) + +* * * + +## WeakRef  +A simple reference wrapper that emulates a weak reference. We seem to have +no other option, since WeakMap and WeakSet are not enumerable (so what is +the point of WeakMap and WeakSet if you still need to manage the keys?!) and +there is no native way to create a weak reference. + +**Kind**: global class + +* [WeakRef](#WeakRef) + * [new WeakRef(target, ttl)](#new_WeakRef_new) + * [._reference](#WeakRef+_reference) : Object + * [._expiration](#WeakRef+_expiration) : number + * [.target](#WeakRef+target) ⇒ Object + + +* * * + +### new WeakRef(target, ttl)  +Initializes the weak reference to the target reference. + + +| Param | Type | Description | +| --- | --- | --- | +| target | Object | The target reference that should be referenced by this weak reference. | +| ttl | number | The maximum number of milliseconds the weak reference should be kept. The reference will be discarded once ACCESSED after the specified timeout. | + + +* * * + +### weakRef._reference : Object  +The actual target reference, or null if the reference has +been already discarded. + +**Kind**: instance property of [WeakRef](#WeakRef) + +* * * + +### weakRef._expiration : number  +The UNIX timestamp with millisecond precision marking the moment at +or after which the reference will be discarded. + +**Kind**: instance property of [WeakRef](#WeakRef) + +* * * + +### weakRef.target ⇒ Object  +Returns the target reference, provided that the target reference is +still alive. Returns null if the reference has been discarded. + +**Kind**: instance property of [WeakRef](#WeakRef) +**Returns**: Object - The target reference, or null if the reference + has been discarded by the garbage collector. + +* * * + diff --git a/docs/_posts/2018-08-31-vendor-linker.md b/docs/_posts/2018-08-31-vendor-linker.md new file mode 100644 index 00000000..3f4928b9 --- /dev/null +++ b/docs/_posts/2018-08-31-vendor-linker.md @@ -0,0 +1,103 @@ +--- +category: "general" +title: "vendorLinker" +--- + +## VendorLinker  +Utility for linking vendor node modules with the application by exporting +them to the IMA loader's modules. + +**Kind**: global class + +* [VendorLinker](#VendorLinker) + * [new exports.VendorLinker()](#new_VendorLinker_new) + * [._modules](#VendorLinker+_modules) : Map.<string, Object.<string, \*>> + * [._plugins](#VendorLinker+_plugins) : Array.<Object.<string, \*>> + * [.set(moduleName, moduleValues)](#VendorLinker+set) + * [.get(moduleName, [imaInternalModule])](#VendorLinker+get) ⇒ Object.<string, \*> + * [.clear()](#VendorLinker+clear) ⇒ [VendorLinker](#VendorLinker) + * [.bindToNamespace(ns)](#VendorLinker+bindToNamespace) + * [.getImaPlugins()](#VendorLinker+getImaPlugins) ⇒ Array.<Object.<string, \*>> + + +* * * + +### new exports.VendorLinker()  +Initializes the vendor linker. + + +* * * + +### vendorLinker._modules : Map.<string, Object.<string, \*>>  +Internal storage of loaded modules. + +**Kind**: instance property of [VendorLinker](#VendorLinker) + +* * * + +### vendorLinker._plugins : Array.<Object.<string, \*>>  +Internal storage of loaded IMA plugins. + +**Kind**: instance property of [VendorLinker](#VendorLinker) + +* * * + +### vendorLinker.set(moduleName, moduleValues)  +Sets the provided vendor node module to the internal registry of this +vendor linker, and registers an IMA loader module of the same name, +exporting the same values. + +**Kind**: instance method of [VendorLinker](#VendorLinker) + +| Param | Type | Description | +| --- | --- | --- | +| moduleName | string | The name of the module. | +| moduleValues | Object.<string, \*> | Values exported from the module. | + + +* * * + +### vendorLinker.get(moduleName, [imaInternalModule]) ⇒ Object.<string, \*>  +Returns the provided vendor node module from the internal registry of this +vendor linker. + +**Kind**: instance method of [VendorLinker](#VendorLinker) +**Returns**: Object.<string, \*> - moduleValues Values exported from the module. + +| Param | Type | Description | +| --- | --- | --- | +| moduleName | string | The name of the module. | +| [imaInternalModule] | boolean | | + + +* * * + +### vendorLinker.clear() ⇒ [VendorLinker](#VendorLinker)  +Clears all loaded modules and plugins from this vendor linker. + +**Kind**: instance method of [VendorLinker](#VendorLinker) +**Returns**: [VendorLinker](#VendorLinker) - This vendor linker. + +* * * + +### vendorLinker.bindToNamespace(ns)  +Binds the vendor modules loaded in this vendor linker to the +Vendor sub-namespace of the provided namespace. + +**Kind**: instance method of [VendorLinker](#VendorLinker) + +| Param | Type | Description | +| --- | --- | --- | +| ns | Namespace | The namespace to which the vendor modules should be bound. | + + +* * * + +### vendorLinker.getImaPlugins() ⇒ Array.<Object.<string, \*>>  +Returns the loaded IMA plugins as an array of export objects. + +**Kind**: instance method of [VendorLinker](#VendorLinker) +**Returns**: Array.<Object.<string, \*>> - The loaded IMA plugins. + +* * * + diff --git a/docs/_posts/2018-08-31-window-client-window.md b/docs/_posts/2018-08-31-window-client-window.md new file mode 100644 index 00000000..51c21531 --- /dev/null +++ b/docs/_posts/2018-08-31-window-client-window.md @@ -0,0 +1,159 @@ +--- +category: "window" +title: "ClientWindow" +--- + +## ClientWindow  +Client-side implementation of the Window utility API. + +**Kind**: global class + +* [ClientWindow](#ClientWindow) + * [.isClient()](#ClientWindow+isClient) + * [.isCookieEnabled()](#ClientWindow+isCookieEnabled) + * [.hasSessionStorage()](#ClientWindow+hasSessionStorage) + * [.setTitle()](#ClientWindow+setTitle) + * [.getWindow()](#ClientWindow+getWindow) + * [.getDocument()](#ClientWindow+getDocument) + * [.getScrollX()](#ClientWindow+getScrollX) + * [.getScrollY()](#ClientWindow+getScrollY) + * [.scrollTo()](#ClientWindow+scrollTo) + * [.getDomain()](#ClientWindow+getDomain) + * [.getHost()](#ClientWindow+getHost) + * [.getPath()](#ClientWindow+getPath) + * [.getUrl()](#ClientWindow+getUrl) + * [.getBody()](#ClientWindow+getBody) + * [.getElementById()](#ClientWindow+getElementById) + * [.getHistoryState()](#ClientWindow+getHistoryState) + * [.querySelector()](#ClientWindow+querySelector) + * [.querySelectorAll()](#ClientWindow+querySelectorAll) + * [.redirect()](#ClientWindow+redirect) + * [.pushState()](#ClientWindow+pushState) + * [.replaceState()](#ClientWindow+replaceState) + * [.createCustomEvent()](#ClientWindow+createCustomEvent) + * [.bindEventListener()](#ClientWindow+bindEventListener) + * [.unbindEventListener()](#ClientWindow+unbindEventListener) + + +* * * + +### clientWindow.isClient()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.isCookieEnabled()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.hasSessionStorage()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.setTitle()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getWindow()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getDocument()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getScrollX()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getScrollY()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.scrollTo()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getDomain()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getHost()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getPath()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getUrl()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getBody()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getElementById()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.getHistoryState()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.querySelector()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.querySelectorAll()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.redirect()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.pushState()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.replaceState()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.createCustomEvent()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.bindEventListener()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + +### clientWindow.unbindEventListener()  +**Kind**: instance method of [ClientWindow](#ClientWindow) + +* * * + diff --git a/docs/_posts/2018-08-31-window-server-window.md b/docs/_posts/2018-08-31-window-server-window.md new file mode 100644 index 00000000..678357e3 --- /dev/null +++ b/docs/_posts/2018-08-31-window-server-window.md @@ -0,0 +1,159 @@ +--- +category: "window" +title: "ServerWindow" +--- + +## ServerWindow  +Server-side implementation of the Window utility API. + +**Kind**: global class + +* [ServerWindow](#ServerWindow) + * [.isClient()](#ServerWindow+isClient) + * [.isCookieEnabled()](#ServerWindow+isCookieEnabled) + * [.hasSessionStorage()](#ServerWindow+hasSessionStorage) + * [.setTitle()](#ServerWindow+setTitle) + * [.getWindow()](#ServerWindow+getWindow) + * [.getDocument()](#ServerWindow+getDocument) + * [.getScrollX()](#ServerWindow+getScrollX) + * [.getScrollY()](#ServerWindow+getScrollY) + * [.scrollTo()](#ServerWindow+scrollTo) + * [.getDomain()](#ServerWindow+getDomain) + * [.getHost()](#ServerWindow+getHost) + * [.getPath()](#ServerWindow+getPath) + * [.getUrl()](#ServerWindow+getUrl) + * [.getBody()](#ServerWindow+getBody) + * [.getElementById()](#ServerWindow+getElementById) + * [.getHistoryState()](#ServerWindow+getHistoryState) + * [.querySelector()](#ServerWindow+querySelector) + * [.querySelectorAll()](#ServerWindow+querySelectorAll) + * [.redirect()](#ServerWindow+redirect) + * [.pushState()](#ServerWindow+pushState) + * [.replaceState()](#ServerWindow+replaceState) + * [.createCustomEvent()](#ServerWindow+createCustomEvent) + * [.bindEventListener()](#ServerWindow+bindEventListener) + * [.unbindEventListener()](#ServerWindow+unbindEventListener) + + +* * * + +### serverWindow.isClient()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.isCookieEnabled()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.hasSessionStorage()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.setTitle()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getWindow()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getDocument()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getScrollX()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getScrollY()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.scrollTo()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getDomain()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getHost()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getPath()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getUrl()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getBody()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getElementById()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.getHistoryState()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.querySelector()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.querySelectorAll()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.redirect()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.pushState()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.replaceState()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.createCustomEvent()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.bindEventListener()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + +### serverWindow.unbindEventListener()  +**Kind**: instance method of [ServerWindow](#ServerWindow) + +* * * + diff --git a/docs/_posts/2018-08-31-window-window.md b/docs/_posts/2018-08-31-window-window.md new file mode 100644 index 00000000..f9b4da5f --- /dev/null +++ b/docs/_posts/2018-08-31-window-window.md @@ -0,0 +1,333 @@ +--- +category: "window" +title: "Window" +--- + +## Window  +**Kind**: global interface + +* [Window](#Window) + * [.isClient()](#Window+isClient) ⇒ boolean + * [.isCookieEnabled()](#Window+isCookieEnabled) ⇒ boolean + * [.hasSessionStorage()](#Window+hasSessionStorage) ⇒ boolean + * [.setTitle(title)](#Window+setTitle) + * ~~[.getWebSocket()](#Window+getWebSocket) ⇒ function~~ + * [.getWindow()](#Window+getWindow) ⇒ undefined \| [Window](#Window) + * [.getDocument()](#Window+getDocument) ⇒ undefined \| Document + * [.getScrollX()](#Window+getScrollX) ⇒ number + * [.getScrollY()](#Window+getScrollY) ⇒ number + * [.scrollTo(x, y)](#Window+scrollTo) + * [.getDomain()](#Window+getDomain) ⇒ string + * [.getHost()](#Window+getHost) ⇒ string + * [.getPath()](#Window+getPath) ⇒ string + * [.getUrl()](#Window+getUrl) ⇒ string + * [.getBody()](#Window+getBody) ⇒ undefined \| HTMLBodyElement + * [.getElementById(id)](#Window+getElementById) ⇒ HTMLElement + * [.getHistoryState()](#Window+getHistoryState) ⇒ Object + * [.querySelector(selector)](#Window+querySelector) ⇒ HTMLElement + * [.querySelectorAll(selector)](#Window+querySelectorAll) ⇒ NodeList + * [.redirect(url)](#Window+redirect) + * [.pushState(state, title, url)](#Window+pushState) + * [.replaceState(state, title, url)](#Window+replaceState) + * [.createCustomEvent(name, options)](#Window+createCustomEvent) ⇒ CustomEvent + * [.bindEventListener(eventTarget, event, listener, [useCapture])](#Window+bindEventListener) + * [.unbindEventListener(eventTarget, event, listener, [useCapture])](#Window+unbindEventListener) + + +* * * + +### window.isClient() ⇒ boolean  +Returns true if invoked at the client side. + +**Kind**: instance method of [Window](#Window) +**Returns**: boolean - true if invoked at the client side. + +* * * + +### window.isCookieEnabled() ⇒ boolean  +Returns true if the cookies are set and processed with every +HTTP request and response automatically by the environment. + +**Kind**: instance method of [Window](#Window) +**Returns**: boolean - true if cookies are handled automatically by + the environment. + +* * * + +### window.hasSessionStorage() ⇒ boolean  +Returns true if the session storage is supported. + +**Kind**: instance method of [Window](#Window) +**Returns**: boolean - true if the session storage is supported. + +* * * + +### window.setTitle(title)  +Sets the new page title of the document. + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Description | +| --- | --- | --- | +| title | string | The new page title. | + + +* * * + +### ~~window.getWebSocket() ⇒ function~~  +***Deprecated*** + +Returns the current WebSocket implementation to use. + +**Kind**: instance method of [Window](#Window) +**Returns**: function - The current WebSocket + implementation. + +* * * + +### window.getWindow() ⇒ undefined \| [Window](#Window)  +Returns the native window object representing the global context +at the client-side. The method returns undefined if used at the +server-side. + +**Kind**: instance method of [Window](#Window) +**Returns**: undefined \| [Window](#Window) - The window object at the + client-side, or undefined at the server-side. + +* * * + +### window.getDocument() ⇒ undefined \| Document  +Returns the native document object representing any web page loaded +in the browser and serves as an entry point into the web page's content +which is the DOM tree at the client-side. The method returns undefined +if used at the server-side. + +**Kind**: instance method of [Window](#Window) +**Returns**: undefined \| Document - The document object at the + client-side, or undefined at the server-side. + +* * * + +### window.getScrollX() ⇒ number  +Returns the number of pixels the viewport is scrolled horizontally. + +**Kind**: instance method of [Window](#Window) +**Returns**: number - The number of pixels the viewport is scrolled + horizontally. + +* * * + +### window.getScrollY() ⇒ number  +Returns the number of pixels the document is scrolled vertically. + +**Kind**: instance method of [Window](#Window) +**Returns**: number - The number of pixels the document is scrolled + vertically. + +* * * + +### window.scrollTo(x, y)  +Scrolls the viewport to the specified location (if possible). + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Description | +| --- | --- | --- | +| x | number | Horizontal scroll offset in pixels. | +| y | number | Vertical scroll offset in pixels. | + + +* * * + +### window.getDomain() ⇒ string  +Returns the domain of the current document's URL as +`${protocol://${host}`}. + +**Kind**: instance method of [Window](#Window) +**Returns**: string - The current domain. + +* * * + +### window.getHost() ⇒ string  +Returns the application's host. + +**Kind**: instance method of [Window](#Window) +**Returns**: string - The current host. + +* * * + +### window.getPath() ⇒ string  +Returns the path part of the current URL, including the query string. + +**Kind**: instance method of [Window](#Window) +**Returns**: string - The path and query string parts of the current URL. + +* * * + +### window.getUrl() ⇒ string  +Returns the current document's URL. + +**Kind**: instance method of [Window](#Window) +**Returns**: string - The current document's URL. + +* * * + +### window.getBody() ⇒ undefined \| HTMLBodyElement  +Returns the document's body element. The method returns +undefined if invoked at the server-side. + +**Kind**: instance method of [Window](#Window) +**Returns**: undefined \| HTMLBodyElement - The document's body element, or + undefined if invoked at the server side. + +* * * + +### window.getElementById(id) ⇒ HTMLElement  +Returns the HTML element with the specified id attribute value. + +**Kind**: instance method of [Window](#Window) +**Returns**: HTMLElement - The element with the specified id, or + null if no such element exists. + +| Param | Type | Description | +| --- | --- | --- | +| id | string | The value of the id attribute to look for. | + + +* * * + +### window.getHistoryState() ⇒ Object  +Returns the history state. + +**Kind**: instance method of [Window](#Window) +**Returns**: Object - The current history state + +* * * + +### window.querySelector(selector) ⇒ HTMLElement  +Returns the first element matching the specified CSS 3 selector. + +**Kind**: instance method of [Window](#Window) +**Returns**: HTMLElement - The first element matching the CSS selector or + null if no such element exists. + +| Param | Type | Description | +| --- | --- | --- | +| selector | string | The CSS selector. | + + +* * * + +### window.querySelectorAll(selector) ⇒ NodeList  +Returns a node list of all elements matching the specified CSS 3 +selector. + +**Kind**: instance method of [Window](#Window) +**Returns**: NodeList - A node list containing all elements matching the + specified CSS selector. + +| Param | Type | Description | +| --- | --- | --- | +| selector | string | The CSS selector. | + + +* * * + +### window.redirect(url)  +Performs a hard redirect (discarding the current JavaScript state) to +the specified URL. + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to which the browser will be redirected. | + + +* * * + +### window.pushState(state, title, url)  +Pushes a new state to the browser history. The method has no effect if +the current browser does not support the history API (IE9). + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Description | +| --- | --- | --- | +| state | Object.<string, \*> | A state object associated with the history item, preferably representing the page state. | +| title | string | The page title related to the state. Note that this parameter is ignored by some browsers. | +| url | string | The new URL at which the state is available. | + + +* * * + +### window.replaceState(state, title, url)  +Replaces the current history entry. The method has no effect if the +current browser does not support the history API (IE9). + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Description | +| --- | --- | --- | +| state | Object.<string, \*> | A state object associated with the history item, preferably representing the page state. | +| title | string | The page title related to the state. Note that this parameter is ignored by some browsers. | +| url | string | The new URL at which the state is available. | + + +* * * + +### window.createCustomEvent(name, options) ⇒ CustomEvent  +Create new instance of CustomEvent of the specified name and using the +provided options. + +**Kind**: instance method of [Window](#Window) +**Returns**: CustomEvent - The created custom event. +**See**: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent + +| Param | Type | Description | +| --- | --- | --- | +| name | string | Custom event's name (sometimes referred to as the event's type). | +| options | Object.<string, \*> | The custom event's options. | + + +* * * + +### window.bindEventListener(eventTarget, event, listener, [useCapture])  +Registers the provided event listener to be executed when the specified +event occurs on the specified event target. + +Registering the same event listener for the same event on the same event +target with the same useCapture flag value repeatedly has no +effect. + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| eventTarget | EventTarget | | The event target. | +| event | string | | The name of the event. | +| listener | function | | The event listener. | +| [useCapture] | boolean | false | If true, the method initiates event capture. After initiating capture, all events of the specified type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree. Events which are bubbling upward through the tree will not trigger a listener designated to use capture. | + + +* * * + +### window.unbindEventListener(eventTarget, event, listener, [useCapture])  +Deregisters the provided event listener, so it will no longer we +executed when the specified event occurs on the specified event target. + +The method has no effect if the provided event listener is not +registered to be executed at the specified event. + +**Kind**: instance method of [Window](#Window) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| eventTarget | EventTarget | | The event target. | +| event | string | | The name of the event. | +| listener | function | | The event listener. | +| [useCapture] | boolean | false | The useCapture flag value that was used when the listener was registered. | + + +* * * +