Update documentation

See #5
geo6 · Feb 25, 2019 · e09ca06 · e09ca06
1 parent 1e5200a
commit e09ca06
Show file tree

Hide file tree

Showing 2 changed files with 223 additions and 46 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -8,63 +8,236 @@ composer create-project geo6/mapper
 
 ## Authentication
 
-To enable authentication, add the following in your configuration file (usually `config/autoload/local.php`) :
-
-    'authentication' => [
-        'pdo' => [
-            'dsn' => 'pgsql:host=localhost;port=5432;dbname=...',
-            'username' => '...',
+To enable authentication, add the following in `config/autoload/local.php` :
+
+```php
+'authentication' => [
+    'pdo' => [
+        'dsn' => 'pgsql:host=localhost;port=5432;dbname=...',
+        'username' => '...',
+        'password' => '...',
+        'table' => '...',
+        'field' => [
+            'identity' => '...',
             'password' => '...',
-            'table' => '...',
-            'field' => [
-                'identity' => '...',
-                'password' => '...',
-            ],
-            'sql_get_roles' => '...',
-            'sql_get_details' => '...',
         ],
+        'sql_get_roles' => '...',
+        'sql_get_details' => '...',
     ],
+],
+```
 
-See <https://docs.zendframework.com/zend-expressive-authentication/v1/user-repository/#pdo-configuration> for more information !
+See [Zend Expressive Authentication configuration](https://docs.zendframework.com/zend-expressive-authentication/v1/user-repository/#pdo-configuration) for more information !
 
 ## Configuration
 
-### Baselayers
+You can write your configuration files using any format compatible with [`Zend\Config\Reader`](https://docs.zendframework.com/zend-config/reader/) (`.ini`, `.xml`, `.json`, `.yaml`, `.php`).
+
+### Geocoder providers (global)
+
+The geocoding uses [Geocoder PHP library](https://github.com/geocoder-php/Geocoder). A list of providers is available [here](https://github.com/geocoder-php/Geocoder#providers).
+
+1. Install the new provider:
+
+    ```shell
+    composer install <geocoder-provider-package>
+    ```
+
+2. Then, declare the newly installed provider in `config/autoload/geocoder.global.php` file:
+
+    ```php
+    '<provider-name>' => [
+        'reverse' => true|false,
+        'title'   => '<provider-title>',
+    ],
+    ```
+
+    | Parameter | Type      | Description                                  |
+    | --------- | --------- | -------------------------------------------- |
+    | `reverse` | *boolean* | Does the service provide reverse geocoding ? |
+    | `title`   | *string*  | Provider display title.                      |
+
+### Coordinates Reference Systems (global)
+
+File `config/autoload/epsg.global.php`
+
+```php
+'<projection-code>' => [
+    'name'  => '<projection-name>',
+    'proj4' => '<projection-proj4-definition>',
+],
+```
+
+| Parameter | Type     | Description                                                      |
+| --------- | -------- | ---------------------------------------------------------------- |
+| `name`    | *string* | Projection display name.                                         |
+| `proj4`   | *string* | [PROJ.4](https://proj4.org/) definition. See <https://epsg.io/>. |
 
-A baselayer can be a XYZ, a WMS, or a WMTS service.
+### Custom configuration
 
-`config/application/baselayers.yaml`
+Custom configuration is defined by "project". Those "projects" can be define by role, user or be available for everyone (= *public*).
+
+To declare a new "project", just create a new folder in one of those directories:
+
+- `config/application/public/`
+- `config/application/roles/<rolename>/`
+- `config/application/users/<username>/`
+
+You will then be able to access a "project" by adding `?c=<project-foldername>` in the URL.
+
+If you want the same baselayers for every "project", you can configure your baselayers in a global `config/application/baselayers.yaml` file.
+
+### Project
+
+```yaml
+---
+title: <project-title>
+description: <project-description>
+map:
+    center: [<project-default-map-center-longitude>, <project-default-map-center-latitude>]
+    zoom: <project-default-map-zoom>
+
+```
+
+| Parameter               | Type      | Description                                                   |
+| ----------------------- | --------- | ------------------------------------------------------------- |
+| `title`                 | *string*  | Project display title.                                        |
+| `description`           | *string*  | Project description (available in "About" sidebar tab).       |
+| `map.center` (optional) | *float[]* | Project default map center coordinates (Longitude, Latitude). |
+| `map.zoom` (optional)   | *float[]* | Project default map zoom level.                               |
+
+### Baselayers
 
 ```yaml
 ---
 baselayers:
-  osmbe:
-    name: OpenStreetMap Belgium
-    url: https://tile.osm.be/osmbe/{z}/{x}/{y}.png
-    attributions:
-      - © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors.
-      - Tiles courtesy of <a href="https://geo6.be/">GEO-6</a>
-    maxZoom: 18
-
-  cirb_ortho:
-    name: "Bruxelles-Brussel (OrthoPhotos 2018)"
-    url: https://geoservices-urbis.irisnet.be/geoserver/ows/
-    mode: wms
-    layers: ['Ortho2018']
-    attributions: ['CIRB © CIBG']
-
-  aiv_grb_wmts:
-    name: "Vlaanderen (Vector: GRB)"
-    url: https://tile.informatievlaanderen.be/ws/raadpleegdiensten/wmts/
-    mode: wmts
-    layer: grb_bsk
-    attributions: ['© AIV']
+  <baselayer-1>
+  <baselayer-2>
+  ...
 ```
 
-## Layers
+Replace  `<baselayer-#>` by one of the following (XYZ, WMS, WMTS):
+
+#### XYZ baselayer
 
-...
+```yaml
+<baselayer-id>:
+  name: <baselayer-name>
+  url: <baselayer-url>
+  attributions:
+    - <baselayer-attribution-1>
+    - <baselayer-attribution-2>
+    - ...
+  maxZoom: <baselayer-max-zoom>
+```
 
-## Files
+| Parameter                 | Type       | Description                   |
+| ------------------------- | ---------- | ----------------------------- |
+| `name`                    | *string*   | Baselayer display name.       |
+| `url`                     | *string*   | Baselayer (service) URL.      |
+| `attributions` (optional) | *string[]* | Baselayer attribution(s).     |
+| `maxZoom` (optional)      | *integer*  | Baselayer maximum zoom level. |
+
+#### WMS baselayer
+
+```yaml
+<baselayer-id>:
+  mode: wms
+  name: <baselayer-name>
+  url: <baselayer-service-url>
+  layers: [<layer-1-id>, <layer-2-id>, ...]
+  attributions:
+    - <baselayer-attribution-1>
+    - <baselayer-attribution-2>
+    - ...
+```
+
+| Parameter                 | Type       | Description                    |
+| ------------------------- | ---------- | ------------------------------ |
+| `name`                    | *string*   | Baselayer display name.        |
+| `url`                     | *string*   | Baselayer service URL.         |
+| `layers`                  | *string[]* | Baselayer service layers name. |
+| `attributions` (optional) | *string[]* | Baselayer attribution(s).      |
+
+#### WMTS baselayer
+
+```yaml
+<baselayer-id>:
+  mode: wmts
+  name: <baselayer-name>
+  url: <baselayer-service-url>
+  layer: <layer-id>
+  attributions:
+    - <baselayer-attribution-1>
+    - <baselayer-attribution-2>
+    - ...
+```
+
+| Parameter                 | Type       | Description                   |
+| ------------------------- | ---------- | ----------------------------- |
+| `name`                    | *string*   | Baselayer display name.       |
+| `url`                     | *string*   | Baselayer service URL.        |
+| `layer`                   | *string[]* | Baselayer service layer name. |
+| `attributions` (optional) | *string[]* | Baselayer attribution(s).     |
+
+### Layers
+
+```yaml
+---
+layers:
+  <layer-1>
+  <layer-2>
+  ...
+```
+
+Replace  `<layer-#>` by one of the following (WMS, WMTS):
+
+#### WMS layer
+
+```yaml
+- type: wms
+  url: <service-url>
+  proxy: true|false
+  auth:
+    type: digest
+    username: <service-username>
+    password: <service-password>
+  layers: []
+  maxZoom: <service-maxzoomlevel>
+```
+
+| Parameter                  | Type       | Description                                                       |
+| -------------------------- | ---------- | ----------------------------------------------------------------- |
+| `url`                      | *string*   | WMS service URL.                                                  |
+| `proxy` (optional)         | *boolean*  | Use *Mapper* application as proxy to query the WMS service ?      |
+| `auth.type` (optional)     | *string*   | Type of authentication used by the WMS service (basic or digest). |
+| `auth.username` (optional) | *string*   | Username for the authentication.                                  |
+| `auth.password` (optional) | *string*   | Password for the authentication.                                  |
+| `layers` (optional)        | *string[]* | List of layers displayed by default.                              |
+| `maxZoom` (optional)       | *integer*  | WMS service maximum zoom level.                                   |
+
+#### WMTS layer
+
+```yaml
+- type: wmts
+  url: <service-url>
+```
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `url`     | *string* | WMS service URL. |
+
+### Layers
+
+```yaml
+---
+files:
+    - type: <file-type>
+      path: <file-path>
+    - ...
+```
 
-...
+| Parameter | Type     | Description                        |
+| --------- | -------- | ---------------------------------- |
+| `type`    | *string* | `csv`, `geojson`, `gpx`, or `kml`. |
+| `path`    | *string* | Path of a file or a directory.     |
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 
 ## Features
 
-- Change baselayer
+- Baselayers
 - Address or POI geocoding
 - Location reverse geocoding
 - Draw
@@ -29,6 +29,10 @@ The *Mapper* supports the following services and file formats :
 
 ## Install
 
-```shell
-composer create-project geo6/mapper
-```
+See [INSTALL.md](INSTALL.md)
+
+## Configuration
+
+The application is configured for Belgium (geocoding services, baselayers, ...) but you can easily adapt the configuration to your use case.
+
+See [INSTALL.md#Configuration](INSTALL.md#Configuration)