summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md151
1 files changed, 145 insertions, 6 deletions
diff --git a/README.md b/README.md
index 53e34ee..d024da9 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,152 @@
+# Dashing!
+
+<!-- CI status? -->
+
+## Introduction
+
+Dashing is a framework for building web-based dashboards.
+
+Features:
+
+ - Custom widgets! Built using whatever HTML/Coffeescript wizardry you posses
+ - Multiple dashboards! You can have many different views all hosted by the same app
+ - Shareable widgets!
+ - ...
+
+## Installation and Setup
+
+ 1. Install the gem from the command line:
+
+ ```gem install dashing```
+
+ 2. Generate a new project:
+
+ ```dashing new sweet_dashboard_project```
+
+ 3. Change your directory to ```sweet_dashboard_project``` and start the Dashing
+
+ ```dashing start```
+
+ 4. Point your browser at [localhost:3000](http://localhost:3000)
+
+## Building a dashboard
+
+```main.erb``` contains the layout for the default dashboard which is accessible at ```/```. You can add additional dashboards with ```COMMAND new_view``` which creates a ```new_view.erb``` file in ```dashboards/```. That new view will be accessible at ```localhost:3000/new_view```
+
+Widgets are represented by a ```div``` with ```data-id``` and ```data-view``` attributes. For example:
+
+```HTML
+<div data-id="sample" data-view="SweetWidget"></div>
+```
+
+represents a dashboard with a single widget.
+
+The ```data-id``` is used to set the widget_id which will be used when we push data to the widget. widget_ids can be shared across dashboards.
+
+```data-view``` specifies the type of widget what will be used. This field is case sensitive and must match the name of coffeescript class. See making your own widget.
+
+Getting the style and layout right when you have multiple widgets is hard, that's why we've done it for you. By default Dashing uses [masonry](http://masonry.desandro.com/) to produce a grid layout.
+
+#### Example
+```HTML
+<ul class="list-nostyle clearfix">
+ <li class="widget-container">
+ <div data-id="widget_id1" data-view="MyWidget"></div>
+ </li>
+ <li class="widget-container">
+ <div data-id="widget_id2" data-view="MyWidget"></div>
+ </li>
+ <li class="widget-container">
+ <div data-id="widget_id3" data-view="MyWidget"></div>
+ </li>
+</ul>
+```
+
+## Making you own widget
+
+To make your own run ```dashing generate sweet_widget``` which will create template files in the ```widget/``` folder or your project.
+
+### sweet_widget.html
+
+Contains the HTML for you widget.
+
+#### Example
+```html
+<h1 data-bind="title"></h1>
+
+<h3 data-bind="text"></h3>
+````
+
+### sweet_widget.coffee
+
+#### Example
+```coffeescript
+class Dashing.SweetWidget extends Dashing.Widget
+ source: 'widget_text'
+
+ onData(data) ->
+ #stuff?
+```
+
+### sweet_widget.scss
+````scss
+$text_value-color: #fff;
+$text_title-color: lighten($widget-text-color, 30%);
+
+.widget-text {
+ .title {
+ color: $text_title-color;
+ }
+ .p {
+ color: $text_value-color:
+ }
+}
+```
+
+## Getting data into Dashing
+
+### Jobs
+
+Dashing uses [rufus-scheduler](http://rufus.rubyforge.org/rufus-scheduler/) to schedule jobs. You can make a new job with ```things job super_job``` which will create a file in the jobs folder called ```super_job.rb```.
+
+Use ```send_event('WIDGET_ID', {text: SAMPLE_DATUMS})```
+
+#### Example
+
+```ruby
+# :first_in sets how long it takes before the job is first run. In this case, it is run immediately
+SCHEDULER.every '1m', :first_in => 0 do |job|
+ send_event('widget_id', {text: "I am #{%w(happy sad hungry).sample}"})
+end
+```
+
+### Push
+
+You can also push data directly to your dashboard! Post the data you want in json to ```/widgets/widget_id```. You will also have to include your auth_token (which can be found in ```config.ru```) as part of the json object.
+
+#### Example
+```bash
+curl -d '{ "auth_token": "YOUR_AUTH_TOKEN", "value": 100 }' http://localhost:3000/widgets/synergy
+```
+
+or
+
+```ruby
+HTTParty.post('http://ADDRESS/widgets/widget_id',
+ :body => {
+ auth_token: "YOUR_AUTH_TOKEN",
+ text: "Weeeeee",
+ }.to_json)
+```
+
+## Licensing
+
+This code is released under the MIT license. Please read the MIT-LICENSE file for more details
+
TODO
====
-- fix textfield style
- tests
-- Create a better readme!
-- Add data fetching capabilities
-- Turn into its own gem
-- Come up with a default style
-- Create example widgets
- investigate if Dir.pwd is the best approach to get the local directory
- Create githubpages
- Open source!