diff --git a/build.sh b/build.sh index 85574be661..d0bf047364 100755 --- a/build.sh +++ b/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 diff --git a/docs/developer-guide/building-and-developing.md b/docs/developer-guide/building-and-developing.md index 7f81a0a430..c41b66ebe7 100644 --- a/docs/developer-guide/building-and-developing.md +++ b/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. diff --git a/docs/developer-guide/contributing-guidelines.md b/docs/developer-guide/contributing-guidelines.md index 93155fb1af..0f9f72e002 100644 --- a/docs/developer-guide/contributing-guidelines.md +++ b/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 , 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. \ No newline at end of file +your branch so that it can be merged automatically. diff --git a/docs/developer-guide/developing-with-mapstore-2.md b/docs/developer-guide/developing-with-mapstore-2.md index 1014eefaa6..ce786530af 100644 --- a/docs/developer-guide/developing-with-mapstore-2.md +++ b/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 | | +-- .jsx (ReactJS component) | | +-- ... | | +-- __tests__ (unit tests folder) - | | +-- -test.jsx + | | +-- -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) \ No newline at end of file +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) diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md index 6dc123be13..b62027af7d 100644 --- a/docs/developer-guide/index.md +++ b/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) diff --git a/docs/developer-guide/infrastructure-and-general-architecture.md b/docs/developer-guide/infrastructure-and-general-architecture.md index 723ff22ec7..ff2a018388 100644 --- a/docs/developer-guide/infrastructure-and-general-architecture.md +++ b/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) +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) \ No newline at end of file +![MapStore 2 - Backend](https://docs.google.com/drawings/d/12SURY5tdrjOXwYx0kH1LHUmHogZpWvmcEoFCGJOgJWY/pub?w=480&h=360) diff --git a/docs/developer-guide/mapstore-migration-guide.md b/docs/developer-guide/mapstore-migration-guide.md new file mode 100644 index 0000000000..7b98ffda2e --- /dev/null +++ b/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. diff --git a/docs/developer-guide/react-0.14.x-migration-guide.md b/docs/developer-guide/react-0.14.x-migration-guide.md deleted file mode 100644 index 7684de66c7..0000000000 --- a/docs/developer-guide/react-0.14.x-migration-guide.md +++ /dev/null @@ -1,51 +0,0 @@ -# Migration Hints -We are migrating MapStore 2 to use the newest 0.14.x version of ReactJS. - -There are some differences in the new release that require some boring steps to make things working. [Here](https://facebook.github.io/react/blog/2015/10/07/react-v0.14.html) you can find the full release notes document from Facebook. - -Here are some quick tips: - - * Wherever you use React.render(...), React.findDOMNode(...) or React.umountComponentAtNode(...) you should: - * import the new react-dom library - * use ReactDOM.render(...), ReactDOM.findDOMNode(...) or ReactDOM.umountComponentAtNode(...) - -```javascript -const ReactDOM = require('react-dom'); -... -ReactDOM.render(..., ...); -``` - - * you should not do these things anymore (they are deprecated): - * component.getDOMNode(...) (use React.findDOMNode(component) instead) - * component.setProps(...), component.replaceProps(...) (you should re-render the component with the new props instead) - * require('react/addons') (require the new react-addon- for each of the needed addons instead) - * component.cloneWithProps(...) (use React.cloneElement instead) - * Context enabled containers (Provider, Localized, etc.) have a simpler syntax: - -```html -// old syntax - - {() => } - - -// new syntax - - - -``` - * new Debug component usage: the Debug component is not a wrapper anymore: - -```html -// old syntax - - - - - - -// new syntax - - - - -``` \ No newline at end of file diff --git a/docs/developer-guide/reactjs-and-redux-introduction.md b/docs/developer-guide/reactjs-and-redux-introduction.md index 1c43d59384..b9539d9590 100644 --- a/docs/developer-guide/reactjs-and-redux-introduction.md +++ b/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(, 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, store: Store): Observable; +``` + +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: