From c139f105a1f5c3b16057f7364f59f8d80b390692 Mon Sep 17 00:00:00 2001 From: kahummer Date: Fri, 4 Oct 2019 22:08:53 +0300 Subject: [PATCH 1/2] Add docs for supported data sources --- README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 75a935eb..69e19c88 100644 --- a/README.md +++ b/README.md @@ -116,8 +116,145 @@ An example layer file in the path `/layers/ken-health-sites.json` } ``` +Gisida supports various data sources. These include:
+**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", + "source": { + "type": "geojson", + "featureType": "Point", + "data": "data/ken_health_sites.csv" + }, + "geo-columns": ["longs", "lats"], + "type": "symbol", + "minZoom": 0, + "paint": { + "text-color": "#000", + "text-halo-color": "#fff", + "text-halo-width": 1.3, + "text-halo-blur": 1 + }, + "layout": { + "text-field": "{name} ({type})", + "text-offset": [0,2], + "icon-image": "hospital-11", + "icon-allow-overlap": true, + "text-transform": "uppercase" + }, + "visible": false, + "credit": "Global Healthsites Mapping Project
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"] +``` +An example of such a layer +```json +{ + "label": "Kenya Health Sites", + "source": { + "type": "vector", + "layer": "province", + "url": "mapbox://ona.cxeuuuuu", + "data": "data/ken_health_sites.csv", + "join": [ + "ADM2_EN", + "province1" + ] + }, + "type": "fill", + "minZoom": 0, + "categories": { + "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 +
+**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 +{ + "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. +
+**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": [ + 55, + 56, + ], + "join": [ + "pd_number", + "pd_number", + ], + } +``` +
+ +**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": { + "type": "superset", + "slice-id": 2238}, + "layer": "homes", + "url": "mapbox://cncncncnc", + "join": [ + "homes", + "homes" + ] + }, +``` +
+ +**Pulling Directly from Mapbox** -Ensure that the data file for the layer is located in the specified source path `data/ken_health_sites.geojson`. +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 From ea5cb9183fb608b8244863904a2207bdabf6c12b Mon Sep 17 00:00:00 2001 From: kahummer Date: Tue, 17 Dec 2019 12:04:44 +0300 Subject: [PATCH 2/2] Data sources enhancements --- README.md | 144 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 80 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 69e19c88..9cd03793 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,11 @@ $ npm install gisida ``` - ## 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,7 +106,7 @@ 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" @@ -114,14 +114,19 @@ An example layer file in the path `/layers/ken-health-sites.json` "visible": false, "credit": "Global Healthsites Mapping Project
Aug 15, 2017" } - ``` + +## Data Sources + Gisida supports various data sources. These include:
-**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
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
**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.
**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 ], } ``` +
**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 ] }, ``` +
**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,20 +279,21 @@ 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 git@github.com: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: @@ -288,35 +301,38 @@ $ git clone git@github.com:onaio/gisida.git $ 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 ` +2. Create branch for new version being released, `git checkout -b ` ``` $ git checkout -b 0.0.8 ``` 3. Run `npm version `. 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 ` e.g + ``` $ git push -u --follow-tags origin 0.0.8 ```