Skip to content

Commit

Permalink
Update module docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jlord
jlord committed Mar 19, 2017
1 parent 0a0b5d6 commit f2a5b27
Show file tree
Hide file tree
Showing 3 changed files with 169 additions and 245 deletions.
163 changes: 79 additions & 84 deletions docs/sheetsee-core.md
View file
Original file line number Diff line number Diff line change
@@ -1,135 +1,130 @@
# Sheetsee-core
# sheetsee-core

This is the core module in sheetsee and is included in all builds. It contains the functions for building your custom file as well as the basic data manipulation functions.
This module is included in every Sheetsee build. It contains methods for basic data manipulation you might want to do.

## Working With Your Data

Tabletop.js will fetch the data from your spreadsheet and return it as an _array of objects_. Sheetsee.js has functions built in to help you filter or reorganize the data if you'd like.
Sheetsee pairs with [Tabletop.js](https://github.com/jsoma/tabletop) which will fetch the data from your spreadsheet and return it as an _array of objects_. You'll use these methods from Sheetsee after you have that data.

### Sheetsee.getGroupCount(data, groupTerm)
## Methods

This takes in your data, an _array of objects_, and searches for a _string_, **groupTerm**, in each piece of your **data** (formerly the cells of your spreadsheet). It returns the number of times it found the **groupTerm**.
Here are the functions you can use!

```JAVASCRIPT
getGroupCount(data, "cat")
// returns a number
```
### `Sheetsee.getKeywordCount(data, keyword)`

### Sheetsee.getColumnTotal(data, column)
- `data` _array of objects_
- `keyword` _string_
- Returns _number_

Given your **data**, an _array of objects_, and a _string_ **column** header, this functions sums each cell in that column(so this collumn you mention best have numbers).
Given your **data** and **keyword** to search by, this function returns the number of times it occurs throughout all of the data.

```JAVASCRIPT
getColumnTotal(data, "cuddlability")
// returns number
```javascript
getGroupCount(data, 'cat')
// returns a number
```

### Sheetsee.getAveragefromColumn(data, column)

A really simple function that builds on `getColumnTotal()` by returning the average number in a **column** of numbers.

```JAVASCRIPT
getColumnAverage(data, "cuddlability")
// returns number
```
### `Sheetsee.getKeyword(data, keyword)`

### Sheetsee.getMin(data, column)
- `data` _array of objects_
- `keyword` _string_
- Returns _number_

This will return an _array_ of _object_ or _objects_ (if there is a tie) of the element with the lowest _number_ value in the **column** you specify from your **data**.
Given your **data** and a **keyword** to search by, this function returns every row which contains a match to the keyword.

```JAVASCRIPT
getMin(data, "cuddlability")
// returns array
```javascript
getKeyword(data, 'cat')
// returns array of objects
```

### Sheetsee.getMax(data, column)
### `Sheetsee.getColumnTotal(data, column)`

This will return an _array_ of _object_ or _objects_ (if there is a tie) of the element with the highest _number_ value in the **column** you specify from your **data**.

```JAVASCRIPT
getMin(data, "cuddlability")
// returns array
```
- `data` _array of objects_
- `column` _string_
- Returns _number_

### Don't Forget JavaScript Math
_Use only with columns of numbers_

Create variables that are the sums, differences, multiples and so forth of others. Lots of info on that [here on MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Math).
Given your **data** and **column** header, this function sums each cell in that column and returns the value.

```JAVASCRIPT
var profit09 = Sheetsee.getColumnTotal(data, "2009")
var profit10 = Sheetsee.getColumnTotal(data, "2010")
var difference = profit09 - profit10
```javascript
getColumnTotal(data, 'cuddlability')
// returns number
```

#### What These Little Bits are Good For
### `Sheetsee.getColumnAverage(data, column)`

You don't have to just create tables of your data. You can have other portions of your page that show things like, "The difference taco consumption between last week and this week is..." These are easy to create with JavaScript math functions and knowing a little bit more about [icanhaz.js](http://icanhazjs.com/).
- `data` _array of objects_
- `column` _string_
- Returns _number_

### Sheetsee.getMatches(data, filter, category)
Given your **data** and **column** header, this function returns the average value of every cell in the column.

Takes **data** as an _array of objects_, a _string_ you'd like to **filter** and a _string_ of the **category** you want it to look in (a column header from your spreadsheet).

```JAVASCRIPT
getMatches(data, "dog", "kind")
```javascript
getColumnAverage(data, 'cuddlability')
// returns number
```

Returns an _array of objects_ matching the category's filter.

```JAVASCRIPT
[{"name": "coco", "kind": "dog"...}, {"name": "wolfgang", "kind": "dog"...},{"name": "cooc", "kind": "dog"...} ]
```
### `Sheetsee.getMin(data, column)`

### Sheetsee.getOccurance(data, category)
- `data` _array of objects_
- `column` _string_
- Returns _array_

Takes **data** as an _array of objects_ and a _string_ for **category** (a column header from your spreadsheet) you want tally how often an element occured.
Given your **data** and **column** header, this function returns an array of the rows with the lowest values within the specified column.

```JAVASCRIPT
getOccurance(data, "kind")
```javascript
getMin(data, 'cuddlability')
// returns array
```

Returns an object with keys and values for each variation of the category and its occurance.

```JAVASCRIPT
{"dog": 3, "cat": 3}
```
### `Sheetsee.getMax(data, column)`

### Sheetsee.makeColorArrayOfObject(data, colors)
- `data` _array of objects_
- `column` _string_
- Returns _array_

If you use `getOccurance()` and want to then chart that data with d3.js, you'll need to make it into an _array_ (instead of an object) and add colors back in (since the hexcolor column applies to the datapoints in your original dataset and not this new dataset).
Given your **data** and **column** header, this function returns an array of the rows with the highest values within the specified column.

This function takes in your data, as an _object_, and an _array_ of hexidecimal color strings which you define.
```javascript
getMin(data, 'cuddlability')
// returns array of objects
```

```JAVASCRIPT
var kinds = getOccurance(data, "kind")
var kindColors = ["#ff00ff", "#DCF13C"]
### `Sheetsee.getMatches(data, filter, column)`

var kindData = makeColorArrayOfObjects(mostPopBreeds, breedColors)
```
- `data` _array of objects_
- `filter` _string_
- `column` _string_
- Returns _array_

It will return an array of objects formatted to go directly into a d3 chart with the appropriate _units_ and _label keys_, like so:
Takes **data**, a **filter** term to search by within a **column** and returns every row that matches,

```JAVASCRIPT
[{"label": "dog", "units": 2, "hexcolor": "#ff00ff"}, {"label": "cat", "units": 3, "hexcolor": "#DCF13C"}]
```javascript
getMatches(data, 'dog', 'kind')
// returns array of objects
// [{'name': 'coco', 'kind': 'dog'...}, {'name': 'wolfgang', 'kind': 'dog'...},{'name': 'cooc', 'kind': 'dog'...} ]
```

If you pass in an array of just one color it will repeat that color for all items. If you pass fewer colors than data elements it will repeat the sequences of colors for the remainder elements.
### `Sheetsee.getOccurance(data, column)`

### Sheetsee.addUnitsLabels(arrayObj, oldLabel, oldUnits)
- `data` _array of objects_
- `column` _string_
- Returns _object_

If you're using data, the data directly from Tabletop, you'll need to format it before you use the d3 charts. You'll need to determine what part of your data you want to chart - what will be your label, what your charting, and what will be your units, how many of them are there (this should be a number).
Takes **data** **column** header and returns an object with key/value pairs of how often an item occurs in the column.

```JAVASCRIPT
var data = [{"name": "coco", "kind": "dog", "cuddablity": 5}, {"name": "unagi", "kind": "cat", "cuddlability": 0}]
getOccurance(data, 'kind')
// Returns an object
// {'dog': 3, 'cat': 3}
```

For istance, if from our original data above we want to chart the age of each cat, we'll use:
### Math

```JAVASCRIPT
Sheetsee.addUnitsLabels(data, "name", "cuddlability")
```

Which will return an array, ready for the d3 charts:
Don't Forget JavaScript Math! Create variables that are the sums, differences, multiples and so forth of others. Lots of info on that [here on MDN](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Math).

```JAVASCRIPT
[{"label": "coco", "kind": "dog", "units": 5}, {"label": "unagi", "kind": "cat", "units": 0}]
```javascript
var profit09 = Sheetsee.getColumnTotal(data, '2009')
var profit10 = Sheetsee.getColumnTotal(data, '2010')
var difference = profit09 - profit10
```
135 changes: 46 additions & 89 deletions docs/sheetsee-maps.md
View file
Original file line number Diff line number Diff line change
@@ -1,127 +1,84 @@
# Sheetsee-maps
# sheetsee-maps

_[View Demo](../demos/demo-map.html)_
see: [jlord.github.io/sheetsee.js](http://jlord.github.io/sheetsee.js)
demo: [maps](http://jlord.github.io/sheetsee.js/demos/demo-map.html)

Sheetsee.js uses [Mapbox.js](http://mapbox.com/mapbox.js) and [Leaflet.js](http://leafletjs.com/) to make maps of your **points**, **polygons**, **lines** or **multipolygons** (all coordinate based). Details on what that actually looks like [here](http://leafletjs.com/examples/geojson.html).
Sheetsee uses this module to handle maps in your projects. This module uses (and includes) [Leaflet.js](http://leafletjs.com) to make maps of your **points**, **polygons**, **lines** or **multipolygons** (all coordinate based). Details on what that actually looks like [here](http://leafletjs.com/examples/geojson.html). It uses (and includes) [Mustache.js](https://mustache.github.io) templates for marker popups.

### Maps: Polygons and Lines
## Maps: Polygons and Lines

Sheetsee-maps now supports polygons and lines. So long as you have the correct coordinate structure in your cells, Sheetsee will add them to the geoJSON it creates for your maps. More details for coordinates of lines and polygons in geoJSON are [here](http://leafletjs.com/examples/geojson.html), but briefly:
Sheetsee-maps supports polygons and lines; so long as you have the correct coordinate structure in your cells. More details for coordinates of lines and polygons in geoJSON are [here](http://leafletjs.com/examples/geojson.html), but briefly:

A linestring:
**A linestring:**

```
```text
[-122.41722106933594, 37.7663045891584], [-122.40477561950684, 37.77695634643178]
```

A polygon:
**A polygon:**

```
```text
[-122.41790771484375, 37.740381166384914], [-122.41790771484375, 37.74520008134973], [-122.40966796874999, 37.74520008134973],[-122.40966796874999, 37.740381166384914], [-122.41790771484375, 37.740381166384914]
```

A Multipolygon:
**A Multipolygon:**

```
```text
[[-122.431640625, 37.79106586542567], [-122.431640625, 37.797441398913286], [-122.42666244506835, 37.797441398913286],[-122.42666244506835, 37.79106586542567], [-122.431640625, 37.79106586542567]],
[[-122.43352890014648, 37.78197638783258], [-122.43352890014648, 37.789031004883654], [-122.42443084716797, 37.789031004883654], [-122.42443084716797, 37.78197638783258], [-122.43352890014648, 37.78197638783258]]
```

### The Parts
## To Use

You'll create a placeholder `<div>` in your HTML, CSS giving it a size and fire up a map from within `<script>` tags. You can also customize your popup content.
This module is used as a part of [Sheetsee.js](http://jlord.us/sheetsee.js). You can download the [full version](https://github.com/jlord/sheetsee.js/blob/master/js/sheetsee.js) or build your own with a [command line tool](https://github.com/jlord/sheetsee).

## Your HTML Placeholder `<div>`
You'll create a little bit of HTML and then some JavaScript in your HTML to use this. You can customize marker color, popup content and enable/disable clustering in your map.

Create an empty `<div>` in your HTML, with an id (name). Add CSS to give it dimensions
## Methods

```HTML
<div id="map"></div>
```
_CSS_
Here are the functions you can use!

```CSS
#map {width: 500px; height: 500px;}
```
### `Sheetsee.createGeoJSON(data, optionsJSON)`

## Your `<script>` Functions
- **data** _JSON array_ of data
- **optionsJSON** _array_ of strings, spreadsheet column title

Next you'll need to create geoJSON out of your data so that it can be mapped.
If you'd like to just generate geoJSON from a spreadsheet you can use this method.

### Sheetsee.createGeoJSON(data, optionsJSON)
This takes in your spreadsheet **data** in JSON format (which you can get with [Tabletop.js]())and the parts of your data, **optionsJSON**, that you plan on including in your map's popups. These will be column headers in your spreadsheet in an array of strings.

This takes in your **data** and the parts of your data, **optionsJSON**, that you plan on including in your map's popups. These will be column headers in your spreadsheet. If you're not going to have popups on your markers, don't worry about it then and just pass in your data (by default it will use all the row's information).
If you're not going to have popups on your markers, don't worry about it then and just pass in your data (by default it will use all the row's information).

```javascript
var optionsJSON = ["name", "breed", "cuddlability"]
var geoJSON = Sheetsee.createGeoJSON(gData, optionsJSON)
```

It will return an _array_ in the special geoJSON format that map making things love.

```JAVASCRIPT
[{
"geometry": {"type": "Point", "coordinates": [long, lat]},
"properties": {
"marker-size": "small",
"marker-color": lineItem.hexcolor
},
"opts": {},
}}
var optionsJSON = ['name', 'breed', 'cuddlability']
var geoJSON = Sheetsee.createGeoJSON(data, optionsJSON)
```

### Sheetsee.loadMap(mapDiv)

To create a simple map, with no data, you simply call `.loadMap()` and pass in a _string_ of the **mapDiv** (with no '#') from your HTML.
It will return an _array_ in the special [geoJSON format](http://geojson.org) that map making things love.

```javascript
var map = Sheetsee.loadMap("map")
```
### `Sheetsee.loadMap(mapOptions)`

### Sheetsee.addTileLayer(map, tileLayer)
- **object** **required** _object_
- `data` your spreadsheet data array **required**
- `mapDiv` the `id` of the `div` in your HTML to contain the map **required**
- `geoJSONincludes` array of strings of column headers to include in popups
- `template` HTML/[Mustache](https://mustache.github.io/) template for popups
- `cluster` a true/false boolean, do you want your markers clustered
- `hexcolor` pick one color for your markers

To add a tile layer (aka a custom map scheme/design/background) you'll use this function which takes in your **map** and the source of the **tileLayer**. This source can be a Mapbox id, a URL to a TileJSON or your own generated TileJSON. See [Mapbox's Documentation](http://mapbox.com/mapbox.js/api/v1.0.2/#L.mapbox.tileLayer) for more information.
```js
var mapOptions = {
data: data, // required
mapDiv: 'map', //required
geoJSONincludes: ['Name', 'Animal', 'Rating'], // optional
template: '<p>{{Name}}—{{Animal}}—{{Rating}}</p>', // optional
cluster: true, // optional
hexcolor: '#e91e63' // optional
}

```javascript
Sheetsee.addTileLayer(map, 'jllord.n7aml2bc')
```

You can add tiles from awesome mapmakers like [Stamen](http://maps.stamen.com/#toner/12/37.7706/-122.3782) or create your own in Mapbox's [Tilemill](http://www.mapbox.com/tilemill) or [online](https://tiles.mapbox.com/newmap#3.00/0.00/0.00).

### Sheetsee.addMarkerLayer(geoJSON, map, popupTemplate, clusterMarkers)

To add markers, lines or shapes to your map, use this function and pass in your **geoJSON** so that it can get the coordinates and your **map** so that it places the markers there. You can customize what the content in your marker's popup looks like with a **popupTemplate**, which is an ICanHaz.js template in HTML and can reference the column headers you included in your optionsJSON. You can set `true` or `false` (default `false`) to **culsterMarkers** to enable marker clusters on your map.

```javascript
var markerLayer = Sheetsee.addMarkerLayer(geoJSON, map, popupTemplate)
var map = Sheetsee.loadMap("map")
```

Example template:
#### Marker colors

```javascript
var popupTemplate = "<h4>Hello {{name}}</h4>"
```

#### Source from the [map demo](https://github.com/jlord/sheetsee.js/blob/master/demos/demo-map.html):

```JavaScript
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function() {
var gData
var URL = "0Ao5u1U6KYND7dGN5QngweVJUWE16bTRob0d2a3dCbnc"
Tabletop.init( { key: URL, callback: showInfo, simpleSheet: true } )
})

function showInfo(data) {
gData = data
var optionsJSON = ["placename", "photo-url"]
var template = "<ul><li><a href='{{photo-url}}' target='_blank'>"
+ "<img src='{{photo-url}}'></a></li>"
+ "<li><h4>{{placename}}</h4></li></ul>"
var geoJSON = Sheetsee.createGeoJSON(gData, optionsJSON)
var map = Sheetsee.loadMap("map")
Sheetsee.addTileLayer(map, 'jllord.n7aml2bc')
var markerLayer = Sheetsee.addMarkerLayer(geoJSON, map, template)
}
</script>
```
If you create a column title `hexcolor` in your spreadsheet and fill each cell with hex color codes, those will be used to color your markers. If you define a color in `hexcolors` in the options you pass to your map it will override colors in the spreadsheet data.
Loading

0 comments on commit f2a5b27

Please sign in to comment.