From c139f105a1f5c3b16057f7364f59f8d80b390692 Mon Sep 17 00:00:00 2001
From: kahummer <pkahama@ona.io>
Date: Fri, 4 Oct 2019 22:08:53 +0300
Subject: [PATCH] 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: <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"] 
+``` 
+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<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"]
+```
+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
+<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
+{
+    "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": [
+            55,
+            56,
+        ],
+        "join": [
+            "pd_number",
+            "pd_number",
+        ],
+    }
+```
+<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": {
+            "type": "superset",
+            "slice-id": 2238},
+            "layer": "homes",
+            "url": "mapbox://cncncncnc",
+            "join": [
+                "homes",
+                "homes"
+            ]
+        },
+```
+<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`. 
+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