Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
Dec 6, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 212 additions & 0 deletions docs/developer-guide/Application-Tutorial.md
Original file line number Diff line number Diff line change
@@ -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)
79 changes: 79 additions & 0 deletions docs/developer-guide/Building-and-developing.md
Original file line number Diff line number Diff line change
@@ -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`
36 changes: 36 additions & 0 deletions docs/developer-guide/Developers-Guide.md
Original file line number Diff line number Diff line change
@@ -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)
63 changes: 63 additions & 0 deletions docs/developer-guide/Developing-with-MapStore-2.md
Original file line number Diff line number Diff line change
@@ -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)
Loading