fix #1319 exported contents of wiki folder to mapstore2 (#1322)

* fix #1319 exported contents wiki folder to mapstore2 * fix
geosolutions-it · Dec 6, 2016 · 2c6174f · 2c6174f
1 parent d33e1f8
commit 2c6174f
Show file tree

Hide file tree

Showing 13 changed files with 869 additions and 0 deletions.
diff --git a/docs/developer-guide/Application-Tutorial.md b/docs/developer-guide/Application-Tutorial.md
@@ -0,0 +1,212 @@
+Writing a new MapStore2 based application can be done following these steps:
+ * create a new folder for the application, inside the MapStore2 directory tree (e.g. web/client/examples/myapp), and the following folder structure:
+
+```
++-- myapp
+    +-- index.html
+    +-- config.json
+    +-- webpack.config.js
+    +-- app.jsx
+    +-- containers
+    |   +-- myapp.jsx
+    +-- stores
+        +-- myappstore.js
+```
+ * create an **index.html** file inside the application folder
+
+```html
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="UTF-8">
+        <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>MyApp</title>
+        <link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.3/leaflet.css" />
+        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
+        <style>
+        html, body, #container, #map {
+            position:absolute;
+            width: 100%;
+            height: 100%;
+            margin: 0;
+            padding: 0;
+        }
+
+        </style>
+    </head>
+    <body>
+        <div id="container"></div>
+        <script src="dist/myapp.js"></script>
+    </body>
+</html>
+```
+ * create an **app.jsx** for the main app ReactJS component
+
+```javascript
+var React = require('react');
+var ReactDOM = require('react-dom');
+
+var Provider = require('react-redux').Provider;
+
+// include application component
+var MyApp = require('./containers/MyApp');
+var url = require('url');
+
+var loadMapConfig = require('../../actions/config').loadMapConfig;
+var ConfigUtils = require('../../utils/ConfigUtils');
+
+// initializes Redux store
+var store = require('./stores/myappstore');
+
+// reads parameter(s) from the url
+const urlQuery = url.parse(window.location.href, true).query;
+
+// get configuration file url (defaults to config.json on the app folder)
+const { configUrl, legacy } = ConfigUtils.getConfigurationOptions(urlQuery, 'config', 'json');
+
+// dispatch an action to load the configuration from the config.json file
+store.dispatch(loadMapConfig(configUrl, legacy));
+
+// Renders the application, wrapped by the Redux Provider to connect the store to components
+ReactDOM.render(
+    <Provider store={store}>
+        <MyApp />
+    </Provider>,
+    document.getElementById('container')
+);
+```
+ * create a **myapp.jsx** component inside the **containers** folder, that will contain the all-in-one Smart Component of the application
+
+```javascript
+var React = require('react');
+var connect = require('react-redux').connect;
+var LMap = require('../../../components/map/leaflet/Map');
+var LLayer = require('../../../components/map/leaflet/Layer');
+
+var MyApp = React.createClass({
+    propTypes: {
+        // redux store slice with map configuration (bound through connect to store at the end of the file)
+        mapConfig: React.PropTypes.object,
+        // redux store dispatch func
+        dispatch: React.PropTypes.func
+    },
+    renderLayers(layers) {
+        if (layers) {
+            return layers.map(function(layer) {
+                return <LLayer type={layer.type} key={layer.name} options={layer} />;
+            });
+        }
+        return null;
+    },
+    render() {
+        // wait for loaded configuration before rendering
+        if (this.props.mapConfig && this.props.mapConfig.map) {
+            return (
+                <LMap id="map" center={this.props.mapConfig.map.center} zoom={this.props.mapConfig.map.zoom}>
+                     {this.renderLayers(this.props.mapConfig.layers)}
+                </LMap>
+            );
+        }
+        return null;
+    }
+});
+
+// include support for OSM and WMS layers
+require('../../../components/map/leaflet/plugins/OSMLayer');
+require('../../../components/map/leaflet/plugins/WMSLayer');
+
+// connect Redux store slice with map configuration
+module.exports = connect((state) => {
+    return {
+        mapConfig: state.mapConfig
+    };
+})(MyApp);
+```
+
+ * create a **myappstore.js** store initalizer inside the **stores** folder, that will create the global Redux store for the application, combining the needed reducers and middleware components
+
+```javascript
+var {createStore, combineReducers, applyMiddleware} = require('redux');
+
+var thunkMiddleware = require('redux-thunk');
+var mapConfig = require('../../../reducers/config');
+
+ // reducers
+const reducers = combineReducers({
+    mapConfig
+});
+
+// compose middleware(s) to createStore
+let finalCreateStore = applyMiddleware(thunkMiddleware)(createStore);
+
+// export the store with the given reducers (and middleware applied)
+module.exports = finalCreateStore(reducers, {});
+```
+
+ * create a **config.json** file with basic map configuration
+
+```javascript
+{
+  "map": {
+    "projection": "EPSG:900913",
+    "units": "m",
+    "center": {"x": 1250000.000000, "y": 5370000.000000, "crs": "EPSG:900913"},
+    "zoom":5,
+    "layers": [
+      {
+        "type": "osm",
+        "title": "Open Street Map",
+        "name": "mapnik",
+        "group": "background",
+        "visibility": true
+      },
+      {
+        "type": "wms",
+        "url":"http://demo.geo-solutions.it/geoserver/wms",
+        "visibility": true,
+        "opacity": 0.5,
+        "title": "Weather data",
+        "name": "nurc:Arc_Sample",
+        "group": "Meteo",
+        "format": "image/png"
+      }
+    ]
+  }
+}
+```
+
+* create a **webpack.config.js** file with build configuration
+
+```javascript
+var path = require("path");
+
+module.exports = {
+    entry: {
+        myapp: path.join(__dirname, "app")
+    },
+    output: {
+      path: path.join(__dirname, "dist"),
+        publicPath: "/dist/",
+        filename: "myapp.js"
+    },
+    resolve: {
+      extensions: ["", ".js", ".jsx"]
+    },
+    module: {
+        loaders: [
+            { test: /\.jsx?$/, loader: "babel-loader" }
+        ]
+    },
+    devtool: 'inline-source-map',
+    debug: true
+};
+```
+
+Now the application is ready, to launch it in development mode, you can use the following command (launch it from the MapStore2 main folder):
+
+```
+./node_modules/.bin/webpack-dev-server --config web/client/examples/myapp/webpack.config.js --progress --colors --port 8081 --content-base web/client/examples/myapp
+```
+
+Then point your preferred browser to the following url: [http://localhost:8081](http://localhost:8081)
diff --git a/docs/developer-guide/Building-and-developing.md b/docs/developer-guide/Building-and-developing.md
@@ -0,0 +1,79 @@
+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.
+
+A basic knowledge of both tools is required.
+
+# Developing and debugging the MapStore 2 framework
+To start developing the MapStore 2 framework you have to:
+ * download developer tools and frontend dependencies locally:
+
+`npm install`
+
+After a while (depending on the network bandwidth) the full set of dependencies and tools will be downloaded to the **node_modules** subfolder.
+
+ * start a development instance of the framework and example applications:
+
+`npm run examples`
+
+ * or you can start a development instance **without the examples**:
+
+`npm start`
+
+Then point your preferred browser to [http://localhost:8081](http://localhost:8081).
+
+The HomePage contains links to the available demo applications.
+
+## Frontend debugging
+The development instance uses file watching and live reload, so each time a MapStore 2 file is changed, the browser will reload the updated application.
+
+Use your favourite editor / IDE to develop and debug on the browser as needed.
+
+We suggest to use one of the following:
+ * [Atom](https://atom.io/) with the following plugins:
+  * editorconfig
+  * linter
+  * linter-eslint
+  * react
+  * lcovinfo
+ * [Sublime Text Editor](http://www.sublimetext.com/) with the following plugins:
+  * Babel
+  * Babel snippets
+  * Emmet
+
+## Backend services debugging
+TBD
+
+## Frontend testing
+To run the MapStore 2 frontend test suite you can use:
+
+`npm test`
+
+You can also have a continuosly running watching test runner, that will execute the complete suite each time a file is changed, launching:
+
+`npm run continuoustest`
+
+To run ESLint checks launch:
+
+`npm run lint`
+
+To run the same tests Travis will check (before a pull request):
+`npm run travis`
+
+# General building and deploying
+Maven is the main tool for building and deploying a complete application. It takes care of:
+ * building the java libraries and webapp(s)
+ * calling NPM as needed to take care of the frontend builds
+ * launching both backend and frontend test suites
+ * creating the final war for deploy into a J2EE container (e.g. Tomcat)
+
+To create the final war, you have several options:
+ * full build, including submodules (e.g. GeoStore)
+
+`./build.sh`
+
+or
+
+`mvn clean install -Pgeostore,proxy, extjs,postgres,h2_disk`
+
+ * fast build (will use the last compiled version of submodules)
+
+`mvn clean install`
diff --git a/docs/developer-guide/Developers-Guide.md b/docs/developer-guide/Developers-Guide.md
@@ -0,0 +1,36 @@
+# Quick Start:
+
+Clone the repository with the --recursive option to automatically clone submodules:
+
+`git clone --recursive https://github.com/geosolutions-it/MapStore2.git`
+
+Install NodeJS 0.12 , if needed, from [here](https://nodejs.org/en/download/releases/).
+
+Start the demo locally:
+
+`npm cache clean` (this is useful to prevent errors on Windows during install)
+
+`npm install`
+
+`npm start`
+
+Then point your preferred browser to [http://localhost:8081](http://localhost:8081).
+
+Install latest Maven, if needed, from [here](https://maven.apache.org/download.cgi) (version 3.1.0 is required).
+
+Build the deployable war:
+
+`./build.sh`
+
+Deploy the generated mapstore.war file (in web/target) to your favourite J2EE container (e.g. Tomcat).
+
+# Developers documentation
+ * [Infrastructure](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Infrastructure-and-general-architecture)
+ * [Building and developing](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Building-and-developing)
+ * [Frontend building tools and configuration](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Frontend-building-tools-and-configuration)
+ * [Developing with MapStore 2](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Developing-with-MapStore-2)
+ * [ReactJS and Redux introduction](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/ReactJS-and-Redux-introduction)
+ * [ReactJS 0.14.x](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/React-0.14.x-Migration-Guide)
+ * [Maps configuration](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Maps-configuration)
+ * [Plugins architecture](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Plugins-architecture)
+ * [How to use a CDN](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/How-to-use-a-CDN)
diff --git a/docs/developer-guide/Developing-with-MapStore-2.md b/docs/developer-guide/Developing-with-MapStore-2.md
@@ -0,0 +1,63 @@
+# Folders structure
+
+This is the overall framework folder structure:
+
+```
++-- package.json
++-- pom.xml
++-- build.sh
++-- karma.conf.*.js
++-- tests.webpack.js
++-- webpack.config.js
++-- prod-webpack.config.js
++-- .babelrc
++-- .eslintrc
++-- .editorconfig
++-- .travis.yml
++-- ...
++-- geostore (submodule)
++-- web      (MapStore2 maven module)
+    +-- pom.xml
+    +-- src        (maven java webapp src folder)
+    |   +-- main
+    |   |   +-- java
+    |   |   +-- resources
+    |   |   +-- webapp
+    |   +-- test
+    |        +-- java
+    |        +-- resources   
+    +-- client
+    |   +-- 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
+        |   +-- ...
+        +-- actions    (Redux actions)
+        +-- reducers   (Redux reducers)
+        +-- stores     (Redux stores)
+        +-- translations (i18n localization files)
+        |  +-- data.en-US
+        |  ...
+        |  product (the MapStore2 main application)
+        |   +...
+        +-- examples   (example applications)
+             +-- 3dviewer
+             |   +-- index.html
+             |   +-- app.jsx
+             |   +-- containers (app specific smart components)
+             |   +-- components (app specific dumb components)
+             |   +-- stores     (app specific stores)
+             |   +-- reducers   (app specific reducers)
+             |   +-- ...
+             +-- ...
+```
+
+If you want to create an application based on MapStore2 you can use the [Project Creation Script](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Project-Creation-Script).
+
+If you want to learn how to develop a simple MapStore2 based application you can follow the [tutorial](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Application-Tutorial)
+
+If you want to learn how to develop a plugins based MapStore2 based application you can follow the [plugins tutorial](https://github.com/geosolutions-it/MapStore2/blob/master/docs/developer-guide/Plugins-architecture#building-an-application-using-plugins)