From 9fcd018278fbd05b833a9e60f4a425698427710e Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Sat, 8 Feb 2014 19:37:38 -0800 Subject: [PATCH] add --- buildpage.js | 73 ++++++++++++++++++++ css/sss.css | 53 +++++++++++++++ demos/demo-chart.html | 92 +++++++++++++++++++++++++ demos/demo-map.html | 79 ++++++++++++++++++++++ demos/demo-table.html | 123 ++++++++++++++++++++++++++++++++++ docs/about.md | 39 +++++++++++ docs/basics.md | 93 ++++++++++++++++++++++++++ docs/building.md | 42 ++++++++++++ docs/changelog.md | 27 ++++++++ docs/custom-charts.md | 69 +++++++++++++++++++ docs/fork-n-go.md | 32 +++++++++ docs/sheetsee-charts.md | 145 ++++++++++++++++++++++++++++++++++++++++ docs/sheetsee-core.md | 135 +++++++++++++++++++++++++++++++++++++ docs/sheetsee-maps.md | 102 ++++++++++++++++++++++++++++ docs/sheetsee-tables.md | 132 ++++++++++++++++++++++++++++++++++++ docs/tips.md | 96 ++++++++++++++++++++++++++ package.json | 35 ++++++++++ template.hbs | 56 ++++++++++++++++ 18 files changed, 1423 insertions(+) create mode 100644 buildpage.js create mode 100644 css/sss.css create mode 100644 demos/demo-chart.html create mode 100644 demos/demo-map.html create mode 100644 demos/demo-table.html create mode 100644 docs/about.md create mode 100644 docs/basics.md create mode 100644 docs/building.md create mode 100644 docs/changelog.md create mode 100644 docs/custom-charts.md create mode 100644 docs/fork-n-go.md create mode 100644 docs/sheetsee-charts.md create mode 100644 docs/sheetsee-core.md create mode 100644 docs/sheetsee-maps.md create mode 100644 docs/sheetsee-tables.md create mode 100644 docs/tips.md create mode 100644 package.json create mode 100644 template.hbs diff --git a/buildpage.js b/buildpage.js new file mode 100644 index 0000000..4e171ff --- /dev/null +++ b/buildpage.js @@ -0,0 +1,73 @@ +#!/usr/bin/env node + +var glob = require('glob') +var fs = require('fs') +var marked = require('marked') +var hbs = require('handlebars') +var mkdirp = require('mkdirp') +var path = require('path') +var cpr = require('cpr') + +cpr('./demos', './site/demos', function(err, files) { + if (err) return console.log(err) + cpr('./js', './site/js', function(err, files) { + if (err) return console.log(err) + }) +}) + +fs.readFile('readme.md', function(err, file) { + if (err) return console.log(err) + var name = "index" + var content = file.toString() + var html = changeExtensions(marked(content)) + applyTemplate(html, name) +}) + +glob("docs/*.md", function (err, files) { + if (err) return console.log(err) + var filenames = files.map(function(name) { + return path.basename(name) + }) + filenames.forEach(function (file) { + var name = file.split('.md')[0] + var filePath = "./docs/" + var content = fs.readFileSync(filePath + file).toString() + var html = changeExtensions(marked(content)) + applyTemplate(html, name) + }) +}) + +function applyTemplate(html, name) { + var content = {content: html} + if (name === "index") { + content.rootstyle = "." + content.rootdoc = "docs" + } else { + content.rootstyle = ".." + content.rootdoc = "." + } + var file = "template.hbs" + var rawTemplate = fs.readFileSync(file).toString() + var template = hbs.compile(rawTemplate) + var page = template(content) + writeFile(page, name) +} + +function writeFile(page, name) { + if (name === "index") { + return fs.writeFileSync('./site/' + name + '.html' , page) + } + mkdirp('./site/docs', function (err) { + if (err) return console.error(err) + fs.writeFileSync('./site/docs/' + name + '.html' , page) + }) +} + +function changeExtensions(html, name) { + if (name === "index") { + html = html.replace('/\./\.\/', '') + } + var re = /.md$/ + var newHtml = html.replace(/\.md/g, '.html') + return newHtml +} diff --git a/css/sss.css b/css/sss.css new file mode 100644 index 0000000..db232d5 --- /dev/null +++ b/css/sss.css @@ -0,0 +1,53 @@ +/* SHEETSEE STYLES */ +/* These are styles that you'll need to handle for certain elements, +/* or are available to you through elements sheetsee.js generates */ + +/* Table */ + +table {text-align: left; width: 100%} +th {padding: 10px 0px;} +td, text {padding: 3px 20px 3px 0px; font-size: 14px;} +input {background-color: transparent; padding: 0px;} +.tHeader {/* table column header style */} +.tHeader::after {content: " \2193 \2191 "; font-size: 10px; padding-left: 3px;} +.noMatches {margin-left: 20px; font-size: 11px; visibility: hidden;} +#Pagination {background: #eee;} +.pagination-next, .pagination-pre {cursor: hand;} +.no-pag {color: #acacac;} + +/* Overflow for large tables and chart */ + +.container {overflow-x: auto;} +#yourDiv {min-width: 600px} + +/* Bar Chart */ + +.labels text {text-align: right;} +.bar .labels text {fill: #333;} +.bar rect {fill: #e6e6e6;} +.axis {shape-rendering: crispEdges;} +.x.axis line {stroke: #fff; fill: none;} +.x.axis path {fill: none;} +.x.axis text {fill: #333;} +.xLabel {font-family: sans-serif; font-size: 9px;} + +/* Pie Chart */ + +.arc path { stroke: #fff;} + +/* Line Chart */ + +.axis {shape-rendering: crispEdges;} +.x.axis .minor, .y.axis .minor {stroke-opacity: .5;} +.x.axis {stroke-opacity: 1;} +.y.axis line, .y.axis path {fill: none; stroke: #acacac; stroke-width: 1;} +.bigg {-webkit-transition: all .2s ease-in-out; -webkit-transform: scale(2);} +path.chartLine {stroke: #333; stroke-width: 3; fill: none;} +div.tooltip {position: absolute; text-align: left; padding: 4px 8px; width: auto; font-size: 10px; height: auto; background: #fff; border: 0px; pointer-events: none;} +circle {fill: #e6e6e6;} + +/* Map */ + +.leaflet-popup-content li {list-style:none;} + +@media only screen and (-webkit-min-device-pixel-ratio: 2) and (min-width: 320px) and (max-width: 1024px) {} diff --git a/demos/demo-chart.html b/demos/demo-chart.html new file mode 100644 index 0000000..cc94c23 --- /dev/null +++ b/demos/demo-chart.html @@ -0,0 +1,92 @@ + + + + + Sheetsee Chart Demo + + + + + + + + + + +
+

Pennies by State

+

spreadsheet

+
+

View Source // View Documentation

+ + +
+ + + + + diff --git a/demos/demo-map.html b/demos/demo-map.html new file mode 100644 index 0000000..b5489c6 --- /dev/null +++ b/demos/demo-map.html @@ -0,0 +1,79 @@ + + + + + Sheetsee Maps Demo + + + + + + + + + +
+

All Pennies Map

+

spreadsheet

+

+

View Source // View Documentation

+ + + + + + diff --git a/demos/demo-table.html b/demos/demo-table.html new file mode 100644 index 0000000..5340092 --- /dev/null +++ b/demos/demo-table.html @@ -0,0 +1,123 @@ + + + + + Sheetsee Table Demo + + + + + + + + +
+

All Pennies

+

spreadsheet

+ +

+

California Pennies

+ +
+

Pretty Pennies

+
+

View Source // View Documentation

+ + +
+ + + + + + + + + + + diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..55ff664 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,39 @@ +# About + +Sheetsee.js began as a part of my [Code for America](http://www.codeforamerica.org) 2012 Fellowship project, [See Penny Work](http://www.seepennywork.in). The idea and original code was to enable cities to easily publish and maintain themselves their budget data. The original sheetsee.js was built into Wordpress templates so that with the See Penny Work template, you could create pages that you only had to name and they would be populated with maps, charts and tables based on the page name corelating with a project in the spreadsheet. + +In early 2013, after the CfA Fellowship, I recieved a grant from [Mozilla Open News](http://opennews.org/) to pull out the sheetsee.js bits and make it a standalone open source library. That brought us to version 2. + +The present version makes the project modular, customizable and with more maping and table features. + +## Built on top of Tabletop.js +Sheetsee would not exist were it not for [tabletop.js](https://github.com/jsoma/tabletop) a library that handles the messy interactions with the Google Spreadsheets API for you and returns a lovely array of your data. Every instance of Sheetsee begins with running tabletop.js. + +### Sheetsee.js + Mapbox.js + d3.js +Once you've got the data, the meat of Sheetsee comes into play. You can now decide if you want to map, chart or display your data in a table. Sheetsee's table module, **sheetsee-tables**, comes with sorting, filtering and pagination. **Sheetsee-maps** is built ontop of [Leaflet.js](http://leafletjs.com/) and [Mapbox.js](https://www.mapbox.com/mapbox.js/) and allows you to customize colors and popups of points, lines, polygons or multipolygons. Finally, **Sheetee-charts** comes with three basic [d3.js](http://d3js.org) charts: bar, circle and line. It is difficult to make a chart that can suit many types of data, but it is easy to choose your own d3 chart and plug it in to sheetsee. Documentation for creating a d3 module is [here](docs/custom-chart.md). + +## Hacked on Openly +- Sheetsee.js is open source software with a [BSD license](docs/license.md). +- Sheetsee.js is a labor of love by [jlord](http://www.github.com/jlord) ([twitter](http://www.twitter.com/jllord)) with support from [contributors](https://github.com/jlord/sheetsee.js/graphs/contributors). + +## Contact +- File a [new issue](https://github.com/jlord/sheetsee.js/issues/new) for ideas and bug reports. +- If your issue falls specifically with one of the modules, you can file it on its particular repo: + - [sheetsee](http://www.github.com/jlord/sheetsee/issues/new) + - [sheetsee-core](http://www.github.com/jlord/sheetsee-core/issues/new) + - [sheetsee-tables](http://www.github.com/jlord/sheetsee-tables/issues/new) + - [sheetsee-maps](http://www.github.com/jlord/sheetsee-maps/issues/new) + - [sheetsee-charts](http://www.github.com/jlord/sheetsee-charts/issues/new) +- [@jllord](http://www.twitter.com/jllord) on Twitter. + +## Big Time Thanks + +Thanks to [Code for America](http://www.codeforamerica.org) for providing the platform me to build the first version of sheetsee.js for Macon, Georgia. + +Thanks to [Dan Sinker](http://www.twitter.com/dansinker) at [Open News](http://www.mozillaopennews.org/) for having faith and getting things together to make this Code Sprint happen and thanks to [Matt Green](https://twitter.com/whatsnewmedia) at WBEZ for being a willing partner. + +Thanks to [Max Ogden](http://www.twitter.com/maxogden) for emotional support, teaching me JavaScript and answering lots of questions. + +Thanks to all the authors and contributors to Tabletop.js, [Mapbox.js](https://www.mapbox.com/mapbox.js/), [Leaflet.js](http://leafletjs.com/), jQuery, [ICanHas.js](http://icanhazjs.com/) and [d3.js](http://d3js.org). Thanks to Google and the Internet for existing and to all those who've written tutorials or asked or answered a question on StackOverflow. + +Thanks to Mom and Dad for getting a computer in 1996 and the mIRC scripts I started writing that I suppose would eventually lead me here. diff --git a/docs/basics.md b/docs/basics.md new file mode 100644 index 0000000..a073a3a --- /dev/null +++ b/docs/basics.md @@ -0,0 +1,93 @@ +# Spreadsheets as Databases + +Spreadsheets are a great _lightweight_ databases. Google Spreadsheets in particular are easy to work with and share, making this unlike most traditional database setups. That being said, traditional databases are great for bigger, more secure jobs. If you're storing lots and lots and lots of information, or storing sensitive or complex information -- the spreadsheet is not for you. But if you're working on small to medium sized personal or community projects, try a spreadsheet! + +## The Short & Sweet + +1. Link to Sheetsee.js, [tabletop.js](https://github.com/jsoma/tabletop/) and [jQuery](http://www.jquery.org) in your HTML head. +2. Create a place holder `
` in your HTML for any chart, map or table you want to have. +3. Create templates for tables in ` + + + + + +
+ + + + + + +``` + +## Your Data + +![sheetsee](https://raw.github.com/jllord/sheetsee-cache/master/img/spreadsheettodata.png) + +Your Google Spreadsheet should be set up with row one as your column headers. Row two and beyond should be your data. Each header and row becomes an oject in the final array that Tabletop.js delivers of your data. + +![sheetsee](https://raw.github.com/jllord/sheetsee-cache/master/img/nonos.png) + +There shouldn't be any breaks or horizontal organization in the spreadsheet. But, feel free to format the style of your spreadsheet as you wish; borders, fonts and colors and such do not transfer or affect your data exporting. + + [{"name":"Coco","breed":"Teacup Maltese","kind":"Dog","cuddlability":"5","lat":"37.74832","long":"-122.402158","picurl":"http://distilleryimage8.s3.amazonaws.com/98580826813011e2bbe622000a9f1270_7.jpg","hexcolor":"#ECECEC","rowNumber":1}...] + +### Hexcolor + +![sheetsee](https://raw.github.com/jllord/sheetsee-cache/master/img/hexcolors.png) + +You must add a column to your spreadsheet with the heading _hexcolor_ (case insensitive). The maps, charts and such use colors and this is the easiest way to standardize that. The color scheme is up to you, all you need to do is fill the column with hexidecimal color values. This [color picker](http://color.hailpixel.com/) by [Devin Hunt](https://twitter.com/hailpixel) is really nice. #Funtip: Coloring the background of the cell it's hexcolor brings delight! + +### Geocoding + +If you intend to map your data and only have addresses you'll need to geocode the addresses into lat/long coordinates. Mapbox built a [plugin](http://mapbox.com/tilemill/docs/guides/google-docs/#geocoding) + that does this for you in Google Docs. You can also use websites like [latlong.net](http://www.latlong.net/) to get the coordinates and paste them into rows with column headers _lat_ and _long_. + +### Publishing Your Spreadsheet + +![sheetsee](https://raw.github.com/jllord/sheetsee-cache/master/img/publish.png) + +You need to do this in order to generate a unique key for your spreadsheet, which Tabletop.js will use to get your spreadsheet data. In your Google Spreadsheet, click _File_ > _Publish to the Web_. Then in the next window click _Start Publishing_; it will then turn into a _Stop Publishing_ button. + +![sheetsee](https://raw.github.com/jllord/sheetsee-cache/master/img/key.png) + +You should have an address in a box at the bottom, your key is the portion between the = and the &. You'll retrieve this later when you hook up your site to the spreadsheet. _Actually, you technically can use the whole URL, but it's so long..._ + +### CSS + +Sheetsee.js comes with a bare minimum stylesheet, `sss.csss`, which contains elements you'll want to style when using the feature they correspond to. diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 0000000..77822a6 --- /dev/null +++ b/docs/building.md @@ -0,0 +1,42 @@ +# Right-sizing + +You can customize your sheetsee.js build with just the parts you want to use. If you want to just use the full version, you can grab it here at [github.com/jlord/sheetsee.js](https://github.com/jlord/sheetsee.js/blob/master/js/sheetsee.js). + +All bundle comes with [mapbox.js]() and [handlebars.js]() (since both are available on [NPM](http://www.npmjs.org)). Additionally you'll need to also include [tabletop.js](https://github.com/jsoma/tabletop) and [jQuery](http://www.jquery.com) in your HTML head like so: + +```HTML + + +``` + +**To build your Sheetsee you'll need [Node.js](http://www.nodejs.org) and [NPM](http://www.npmjs.org) (the latter comes with the former in most installs) on your computer and a command line.** + +#### Get Node/NPM + +Download Node.js from [nodejs.org/download](http://nodejs.org/download). For most users you can just download the Mac _.pkg_ or Windows _.msi_. Follow the install instructions, both include NPM. Once they're installed, proceed: + +## Install `sheetsee` from NPM +The `sheetsee` (with no '.js') module is the tool for building custom Sheetsee.js builds. Install `sheetsee` globally and then run it within the folder of your soon-to-be sheetsee.js project. + +_Install globally_ + +```bash +npm install -g sheetsee +``` + +_Run from within a project folder_ + +```bash +sheetsee [options] +``` + +Here are the options for the different modules. If you want save the generated file as _sheetsee.js_ then add the `--save` option. + +- `-m` or `-maps` for maps +- `-t` or `-tables` for tables +- `-c` or `-charts` for charts +- `--save` to write out the file* + +_* otherwise, defaults to standardout on your console which you can_ `| pbcopy` + +So for instance, `sheetsee -m -t --save` will build you a Sheetsee.js with the basic **data** functions, the **map** and **tables** sections built in and save it as a file named **sheetsee.js**. Running `sheetsee -m -t | pbcopy` will save the output to your clipboard. diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..7849512 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,27 @@ +### Sheetsee v3 + + +## August 13, 2013 +### Charting Intake + +D3 charts need an array of objects, and something to chart: the thing itself (aka labels) and the corresponding value (aka units). Your data usually contains more than D3 needs to make the chart, so you have to tell it what to chart from your data to chart. + +Previously Sheetsee required you pass your data through a function, `addUnitsAndLabels()` which took in your data and the things you wanted to chart, reformatted your data for you so that you could pass it into one of the d3 charts. This is one more step than actually needs to happen. + +Now Sheetsee just asks for what you want your _labels_ and _units_ to be in the options you give it when calling the chart function. It then sorts the data correctly on the inside of the chart function. Yay, easier! + +```javascript +var options = { + labels: "name", + units: "cuddleability", + m: [60, 60, 30, 150], + w: 600, h: 400, + div: "#barChart", + xaxis: "no. of pennies", + hiColor: "#FF317D" +} +``` + +Thanks @maxogden for the help with this. + +### Started doing this changelong pretty late in the game. diff --git a/docs/custom-charts.md b/docs/custom-charts.md new file mode 100644 index 0000000..53476a6 --- /dev/null +++ b/docs/custom-charts.md @@ -0,0 +1,69 @@ +# Custom Charts + +It's easy to take a [D3.js](http://d3js.org/) chart of your own and use it with Sheetsee.js. If you make it into a module, anyone can use your chart, too! + +Sheetsee charts currently work by taking in some options, like so: + +```javascript +var pieOptions = {labels: "name", units: "units", m: [80, 80, 80, 80], w: 600, h: 400, div: "#pieChart", hiColor: "#14ECC8"} +``` + +The _labels_ represent the actual thing you're charting and _units_ are how many of those things. Margin, width and height are _m, w, h_ and the `
` to build your chart in is _div_. Finally, you can supply a highlight color if you want. + +So, your chart could take the same options, but map them into your D3 code with the correct variables. An example from [maxogden/sheetsee-d3bubble](https://github.com/maxogden/sheetsee-d3bubble): + + +_Append the d3.js code with a map of your sheetsee options_ + +```JavaScript +Sheetsee.d3BubbleChart = function(data, options) { + var tree = {name: "data", children: []} + var groups = {} + + // data needs to look like this: + // var data = { name: "wahtever", children: [ + // { name: "group1", children: [ + // { name: 'bob', size: 3}, + // { name: 'judy', size: 5} + // ]}, + // { name: "group2", children: [ + // { name: 'jim', size: 10}, + // { name: 'bill', size: 5} + // ]} + // ]} + + data.map(function(r) { + var groupName = r[options.group] + groups[groupName] = true + }) + + Object.keys(groups).map(function(groupName) { + var groupMembers = [] + data.map(function(r) { + if (r[options.group] !== groupName) return + groupMembers.push({name: r[options.name], size: r[options.size]}) + }) + tree.children.push({name: groupName, children: groupMembers}) + }) + + // the rest of the code +``` + +_In your HTML call it like so_ + +```JavaScript + +``` + +There are lots of charts to get excited about in the [D3 gallery](https://github.com/mbostock/d3/wiki/Gallery). + +_View the [entire source](https://github.com/maxogden/sheetsee-d3bubble)_ diff --git a/docs/fork-n-go.md b/docs/fork-n-go.md new file mode 100644 index 0000000..d54bd54 --- /dev/null +++ b/docs/fork-n-go.md @@ -0,0 +1,32 @@ +# Fork-n-Go + +A Fork-n-Go project is a project on GitHub that in a few clicks and starting with a fork, gives another user a live website that they control with an easy to swap-for-your-own Google Spreadsheet database. + +To awesome things that make this possible: **Forking** and [**GitHub Pages**](http://pages.github.com). + +On GitHub, a **fork** is a full copy of a repository, on your account, that you can manage and edit. It's done with the click of a button. + +**GitHub Pages** is the hosting service that GitHub provides free to all users, organizations _and_ repositories. This means everyone of these entities or project can have it's own website at a predictable domain: + +- **organizations**: orgname.github.io +- **users**: username.github.io +- **repositories**: username.github.io/repositoryname + +To have a website for a repository all you need is a branch named `gh-pages`. GitHub will then look in that branch for web files and serve them up at the address. + +What all of this means is that Sheetsee.js projects, hosted on gh-pages branches on GitHub, can easily be forked and connected to another spreadsheet giving another user a live website of their own really easily. + +A Fork-n-Go example from my [blog post](http://jlord.us/fork-n-go/) on the topic: + +### Hack Spots Fork-n-Go + +I made this website to collect hack spots all over the world from friends and friends of friends (the spreadsheet is wide open, so you can add some, too!). It’s using sheetsee to power the table, map and other elements of the page. Its source is in this repo, with just a gh-pages branch. To create an instance of this site for yourself all you need to do: + +- Create a Google spreadsheet with the same headers (just copy and paste header row from the original). Click File > Publish to Web, then Start Publishing. +- Fork the original repository. +- Edit the HTML file directly on GitHub.com to replace the original spreadsheet’s unique key with your spreadsheet’s key (found in your spreadsheet’s URL). +Commit your change. + +Now you have the same site connected to a spreadsheet that you manage — it’s live and can be found at yourGitHubName.github.io/theReposName. + +![forkcommit](http://jlord.s3.amazonaws.com/wp-content/uploads/forkcommit1.png) \ No newline at end of file diff --git a/docs/sheetsee-charts.md b/docs/sheetsee-charts.md new file mode 100644 index 0000000..a02ea04 --- /dev/null +++ b/docs/sheetsee-charts.md @@ -0,0 +1,145 @@ +# Sheetsee-charts + +_[View Demo](/demos/demo-chart.html)_ + +Sheetsee.js provides three [D3.js](http://d3js.org/) chart options to use with your spreadsheet data: a bar chart, line graph and pie chart. You can also use a custom D3 chart with Sheetsee, read about that [here](custom-charts.md). + +## Make a Chart + +Each chart requires your data be an _array of objects_, with objects containing `label` and `units` key/value pairs. + +Experiment with the charts to find the correct size your `
` will need to be to hold the chart with your data in it nicely. + +You can also make your own D3 chart in a separate .js file, link to that in your HTML head and pass your data on to it after Tabletop.js returns. Information [here](custom-charts.md) on using your own chart. + +### Bar Chart + +To create a bar chart you'll need to add a placeholder `
` in your HTML with an id. + +```HTML +
+``` + +In your CSS, give it dimensions. + +```CSS +#barChart {height: 400px; max-width: 600px; background: #F8CDCD;} +``` + +You'll also have these CSS elements to style however you'd like: + +```CSS +.labels text {text-align: right;} +.bar .labels text {fill: #333;} +.bar rect {fill: #e6e6e6;} +.axis {shape-rendering: crispEdges;} +.x.axis line {stroke: #fff; fill: none;} +.x.axis path {fill: none;} +.x.axis text {fill: #333;} +.xLabel {font-family: sans-serif; font-size: 9px;} +``` + +In a ` +``` diff --git a/docs/sheetsee-tables.md b/docs/sheetsee-tables.md new file mode 100644 index 0000000..370e3c2 --- /dev/null +++ b/docs/sheetsee-tables.md @@ -0,0 +1,132 @@ +# Sheetsee-tables + +_[View Demo](/demos/demo-table.html)_ + +With this module you can create tables of your data that are sortable, searchable and paginate-able. + +You'll need a placeholder `
` in your html, a ` +``` + +#### Your ` +``` + +To create another table, simply repeat the steps except for `initiateTableFilter()` + +```HTML +
+ + +``` + +Learn more about the things you can do with [ICanHaz.js](http://icanhazjs.com). + +### Sheetsee.makeTable(tableOptions) + +You pass in an object containing: + +- `data` your data array +- `pagination` how many rows displayed at one time, defaults to all +- `tableDiv` the
placeholder in your HTML +- `filterDiv` the `
` containing your `` filter if using search + +```javascript +var tableOptions = { + "data": gData, + "pagination": 10, + "tableDiv": "#fullTable", + "filterDiv": "#fullTableFilter" + } +Sheetsee.makeTable(tableOptions) +``` + +#### Pagination + +If you do not put in a number for pagination, by default it will show all of the data at once. With pagination, HTML will be added at the bottom of your table for naviagtion, which you can style in your CSS: + +_HTML_ + +```HTML + +``` + +_CSS_ + +```CSS + +``` + +## Table Filter/Search + +If you want to have an input to allow users to search/filter the data in the table, you'll add an input to your HTML. Give it an id and if you want, placeholder text: + +```javascript + +``` + +### Sheetsee.initiateTableFilter(tableOptions) + +You will then call this function with your `tableOptions` to make that input live and connected to your table: + +```javascript +Sheetsee.initiateTableFilter(tableOptions) +``` + +It will connect that input to your data as well as inject this HTML for a button, which you can style yourself in your CSS: + +```HTML +Clear +no matches +``` + +_[View Demo](/demos/demo-table.html)_ diff --git a/docs/tips.md b/docs/tips.md new file mode 100644 index 0000000..e2f672e --- /dev/null +++ b/docs/tips.md @@ -0,0 +1,96 @@ +# Tips + +A few things to think about beyond charts, maps and tables. + +## ICanHaz.js + +You can use templates for more than just tables. Use them to create lists `ol`, `ul`; array of images... You'll need a placeholder `
` in your HTML, a ` +``` + +_Script_ + +```JavaScript + +``` + +_non-table example output_ + +![lib](http://jlord.s3.amazonaws.com/wp-content/uploads/lending-ss.png) + +## Query Strings + +If your spreadsheet contains address information, using templates (Sheetsee.js uses a form of Mustache), you can embed those elements into a query string (aka a search URL) like Google Maps URL or Yelp. If you search for a location in Google Maps, you'll notice it creates a URL for that search. + +So, if you have information in your spreadsheet that would go inside a query string, make a template for inserting them into a link on your page. + +The basic elements are: a spreadsheet with address info + HTML template to create the query string. + +The Sheetsee [Hack-Spots](jlord.github.io/hack-spots) is an does such a thing. Here is the spreadsheet, with address information + +![img](http://jlord.s3.amazonaws.com/wp-content/uploads/Screen-Shot-2013-09-15-at-6.49.19-PM.png) + +In the HTML template for the table on the [Hack-Spots](jlord.github.io/hack-spots) page, the button’s links look like this: + +```HTML +View in Google Maps +Find on Yelp +``` +Here is the exact line of code on GitHub. + +We’re inserting the address, city, and state details from the spreadsheet into the structure of a query string for Google maps and Yelp. You can figure out the query string of a service by just using it (type in an address in Google Maps) and looking at the resulting URL. + +With a some CSS and such, the resulting website has a table with the hack spots and a button for viewing in Google Maps or Yelp: + +![img](http://jlord.s3.amazonaws.com/wp-content/uploads/Screen-Shot-2013-09-15-at-6.43.54-PM.png) + +When the page builds, it creates the correct link for each row. When someone clicks on the buttons it takes them directly to the Google Map search result for that address. BAM! + +## IFTTT + +[Ifttt.com](http://www.ifttt.com) offers lots of options sending data from your actions (Twitter, Instagram, GitHub, Pocket...) to Google Spreadsheets. + +## Row Numbers + +When Tabletop.js returns your spreadsheet data, it adds a key/value of `rownumber`. This is great to use when you need to uniquely match or find a row in your data. + +## Images + +Your spreadsheet can contain URLs to images which you can use to display the images on the page you build. Your template would look something like this: + +```HTML + +``` + +## Data as Classes + +You can use your data as classes to style with CSS. For instance, if you had data about recipes and a column called 'Taste' that contained either 'savory' or 'sweet'. In a table of the recipes you could do something like: + +```HTML + +``` + +Then in your CSS: + +```CSS +td .savory {} +td .sweet {} +``` diff --git a/package.json b/package.json new file mode 100644 index 0000000..28dea23 --- /dev/null +++ b/package.json @@ -0,0 +1,35 @@ +{ + "name": "sheetsee.js", + "version": "0.0.0", + "description": "sheetsee.js documentation", + "main": "buildpage.js", + "directories": { + "doc": "docs" + }, + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "repository": { + "type": "git", + "url": "https://github.com/jlord/sheetsee.js.git" + }, + "keywords": [ + "spreadsheet", + "data", + "visualize", + "google" + ], + "author": "jlord", + "license": "BSD-2-Clause", + "bugs": { + "url": "https://github.com/jlord/sheetsee.js/issues" + }, + "dependencies": { + "glob": "~3.2.8", + "marked": "~0.3.1", + "handlebars": "~1.3.0", + "mkdirp": "~0.3.5", + "path": "~0.4.9", + "cpr": "~0.1.1" + } +} diff --git a/template.hbs b/template.hbs new file mode 100644 index 0000000..18c49bd --- /dev/null +++ b/template.hbs @@ -0,0 +1,56 @@ + + + + + Sheetsee.js + + + + + + + + + + + +
+ {{{content}}} + + +
+ + +