-### Kraken Dataset Spec ###
+### Kraken Datasource Spec ###
-# Describes the format of dataset json/yaml files for use in the Kraken chart UI.
+# Describes the format of datasource json/yaml files for use in the Kraken chart UI.
# Reminder: the project transparently compiles any .yaml files requested as .json
# at request time -- you're welcome to generate them in either form.
# TODO: Thrift/Avro schema
-id : Unique identifier for this dataset. This file should be named `{id}.{ext}`
- and live in the data directory alongside the data file.
-name : Human-friendly name for the dataset.
-format : Data format. Valid: csv, json. (Maybe in the future: yaml, xml, etc.)
-url : Canonical URL for the dataset's data file: /data/
+id : Unique identifier for this datasource. This file should be named `{id}.{ext}`
+ and live in the data directory alongside the data file.
+name : Human-friendly name for the datasource.
+shortName : A shorter version of the datasource name for use in the UI.
+title : Title for use on the graph of the data in some chart-types.
+subtitle : A subtitle for use on the graph of the data in some chart-types.
+desc : Description of the datasource.
+notes : Notes about the datasource, particularly about definitions, data integrity,
+ data normalization, data generation, etc.
-### Timespan and quanta covered by this dataset
+format : Data format. Valid: csv, json. (Maybe in the future: yaml, xml, etc.)
+url : Canonical URL for the datasource's data file, eg: /data/datasources/{id}.csv
+
+
+### Timespan and quanta covered by this datasource
timespan :
- start : Start of the dataset, eg: 2012/01/01T00:00:00 or 2012/01/01 or 1325404800
+ start : Start of the data, eg: 2012/01/01T00:00:00 or 2012/01/01 or 1325404800
All dates should be seconds-since-the-epoch, or ISO-8601 formatted: YYYY/MM/DDThh:mm:ss.s
See also: http://www.w3.org/TR/NOTE-datetime
And: http://blog.dygraphs.com/2012/03/javascript-and-dates-what-mess.html
- end : End of the dataset, eg: 2012/02/01T00:00:00 or 2012/02/01 or 1328083200
+ end : End of the data, eg: 2012/02/01T00:00:00 or 2012/02/01 or 1328083200
step : Amount of time between elapsed between each row, measured in seconds, eg: 86400
### Metadata about the Datatypes
# Note: 'columns' can also be supplied as a list of { label, type } objects instead of two lists. (TODO)
columns :
- labels : List of the column-names in order. (Future optimization: the date column could
+ labels : List of the column-names in order. (Future optimization: the date column could
be omitted if the data is sorted and contains no gaps -- each datapoint is exactly
timespan.step apart, and none are missing.)
types : List of the column datatype-names in order. Valid type names: date, float, int.
# todo
-## bugs
-
-
-
-
-## ux
-
-- [DataSource UI]
- - Sources Selector: list datasets via YAML metadata descriptor files (/data/list -> UI)
- - Metric Selector: select metrics out of a dataset
- - (Date range selector & scrubber?)
- - Metric Presentation: color, label, formatting, and transform (low-pri -- can hardcode for now)
-- [Graph Edit UI]
- - Add option for a "Benchmark Value" on the graph
- - Annotations
- - Tag options with "advanced", make modal UI
- - List tags to toggle all matching options
- - (work beyond here is low-pri)
- - non-lib option: redraw graph on page resize
- - Typeahead filter box for names/tags
- - Sort by Importance, Tag, Lexical
- - Collapse/uncollapse all
- - Reset all options to defaults
- - Outline modified options
- - Save to server
-
-### later
-
-- [Graph Edit UI]
- - Filter/Sort attributes, datasets, etc
- - Outline all changed options
-- Dashboard
- - How should they be laid out?
-- Stacked bar charts seem to be something a lot of us are into, but dygraphs won't be doing that. (tho d3 does)
-- Sort by custom tag order
-
-
-## features
-
-- Graphs should have tags
-- Ability to merge & filter datasets
-- Discoverable & Self-Describing Data Sources
- - ToC endpoint
- - Metadata endpoint for each datasource/dataset
- - (Both could be static files -- "endpoint" just means a convention to the URLs)
-- Persist graph settings as a preset on the server
-- Dashboard Configuration
- - list of graphs w/ configuration identifiers
+### general
+- Library for undo/redo
+- LocalStorage for unsaved changes, so accidental refresh (etc) doesn't lose changes
+
+
+### Dashboard
+- Sparklines
+- Combine graphs
+- Featured Graphs (reportcard)
+- Browse Graphs
+ - New
+ - Recently Edited
+ - Popular
+- Graph tags as categories (searchable?)
+- Users & Auth
+- "Fork this Graph"
+- User-relative slugs? `/user/:user/graph/:graph.slug/`
+
+
+### View for show Graph
+- Embedding: iframe URL, `.js`
+
+
+### Edit UX
+- Info & Alert message boxes, eg: save, load success/error, validation
+- Visual indicator graph is unsaved or has changes
+- Fields in `info` tab for graph identifiers:
+ - short URL (slug only)
+ - full URL (no slug -- all options)
+ - embed code (iframe with .js pointer)
+- Loading Indicator:
+ - Render UI at start with `loading` mode, showing placeholders and indicator
+ - Activate Loading Spinner post-ready when waiting
+- Keyboard Shortcuts:
+ - Move between tabs
+ - Zoom/pan chart
+ - Focus on form?
+ - Manipulating datasources and other complex forms (up, down, select, back, etc)
+- Standard-view layout
+- Fixed Chart at top?
+- Bold/darken numeric portion of formatted legend? Decrease size, change color of KMB suffix?
+- Load dygraph chart-spec on demand
+
+
+### GraphModel
+- Use dataset name for Graph.name if empty
+- Cascade dataset chart-type defaults before `root`?
+- toURL():
+ - Slug only if not `.isNew()`
+ - Filter `id` out
+ - Diff with last saved state
+ - validation: check `slug` is unique if unsaved
+ - Do not include `undefined` & empty values
+ - Compact some components (w/ collapse and expand methods):
+ - `options` -> `o`
+ - `dataset` -> `d`
+- Graph Options (non-chart options):
+ - `palette`: String | { name:String, length:Number }
+ - `name`: Infer colors from ColorBrewer + index
+ - `columns`: Use this as column-length
+ - Zoom range: `dateWindow`
+ - redraw graph on page resize
+- Backbone.Router, history w/ undo/redo
+- "Save as PNG" link; post PNG to server
+
+
+### Data UI
+- CSV cache: Load and parse
+- Sources Selector: list datasets via YAML metadata descriptor files (`/datasources/list` -> UI)
+- Metric Selector: select metrics out of multiple dataset & graph together
+- Metric Presentation:
+ - label, color
+ - Date range selector & scrubber?
+ - visible, disable
+ - transform
+ - legend, label format
+ - axes
+- Timespan:
+ - Step compat check
+ - Use `step` to format date legend/labels (`1mo`? omit day, eg `2012/01`)
+ - Date picker
+- Graph Options:
+ - `palette`: String | { name:String, length:Number }
+ - `name`: Infer colors from ColorBrewer + index
+ - `columns`: Use this as column-length
+ -
+- Apply `meta.chart.{type, options}`
+- Should data files have timespan in name?
+- Add `shortName`, `desc`, `title` to metadata files
+
+
+### Charting
+- Finish ChartType & Chart wrapper
+- Benchmark line on the graph
+- Per-series styles
+- Meta-metrics:
+ - Year-over-year
+
+
+### Annotations
+- Click chart to add an Annotation
+- Props:
+ - label/title
+ - desc/text: markdown
+ - location:
+ - dataset, value
+ - series, x
+ - disabled
+ - visible?
+ - dygraphs:
+ - cssClass
+ - attachAtBottom
+ - tickHeight
+ - symbol:
+ - letter: auto from `title` by default
+ - icon: replace letter with `<i class="icon-foobar"/>`
+- Actions:
+ - CRUD
+ - Enable/Disable
+ - Clear All
+ - Ordering?
+- Events:
+ - show
+ - hide
+- UI for icon?
+
+
+### Graph Options UI
+- `tags.json` to describe colors, sorting, ignored-tags
+- Outline modified
+- Fix UI pill color when expanded
+- Filter:
+ - by major Categories: labels, grid, axes, display, interactivity
+ - by Tag (collapsable box)
+ - via typeahead box: names + tags
+- Sort
+ - by: Modified, Importance, Tag, Lexical
+ - Use `categoryRows`
+- Derived Options:
+ - visibility
+ - colors
+ - dateWindow
+ - file
+ - width, height
+- Buttons: Reset {all,visible} to defaults
+
+
+### Server-side Persistence
+- Prompt to override slug
+- Generate UUID for `Graph.id`
+
+
+### Backbone Base
+- Subview convention for attaching the element: `@$el.find '.____-subview' .replaceWith subview.el`
+
projects / kraken-ui.git / commitdiff