Markdown documentation added

peppierre · peppierre · commit 080688c1c99e · 2017-04-26T21:25:21.000+02:00
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,15 @@
+# Globular
+
+Globular is a feature-based, view-agnostic framework written in ECMAScript 2015 (aka ECMAScript 6). Main goal of it to provide an easy way to separate application's business logic and view, by organizing application functionalities into features at the highest level and by making view to be pluggable into these features.
+
+[Objects in Globular](objects/README.md)
+
+[Interface Definitions](interface/README.md)
+
+[Installation and usage](installation/README.md)
+
+## Changelog
+
+* 0.1.0
+    1. ability to create Globular apps and extend it by features
+    1. globular.Api class to provide pluginable API adapter solution for applications
diff --git a/docs/installation/README.md b/docs/installation/README.md
@@ -0,0 +1,35 @@
+## Installation and usage
+
+[Index](/docs/README.md) | Installation and usage
+
+To install, type following command in terminal:
+
+    npm install globular --save
+
+After package is installed, you can refer to it in your application as follows:
+
+    class DoImportantThingCore {
+        execute(data) {
+           // TODO: implement functionality
+        }
+    }
+    
+    const myApplication = globular.initializeApp('my-app');
+    myApplication.extendWithFeature('do-important-thing', DoImportantThingCore);
+    myApplication.executeFeature('do-important-thing', { 'prop1':'value1', 'prop2':2 });
+    
+If you need nothing more but an API adapter to use in your exsisting application, just make it happen as follows:
+
+    const myApi = new globular.Api();
+    
+    myApi.pluginCall('get-current-location', () => ({
+        type: 'xhr',
+        config: {
+            url: '/api/get-location',
+            method: 'get'
+        }
+    }));
+    
+    ...
+    
+    let currentLocation = myApi.request('get-current-location').then((data) => data);
diff --git a/docs/interface/README.md b/docs/interface/README.md
@@ -0,0 +1,13 @@
+# Interface definitions
+
+[Index](/docs/README.md) | Interface definitions
+
+[Feature Core interface](feature-core/README.md)
+
+[Persistency Adapter interface](persistency-adapter/README.md)
+
+[API Adapter interface](api-adapter/README.md)
+
+[API Request function](api-request/README.md)
+
+[View function](view/README.md)
diff --git a/docs/interface/api-adapter/README.md b/docs/interface/api-adapter/README.md
@@ -0,0 +1,21 @@
+## API Adapter interface
+
+[Index](/docs/README.md) | [Interface definitions](/docs/interface/README.md) | API Adapter interface
+
+API Adapter interface is a common way to make API plugginable to applications. When initializing an application, you could define which adapter you prefer to use.
+
+### Criteria against
+
+1. Adapter must have `pluginCall` and `request` methods implemented.
+
+**Example**
+
+    class MyApiAdapter {
+        pluginCall() {}
+        
+        request(data) {
+            return JSON.stringify(data);
+        }
+    }
+
+*Note that [globular.Api](/docs/objects/framework/api/README.md) implements this interface. Please check section for specialties.*
diff --git a/docs/interface/api-request/README.md b/docs/interface/api-request/README.md
@@ -0,0 +1,34 @@
+## API Request function
+
+[Index](/docs/README.md) | [Interface definitions](/docs/interface/README.md) | API Request function
+
+API request function is for providing a API call configuration for built-in [API Adapter class](/docs/objects/framework/api) instance based on input parameter. When a feature calls API, API Adapter queries relevant call configuration and run request against API based on configuration.
+
+### Criteria against
+
+Function must return an object with following high-level properties defined:
+
+`type`
+
+String value to define how to handle request. Currently only `'xhr'` type is supported.
+
+`config`
+
+Configuration object, required properties depends on request type specified by `type` property. In case of `type: 'xhr'`, following properties are used:
+
+* `config.method`: HTTP method to use
+* `config.url`: requested URL
+* `config.headers`: key-value pairs of HTTP headers
+* `config.body`: HTTP body
+
+**Example**
+
+    (data) => ({
+        type: 'xhr',
+        config: {
+            url: '/api/book-table',
+            method: 'post',
+            headers: { 'Allow-Origin': '*' },
+            body: JSON.stringify(data),
+        }
+    })
diff --git a/docs/interface/feature-core/README.md b/docs/interface/feature-core/README.md
@@ -0,0 +1,25 @@
+## Feature Core class
+
+[Index](/docs/README.md) | [Interface definitions](/docs/interface/README.md) | Feature Core class
+
+Feature Core class implements application's business logic.
+
+### Criteria against
+
+1. Feature Core must have `execute` methods implemented.
+1. If it requires persistency and/or API, constructor must be declared as follows: `constructor({ persistency, api })`
+
+**Example**
+
+    class CreateOrder {
+        constructor({ persistency, api }) {
+            this.persistency = persistency;
+            this.api = api;
+        }
+        
+        execute(data) {
+            const apiKey = this.persistency.getItem('api-key');
+            return this.api.request('create-order', { apiKey, orderName: data.name })
+                .then(result => result);
+        }
+    }
diff --git a/docs/interface/persistency-adapter/README.md b/docs/interface/persistency-adapter/README.md
@@ -0,0 +1,30 @@
+## Persistency Adapter interface
+
+[Index](/docs/README.md) | [Interface definitions](/docs/interface/README.md) | Persistency Adapter interface
+
+Persistency Adapter interface provides a way to build-up a persistency-agnostic application. This interface only defines a few set of methods an Adapter instance must implement and [Feature Core](/docs/interface/feature-core/README.md) must use. These methods are:
+
+1. `getItem(key)`
+1. `setItem(key, value)`
+1. `removeItem()`
+1. `clear()`
+
+As you may notice, these set of methods is a subset of [Storage interface](http://www/w3.org/TR/webstorage/#the-storage-interface) API which let e.g. browser's localStorage object to be injected into applications.
+
+**Example**
+
+    const myApplication = globular.initializeApp('calculator', { persistency:localStorage });
+    
+    class FetchWeatherHere {
+        constructor({ persistency }) {
+            this.persistency = persistency;
+        }
+        
+        execute(data) {
+            const cityCode = this.persistency.getItem('current-location');
+            
+            // do some stuff here
+        }
+    }
+    
+    myApplication.extendWithFeature('fetch-weather-here', FetchWeatherHere);
diff --git a/docs/interface/view/README.md b/docs/interface/view/README.md
@@ -0,0 +1,13 @@
+## View function
+
+[Index](/docs/README.md) | [Interface definitions](/docs/interface/README.md) | View function
+
+View function is a callback added to [Feature](/docs/objects/feature/README.md). When feature executes, generated view-model is passed to each plugged-in view to handle.
+
+*Please note that there is no restriction about what will be passed to this function after feature executed. View-model would be a simple string or an object, relevant feature must determine what kind of view-model is generated.*
+
+**Example**
+
+    data => {
+        document.querySelector('#indicator').innerText = data.label;
+    }
diff --git a/docs/objects/README.md b/docs/objects/README.md
@@ -0,0 +1,9 @@
+# Objects in Globular
+
+[Index](/docs/README.md) | Objects in Globular
+
+[Framework](framework/README.md)
+
+[Application](application/README.md)
+
+[Feature](feature/README.md)
diff --git a/docs/objects/application/README.md b/docs/objects/application/README.md
@@ -0,0 +1,13 @@
+## Application
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | Application
+
+Application object provides ability work with features of application. This includes extending application with a feature, as well as executing a feature.
+
+[getFeature()](get-feature/README.md)
+
+[getFeatures()](get-features/README.md)
+
+[extendWithFeature()](extend-with-feature/README.md)
+
+[executeFeature()](execute-feature/README.md)
diff --git a/docs/objects/application/execute-feature/README.md b/docs/objects/application/execute-feature/README.md
@@ -0,0 +1,25 @@
+### executeFeature()
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | [Application](/docs/objects/application/README.md) | executeFeature()
+
+Executes a feature of application. This method is a syntax sugar around [execute](/docs/objects/feature/execute/README.md) method of [Feature](/docs/objects/feature/README.md) object.
+
+If no feature is available with given name, no execution occur.
+
+**Signature**
+
+    executeFeature(featureName, model)
+
+**Parameters**
+
+`featureName`
+
+*(mandatory)* String ID of feature required.
+
+`model`
+
+*(optional)* Any type of data, which is necessary for feature to do its job.
+
+**Example**
+
+    const sumNumbers = myApplication.executeFeature('sum-numbers', [23, 97, 11]);
diff --git a/docs/objects/application/extend-with-feature/README.md b/docs/objects/application/extend-with-feature/README.md
@@ -0,0 +1,33 @@
+### extendWithFeature()
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | [Application](/docs/objects/application/README.md) | extendWithFeature()
+
+Extends application's functionality with a feature.
+
+**Signature**
+
+    myApplication.extendWithFeature(featureName, featureCore)
+    
+**Parameters**
+
+`featureName`
+
+*(mandatory)* String identifier to uniquely identify feature.
+
+`featureCore`
+
+*(mandatory)* A class which implements business object of feature. For details about interface requirement, check [Feature Core class](/docs/interface/feature-core/README.md) section.
+
+**Return value**
+
+For chaining purpose, this method returns newly added feature object. For further information about object returned, please check [Feature](/docs/objects/feature/README.md) section.
+
+**Example**
+
+    class ReserveRoom {
+        execute() {
+            // to some stuffs
+        }
+    }
+    
+    myApplication.extendWithFeature('reserve-room', ReserveRoom);
diff --git a/docs/objects/application/get-feature/README.md b/docs/objects/application/get-feature/README.md
@@ -0,0 +1,24 @@
+### getFeature()
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | [Application](/docs/objects/application/README.md) | getFeature()
+
+Returns a feature of application.
+
+**Signature**
+
+    myAppl.getFeature(featureName)
+
+**Parameters**
+
+`featureName`
+
+*(mandatory)* String ID of feature required.
+
+**Return value**
+
+A feature object or -if no feature available with given ID- `undefined`. For further information, please check [Feature](/docs/objects/feature/README.md) section.
+
+**Example**
+
+    const myFeature = myApplication.getFeature('check-humidity-for-location')
+    
diff --git a/docs/objects/application/get-features/README.md b/docs/objects/application/get-features/README.md
@@ -0,0 +1,21 @@
+### getFeatures()
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | [Application](/docs/objects/application/README.md) | getFeatures()
+
+Returns IDs of application's available features.
+
+**Signature**
+
+    myApp.getFeatures()
+
+**Return value**
+
+Array containing string IDs of features.
+
+**Example**
+
+    const featureList = myApp.getFeatures();
+    if (featureList.indexOf('check-wind-condictions') < 0) {
+        throw new Error('Missing feature: Check Wind Conditions');
+    }
+
diff --git a/docs/objects/feature/README.md b/docs/objects/feature/README.md
@@ -0,0 +1,9 @@
+## Feature
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | Feature
+
+Feature is an essence in Globular ecosystem. Technically it is a wrapper around an instance of [Feature Core class](/docs/interface/feature-core/README.md) to provide separation of business logic and views. 
+
+[execute()](execute/README.md)
+
+[pluginView()](plugin-view/README.md)
diff --git a/docs/objects/feature/execute/README.md b/docs/objects/feature/execute/README.md
@@ -0,0 +1,23 @@
+### execute()
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | [Feature](/docs/objects/feature/README.md) | execute()
+
+Executes a feature by passing a model directly to [Feature Core class](/docs/interface/feature-core/README.md) instance wrapped by feature.
+
+**Signature**
+
+    execute(model)
+
+**Parameters**
+
+`model`
+
+*(optional)* Any type of data, which is necessary for feature to do its job.
+
+**Example**
+
+    const sumNumbers = myApplication.getFeature('sum-numbers');
+    sumNumbers.execute([23, 97, 11]);
+
+    const capitalizeName = myApplication.getFeature('capitalize-name');
+    capitalizeName.execute('peter abraham');
diff --git a/docs/objects/feature/plugin-view/README.md b/docs/objects/feature/plugin-view/README.md
@@ -0,0 +1,31 @@
+### pluginView()
+
+[Index](/docs/README.md) | [Objects in Globular](/docs/objects/README.md) | [Feature](/docs/objects/feature/README.md) | pluginView()
+
+Adds a new view to list of views. Each views in this list is going to be notified when [Feature](/docs/objects/feature/README.md) is [executed](/docs/objects/feature/execute/README.md).
+
+**Signature**
+
+    pluginView(view)
+
+**Parameters**
+
+`view`
+
+*(mandatory)* A function which is called with result of feature when it is executed. For required signature, please check [View function](/docs/interface/view/README.md).
+
+**Return value**
+
+For chaining purpose, this method returns [Feature](/docs/objects/feature/README.md) itself.
+
+**Example**
+
+    function updateOperation(data) {
+        // do stuffs in DOM
+    }
+    
+    function updateResult(data) {
+        // do stuffs in DOM
+    }
+    
+    myFeature.pluginView(updateOperation).pluginView(updateResult);
diff --git a/docs/objects/framework/README.md b/docs/objects/framework/README.md
diff --git a/docs/objects/framework/api/README.md b/docs/objects/framework/api/README.md
diff --git a/docs/objects/framework/app/README.md b/docs/objects/framework/app/README.md
diff --git a/docs/objects/framework/initialize-app/README.md b/docs/objects/framework/initialize-app/README.md
