Updated documentation

* Updated documentation
  * Included epics
  * Add a migration guide
  * updated out-of-date references
* Fixed build of docma (now deploys in the mapstore.war)

build.sh

@@ -3,8 +3,9 @@ set -e
 
 npm install
 npm run compile
+npm run cleandoc
 npm run lint
-npm run doc
 npm test
+npm run doc
 mvn clean install
 npm run cleandoc

docs/developer-guide/building-and-developing.md

@@ -1,4 +1,8 @@
-Due to the dual nature of the project (Java backend and Javascript frontend) building and developing using the MapStore 2 framework requires two distinct set of tools, [Apache Maven](https://maven.apache.org/) for Java and [NPM](https://www.npmjs.com/) for Javascript.
+#Building and developing
+
+Due to the dual nature of the project (Java backend and Javascript frontend) building and developing using the MapStore 2 framework requires two distinct set of tools
+ * [Apache Maven](https://maven.apache.org/) for Java
+ * [NPM](https://www.npmjs.com/) for Javascript.
 
 A basic knowledge of both tools is required.
 

docs/developer-guide/contributing-guidelines.md

@@ -4,7 +4,7 @@ Your pull request must:
 
  * Follow MapStore 2's coding style.
 
- * The new components have to be tested. 
+ * The new components have to be tested.
 
  * Pass the integration tests run automatically by the Travis Continuous
    Integration system.
@@ -19,25 +19,9 @@ Your pull request must:
  * Be possible to merge automatically.
 
 
-### The `test` and `lint` build targets
-
-It is strongly recommended that you run
-
-    $ npm test
-
-    $ npm run lint
-
-before every commit.  This will catch many problems quickly, and it is much
-faster than waiting for the Travis CI integration tests to run.
-
-The `test` build target runs a number of quick tests on your code.  
-
-The `lint` build target runs ESLint checks on your code.  
-
-
 ### Follow MapStore 2's coding style
 
-MapStore 2 follows a strict coding style, enforced by [ESLint](http://eslint.org/) rules. 
+MapStore 2 follows a strict coding style, enforced by [ESLint](http://eslint.org/) rules.
 
 The set of used rules can be found in the [.eslintrc](https://github.com/geosolutions-it/MapStore2/blob/master/.eslintrc) file, in the root folder of the project.
 
@@ -51,7 +35,7 @@ In addition, take care of adding the standard file header in each javascript / c
 This is the standard file header:
 
 ```
-/**
+/*
  * Copyright <year>, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -60,6 +44,17 @@ This is the standard file header:
  */
 ```
 
+### The components have to be tested
+
+It is strongly recommended that you run
+
+    $ npm test
+
+before every commit.  This will catch many problems quickly, and it is much
+faster than waiting for the Travis CI integration tests to run.
+
+The `test` build target runs a number of quick tests on your code.  
+
 ### Configure your editor
 
 If possible, configure your editor to follow the coding conventions of the
@@ -129,4 +124,4 @@ Please keep the header line short, no more than 50 characters.
 Occasionally other changes to `master` might mean that your pull request cannot
 be merged automatically.  In this case you may need to rebase your branch on a
 more recent `master`, resolve any conflicts, and `git push --force` to update
-your branch so that it can be merged automatically.
+your branch so that it can be merged automatically.

docs/developer-guide/developing-with-mapstore-2.md

@@ -15,7 +15,6 @@ This is the overall framework folder structure:
 +-- .editorconfig
 +-- .travis.yml
 +-- ...
-+-- geostore (submodule)
 +-- web      (MapStore2 maven module)
     +-- pom.xml
     +-- src        (maven java webapp src folder)
@@ -27,16 +26,17 @@ This is the overall framework folder structure:
     |        +-- java
     |        +-- resources   
     +-- client
-    |   +-- index.html (demo application home page) 
+    |   +-- index.html (demo application home page)
         +-- plugins (ReactJS smart components with required reducers)
         +-- components (ReactJS dumb components)
         |   +-- category
         |   |   +-- <component>.jsx (ReactJS component)
         |   |   +-- ...
         |   |   +-- __tests__       (unit tests folder)
-        |   |       +-- <component>-test.jsx 
+        |   |       +-- <component>-test.jsx
         |   +-- ...
         +-- actions    (Redux actions)
+        +-- epics      (redux-observable epics)
         +-- reducers   (Redux reducers)
         +-- stores     (Redux stores)
         +-- translations (i18n localization files)
@@ -66,4 +66,4 @@ If you want to create an application based on MapStore2 you can use the [Project
 
 If you want to learn how to develop a simple MapStore2 based application you can follow the [tutorial](application-tutorial)
 
-If you want to learn how to develop a plugins based MapStore2 based application you can follow the [plugins tutorial](plugins-architecture#building-an-application-using-plugins)
+If you want to learn how to develop a plug-in based MapStore2 based application you can follow the [plugins tutorial](plugins-architecture#building-an-application-using-plugins)

docs/developer-guide/index.md

@@ -6,7 +6,7 @@ Clone the repository with the --recursive option to automatically clone submodul
 
 Install NodeJS >= 4.6.1 , if needed, from [here](https://nodejs.org/en/download/releases/).
 
-Update npm to 3.x, using: 
+Update npm to 3.x, using:
 
 `npm install -g npm@3`
 
@@ -33,3 +33,4 @@ Deploy the generated mapstore.war file (in web/target) to your favourite J2EE co
  * [Building and deploying](building-and-developing)
  * [Developing with MapStore 2](developing-with-mapstore-2-intro)
  * [Configuration](configuration-files)
+ * [Migration](mapstore-migration-guide)

docs/developer-guide/infrastructure-and-general-architecture.md

@@ -9,15 +9,14 @@ The backend is a suite of web services, developed in Java and deployed into a J2
 
 The frontend is based on the [ReactJS](https://facebook.github.io/react/) library and the [Redux](http://rackt.github.io/redux/) architecture, which is a specific implementation of the [Flux](http://facebook.github.io/flux/) architecture.
 
-![Flux infrastructure](https://facebook.github.io/flux/img/flux-simple-f8-diagram-with-client-action-1300w.png)
+<img src="https://facebook.github.io/flux/img/flux-simple-f8-diagram-with-client-action-1300w.png" style="max-width:500px" alt="Flux infrastructure" />
 
 It allows plugging different mapping libraries (with **Leaflet** and **OpenLayers 3** as our first implementation targets) abstracting libraries implementation details using ReactJS _web components_ and _actions based communication_.
 
 ![MapStore 2 - Frontend](https://docs.google.com/drawings/d/1k8Qja6ZFeOpoW3WqbZJvU3f7PvKpL-oTGq0vErQng44/pub?w=480&h=360)
 
-## Technologies
+## Frontend Technologies
  * [ReactJS and Redux introduction](reactjs-and-redux-introduction)
- * [ReactJS 0.14.x](react-0.14.x-migration-guide)
 
 # Backend
 
@@ -27,4 +26,4 @@ Backend services include at least (but not only) these ones:
  * **Configuration** services, to allow full application(s) and services configurability
  * **Security** with the ability to configure authentication using an internal or external service, and a flexible authorization policy for services and resources access
 
-![MapStore 2 - Backend](https://docs.google.com/drawings/d/12SURY5tdrjOXwYx0kH1LHUmHogZpWvmcEoFCGJOgJWY/pub?w=480&h=360)
+![MapStore 2 - Backend](https://docs.google.com/drawings/d/12SURY5tdrjOXwYx0kH1LHUmHogZpWvmcEoFCGJOgJWY/pub?w=480&h=360)

docs/developer-guide/mapstore-migration-guide.md

@@ -0,0 +1,54 @@
+# Migration from 2017.01.00 to 2017.02.00
+The version 2017.02.00 has many improvements and changes:
+  * introduced `redux-observable`
+  * updated `webpack` to version 2
+  * updated `react-intl` to version 2.x
+  * updated `react` to [version 15.4.2] (https://facebook.github.io/react/blog/2016/04/07/react-v15.html)
+  * updated `react-bootstrap` to version 0.30.7
+
+
+We suggest you to:
+ * align your package.json with the latest version of 2017.02.00.
+ * update your webpack files (see below).
+ * update your tests to react 15 version. [see upgrade guide](https://facebook.github.io/react/blog/2016/04/07/react-v15.html#upgrade-guide)
+ * Update your `react-bootstrap` custom components with the new one (see below).
+
+## Side Effect Management - Introduced redux-observable
+To manage complex asynchronous operations the thunk middleware is not enough.
+When we started with MapStore 2 there was no alternative to thunk. Now we have some options. After a spike (results available [here](https://github.com/geosolutions-it/MapStore2/issues/1420)) we chose to use redux-observable.
+For the future, we strongly recommend to use this library to perform asynchronous tasks.
+
+Introducing this library will allow to :
+ * remove business logic from the components event handlers
+ * now all new  `actionCreators` should return pure actions. All async stuff will be deferred to the epics.
+ * avoid bouncing between components and state to trigger side effect
+ * speed up development with `rxjs` functionalities
+ * Existing thunk integration will be maintained since all the thunks will be replaced.
+
+If you are using the Plugin system and the StandardStore, you may have only to include the missing new dependencies in your package.json (redux-observable and an updated version of redux).
+
+Check the current package.json to get he most recent versions. For testing we included also redux-mockup-store as a dependency, but you are free to test your epics as you want.
+
+For more complex integrations check [this](https://github.com/geosolutions-it/MapStore2/pull/1471) pull request to see how to integrate redux-observable or follow the guide on the [redux-observable site](https://redux-observable.js.org/).
+
+## Webpack update to version 2
+We updated webpack (old one is deprecated), check [this pull request](https://github.com/geosolutions-it/MapStore2/pull/1491) to find out how to update your webpack files.
+here a list of what we had to update:
+ * module.loaders are now module.rules
+ * update your package.json with latest versions of webpack, webpack plugins and karma libs and integrations (Take a look to the changes on package.json in the pull request if you want a detailed list of what to update in this case).
+ * change your test proxy configuration with the new one.
+
+More details on the [webpack site](https://webpack.js.org/guides/migrating/).
+
+
+## react-intl update to  2.x
+See [this pull request](https://github.com/geosolutions-it/MapStore2/pull/1495/files) for the details. You should only have to update your package.json
+
+## react update to 15.4.2
+Check this pull request to see how to:
+* update your package.json
+* update your tests
+
+## React Bootstrap update
+The version we are using is not documented anymore, and not too much compatible with react 15 (too many warnings). So this update can not be postponed anymore.
+The bigger change in this case is that the Input component do not exists anymore. You will have to replace all your Input with the proper components, and update the `package.json`. See [this pull request](https://github.com/geosolutions-it/MapStore2/pull/1511) for details.

docs/developer-guide/reactjs-and-redux-introduction.md

@@ -1,5 +1,10 @@
-# ReactJS
-[ReactJS](https://facebook.github.io/react/index.html) 0.14.x is used to develop MapStore2. The main purpose of ReactJS is to allow writing the **View** of the application, through the composition of _small components_, in a _declarative way_.
+# Main Frontend Tecnologies
+The main tecnologies used on the mapstore 2 are:
+ * ReactJS (View)
+ * Redux (state management)
+
+## ReactJS
+[ReactJS](https://facebook.github.io/react/index.html) 0.15.x is used to develop MapStore2. The main purpose of ReactJS is to allow writing the **View** of the application, through the composition of _small components_, in a _declarative way_.
 
 Components are written using a "templating" language, called [**JSX**](https://react-bootstrap.github.io/introduction.html), that is a sort of composition of HTML and Javascript code. The difference between JSX and older approaches like _JSP_ is that JSX templates are mixed with Javascript code inside javascript files.
 
@@ -18,7 +23,7 @@ Component usage:
 ```javascript
 React.render(<MyComponent title="My title"/>, document.body);
 ```
-## Properties, State and Event handlers
+### Properties, State and Event handlers
 Components can define and use **properties**, like the title one used in the example. These are immutable, and cannot be changed by component's code.
 
 Components can also use **state** that can change. When the state changes, the component is updated (re-rendered) automatically.
@@ -40,9 +45,9 @@ const MyComponent = React.createClass({
    }
 });
 ```
-In this example, the initial state includes a title property whose value is CHANGE_ME.
+In this example, the initial state includes a title property whose value is `CHANGE_ME`.
 
-When the h1 element is clicked, the state is changed so that title becomes CHANGED.
+When the h1 element is clicked, the state is changed so that title becomes `CHANGED`.
 
 The HTML page is automatically updated by ReactJS, each time the state changes (each time this.setState is called). For this reason we say that JSX allows to declaratively describe the View for each possible application state.
 
@@ -108,6 +113,7 @@ function reducer(state = {title: "CHANGE_ME"}, action) {
     }
 }
 ```
+
 ## Store
 The redux store combines different reducers to produce a global state, with a slice for each used reducer.
 
@@ -132,7 +138,61 @@ You can subscribe to the store, to be notified whenever the state changes.
 ```javascript
 store.subscribe(function handleChange() {});
 ```
-## Redux and ReactJS integration
+
+## Redux Middlewares
+Redux data flow is synchronous. To provide asynchronous functionalities (e.g. Ajax) redux needs a [middleware](http://redux.js.org/docs/advanced/Middleware.html). Actually MapStore 2 uses 2 middlewares for this purpose:
+ * Redux thunk (going to be fully replaced by redux-observable)
+ * Redux Observable
+
+### Redux thunk
+This middleware allows to perform simple asynchronous flows by returning a function from the action creator (instead of a action object).
+
+```javascript
+// action creator
+function changeTitleAsync() {
+    return (dispatch, getState) => {
+        myAsyncPromise.then( (newTitle) => {
+            dispatch({
+                type: CHANGE_TITLE,
+                title: newTitle
+            };)
+        });
+    }
+}
+```
+
+This middleware is there from the beginning of the MapStore 2 history. During the years, some better middlewares have been developed for this purpose. We want to replace it in the future with redux-observable.
+
+### Redux Observable and epics
+This middleware provides support for side-effects in MapStore 2 using rxjs. The core object of this middleware is the `epic`
+
+```javascript
+function (action$: Observable<Action>, store: Store): Observable<Action>;
+```
+
+The epic is a function that simply gets as first parameter an `Observable` (stream) emitting the actions emitted by redux. It returns another `Observable` (stream) that emits actions that will be forwarded to redux too.
+
+So there are 2 streams:
+ * Actions in
+ * Actions out
+
+A simple epic example can be the following:
+
+```javascript
+const pingEpic = action$ =>
+  action$.filter(action => action.type === 'PING')
+    .mapTo({ type: 'PONG' });
+```
+Every time a 'PING' action is emitted, the epic will emit also the 'PONG' action.
+
+See :
+ * [Introduction to RxJS for MapStore Developers](https://docs.google.com/presentation/d/1Ts-yZGc12VMr9oG8xMqwptUmMjdsKI2uZh4Mr5shYhA/edit?usp=sharing)
+ * [redux-observable site](https://redux-observable.js.org/)
+ * [rxjs Observable](http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html) as a reference for methods
+ * [setting up the middleware](https://redux-observable.js.org/docs/basics/SettingUpTheMiddleware.html) to integrate epics with your store
+
+
+# Redux and ReactJS integration
 The **react-redux** library can be used to connect the Redux application state to ReactJS components.
 
 This can be done in the following way: