From f2a5b2775f3ada2d82c24d896c223481f69a2b8f Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Sun, 19 Mar 2017 18:06:24 -0400 Subject: [PATCH] Update module docs --- docs/sheetsee-core.md | 163 +++++++++++++++++++--------------------- docs/sheetsee-maps.md | 135 ++++++++++++--------------------- docs/sheetsee-tables.md | 116 +++++++++++----------------- 3 files changed, 169 insertions(+), 245 deletions(-) diff --git a/docs/sheetsee-core.md b/docs/sheetsee-core.md index 1d76b339..d1be4772 100644 --- a/docs/sheetsee-core.md +++ b/docs/sheetsee-core.md @@ -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 ``` diff --git a/docs/sheetsee-maps.md b/docs/sheetsee-maps.md index 4e2d383d..50c53f8b 100644 --- a/docs/sheetsee-maps.md +++ b/docs/sheetsee-maps.md @@ -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 `
` in your HTML, CSS giving it a size and fire up a map from within ` -``` +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. diff --git a/docs/sheetsee-tables.md b/docs/sheetsee-tables.md index d12a07d8..2d4261be 100644 --- a/docs/sheetsee-tables.md +++ b/docs/sheetsee-tables.md @@ -1,8 +1,8 @@ -# Sheetsee-tables +# sheetsee-tables -With this module you can create tables of your data that are sortable, searchable and paginate-able. +Sheetsee uses this module to make tables. With this module you can create tables of your spreadsheet data that are sortable, searchable and paginate-able. -You'll need a placeholder `
` in your html, a ` -``` - -To create another table, simply repeat the steps above (abreviated here below). - -_HTML_ -```HTML -
- -``` -_Template_ - -```JavaScript - ``` - -_JavaScript_ - -```JavaScript - -``` - -Learn more about the things you can do with [ICanHaz.js](http://icanhazjs.com). - -_[View Demo](/demos/demo-table.html)_