This repository has been archived by the owner on Feb 19, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
80 additions
and
64 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -27,12 +27,11 @@ $ npm install gisida | |
| <script src="http://demo.gisida.onalabs.org/assets/js/gisida.js"> </script> | ||
| ``` | ||
|
|
||
|
|
||
| ## Getting Started | ||
|
|
||
| ### 1.Create config file | ||
|
|
||
| - Create a `config.json` and save it in the application's root path. An example `config.json` file is provided below: | ||
| - Create a `config.json` and save it in the application's root path. An example `config.json` file is provided below: | ||
|
|
||
| ```json | ||
| { | ||
|
|
@@ -75,15 +74,16 @@ $ npm install gisida | |
| ### 2. Import and initializing the store. | ||
|
|
||
| ```javascript | ||
| import { initStore } from 'gisida'; | ||
| import { initStore } from "gisida"; | ||
|
|
||
| const store = initStore(); | ||
| ``` | ||
|
|
||
| ### 3. Adding Layers | ||
| - The `layersPath` propery under `APP.mapConfig` is used to define the folder that contains the layers files. | ||
|
|
||
| - The `LAYERS` propery is a list that contains the filenames of the layers that should be loaded into state. | ||
| - The `layersPath` propery under `APP.mapConfig` is used to define the folder that contains the layers files. | ||
|
|
||
| - The `LAYERS` propery is a list that contains the filenames of the layers that should be loaded into state. | ||
|
|
||
| **NOTE:** The filename is added withouth the `.json` extension in the config file. | ||
|
|
||
|
|
@@ -106,22 +106,27 @@ An example layer file in the path `/layers/ken-health-sites.json` | |
| }, | ||
| "layout": { | ||
| "text-field": "{name} ({type})", | ||
| "text-offset": [0,2], | ||
| "text-offset": [0, 2], | ||
| "icon-image": "hospital-11", | ||
| "icon-allow-overlap": true, | ||
| "text-transform": "uppercase" | ||
| }, | ||
| "visible": false, | ||
| "credit": "Global Healthsites Mapping Project<br>Aug 15, 2017" | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| ## Data Sources | ||
|
|
||
| Gisida supports various data sources. These include: <br> | ||
| **csv -** A [csv](https://en.wikipedia.org/wiki/Comma-separated_values) file can be used solely as a source without joining it with any other source as long as it has geolocations columns i.e longitude and latitude. If the fields are named differently one will need to include geo-columns property on the layer spec as shown below. | ||
| ``` | ||
| "geo-columns": ["longitude", "latitude"] | ||
| ``` | ||
| **csv -** A [csv](https://en.wikipedia.org/wiki/Comma-separated_values) file can be used solely as a source without joining it with any other source as long as it has geolocations columns i.e longitude and latitude. If the fields are named differently one will need to include geo-columns property on the layer spec as shown below. | ||
|
|
||
| ``` | ||
| "geo-columns": ["longitude", "latitude"] | ||
| ``` | ||
|
|
||
| An example of such a layer | ||
|
|
||
| ```json | ||
| { | ||
| "label": "Kenya Health Sites", | ||
|
|
@@ -141,20 +146,24 @@ An example of such a layer | |
| }, | ||
| "layout": { | ||
| "text-field": "{name} ({type})", | ||
| "text-offset": [0,2], | ||
| "text-offset": [0, 2], | ||
| "icon-image": "hospital-11", | ||
| "icon-allow-overlap": true, | ||
| "text-transform": "uppercase" | ||
| }, | ||
| "visible": false, | ||
| "credit": "Global Healthsites Mapping Project<br>Aug 15, 2017" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| We can also join the csv with a vector layer being served from mapbox. To achieve this we need to add a columns with simmillar data on both datasets for the join to work. | ||
|
|
||
| ``` | ||
| "join":["name","name"] | ||
| "join":["vectorProp","csvProp"] | ||
| ``` | ||
| An example of such a layer | ||
|
|
||
| An example of such a layer | ||
|
|
||
| ```json | ||
| { | ||
| "label": "Kenya Health Sites", | ||
|
|
@@ -163,64 +172,64 @@ An example of such a layer | |
| "layer": "province", | ||
| "url": "mapbox://ona.cxeuuuuu", | ||
| "data": "data/ken_health_sites.csv", | ||
| "join": [ | ||
| "ADM2_EN", | ||
| "province1" | ||
| ] | ||
| "join": ["ADM2_EN", "province1"] | ||
| }, | ||
| "type": "fill", | ||
| "minZoom": 0, | ||
| "categories": { | ||
| "breaks": "yes", | ||
| "color": "Greens", | ||
| "clusters": 3 | ||
| }, | ||
| "breaks": "yes", | ||
| "color": "Greens", | ||
| "clusters": 3 | ||
| }, | ||
| "visible": false, | ||
| "credit": "Kenya Health Mapping Project" | ||
| } | ||
| ``` | ||
| } | ||
| ``` | ||
|
|
||
| The url points to the tileset which is joined with the csv file on basis of the two files i.e ADM2_EN and province1 | ||
| <br> | ||
| **geojson -** We use [geojon](https://geojson.org/) format mostly to build to render geometric centres (centroids) of regions on a map but they still can be used simmilarly as csv's. An example of geojson data source in action | ||
| ``` json | ||
|
|
||
| ```json | ||
| { | ||
| "label": "District Labels", | ||
| "source": { | ||
| "type": "geojson", | ||
| "data": "data/centroids-2.geojson" | ||
| }, | ||
| "type": "symbol", | ||
| "minzoom": 0, | ||
| "paint": { | ||
| "text-color": "#000", | ||
| "text-halo-color": "#fff", | ||
| "text-halo-width": 1.3, | ||
| "text-halo-blur": 1 | ||
| }, | ||
| "layout": { | ||
| "text-size": 12, | ||
| "text-field": "{NAME}", | ||
| "text-transform": "uppercase", | ||
| "text-offset": [ | ||
| 0, | ||
| 0 | ||
| ] | ||
| }, | ||
| "visible": false, | ||
| "category": "Boundaries & Labels" | ||
| "label": "District Labels", | ||
| "source": { | ||
| "type": "geojson", | ||
| "data": "data/centroids-2.geojson" | ||
| }, | ||
| "type": "symbol", | ||
| "minzoom": 0, | ||
| "paint": { | ||
| "text-color": "#000", | ||
| "text-halo-color": "#fff", | ||
| "text-halo-width": 1.3, | ||
| "text-halo-blur": 1 | ||
| }, | ||
| "layout": { | ||
| "text-size": 12, | ||
| "text-field": "{NAME}", | ||
| "text-transform": "uppercase", | ||
| "text-offset": [0, 0] | ||
| }, | ||
| "visible": false, | ||
| "category": "Boundaries & Labels" | ||
| } | ||
| ``` | ||
| ``` | ||
|
|
||
| To test whether the geojson file is working and is of right format you can paste it's content [here](http://geojson.io) and check whether it renders. | ||
| <br> | ||
| **onadata -** Gisida supports data coming from [Ona](https://ona.io/) forms. When building layers that pull data from Ona you will have to provide the form id on the layer spec. | ||
| ``` | ||
|
|
||
| ``` | ||
| "source": { | ||
| "type": "geojson", | ||
| "data": 899 | ||
| } | ||
| ``` | ||
|
|
||
| We can also pull data from different forms and join the various form data. Here is an example. | ||
| ``` | ||
|
|
||
| ``` | ||
| "source": { | ||
| "type": "geojson", | ||
| "data": [ | ||
|
|
@@ -233,10 +242,12 @@ We can also pull data from different forms and join the various form data. Here | |
| ], | ||
| } | ||
| ``` | ||
|
|
||
| <br> | ||
|
|
||
| **superset slice -** Gisida supports [superset/canopy](https://canopyinsights.com/) slices. The slice are api's that hold unique id's. The splice id property should be provided on the layer spec. Here is an example of a superset layer in action: | ||
| ``` | ||
|
|
||
| ``` | ||
| "source": { | ||
| "type": "vector", | ||
| "data": { | ||
|
|
@@ -250,13 +261,14 @@ We can also pull data from different forms and join the various form data. Here | |
| ] | ||
| }, | ||
| ``` | ||
|
|
||
| <br> | ||
|
|
||
| **Pulling Directly from Mapbox** | ||
|
|
||
| Ensure that the data file for the layer is located in the specified source path `data/ken_health_sites.geojson or a remote url that points to the file`. | ||
| Ensure that the data file for the layer is located in the specified source path `data/ken_health_sites.geojson or a remote url that points to the file`. | ||
|
|
||
| ### 3. Actions | ||
| ### 3. Actions | ||
|
|
||
| Gisida provides in-build functions that trigger to process and managed data in the store; | ||
|
|
||
|
|
@@ -267,56 +279,60 @@ Gisida provides in-build functions that trigger to process and managed data in t | |
| - addLegend | ||
| - buildTimeSeriesData | ||
|
|
||
|
|
||
| TODO: add documentation for Gisida API | ||
|
|
||
|
|
||
| ## Development | ||
| To locally develop and make changes to gisida: | ||
|
|
||
| To locally develop and make changes to gisida: | ||
|
|
||
| ### Local development | ||
|
|
||
| - Clone repo: | ||
|
|
||
| ``` | ||
| $ git clone [email protected]:onaio/gisida.git | ||
| ``` | ||
|
|
||
| - Link the project folder as local module within your project using [`npm link`](https://docs.npmjs.com/cli/link) or [`yarn link`](https://yarnpkg.com/lang/en/docs/cli/link/) if you use yarn as your preferred node package manager. | ||
| - Link the project folder as local module within your project using [`npm link`](https://docs.npmjs.com/cli/link) or [`yarn link`](https://yarnpkg.com/lang/en/docs/cli/link/) if you use yarn as your preferred node package manager. | ||
|
|
||
| - Run development build: | ||
|
|
||
| ``` | ||
| $ npm develop | ||
| ``` | ||
|
|
||
| ### Production build | ||
| ### Production build | ||
|
|
||
| - Build production distribution | ||
|
|
||
| ``` | ||
| $ npm build | ||
| ``` | ||
|
|
||
| - Publish to npm | ||
|
|
||
| ``` | ||
| $ npm publish | ||
| ``` | ||
|
|
||
|
|
||
| ### Releases | ||
|
|
||
| 1. Check https://github.com/onaio/gisida/releases to see what the next release version number should be, i.e. if the last release is `0.0.7` the next should be `0.0.8` depending on the Semantic Versioning guide, refer to (https://semver.org/). | ||
| 1. Check https://github.com/onaio/gisida/releases to see what the next release version number should be, i.e. if the last release is `0.0.7` the next should be `0.0.8` depending on the Semantic Versioning guide, refer to (https://semver.org/). | ||
|
|
||
| 2. Create branch for new version being released, `git checkout -b <version-number>` | ||
| 2. Create branch for new version being released, `git checkout -b <version-number>` | ||
|
|
||
| ``` | ||
| $ git checkout -b 0.0.8 | ||
| ``` | ||
|
|
||
| 3. Run `npm version <version-number>`. This creates a commit and updates version number in package.json. | ||
|
|
||
| ``` | ||
| $ npm version 0.0.8 | ||
| ``` | ||
|
|
||
| 4. Push release branch to Github and tag `git push -u --follow-tags origin <version-number>` e.g | ||
|
|
||
| ``` | ||
| $ git push -u --follow-tags origin 0.0.8 | ||
| ``` | ||
|
|
||