From 9eb9ade9d9085676ad2786830a2e7be49537377f Mon Sep 17 00:00:00 2001 From: dsc Date: Sun, 8 Apr 2012 22:02:04 -0700 Subject: [PATCH] Updates todo, adds docs. --- docs/internals/backbone-base.md | 6 + docs/internals/data-ui.md | 2 + docs/internals/dataset-spec.yaml | 30 ++++-- docs/later.md | 20 ++++ docs/notes.md | 9 ++- docs/todo.md | 203 +++++++++++++++++++++++++++++--------- 6 files changed, 209 insertions(+), 61 deletions(-) create mode 100644 docs/internals/backbone-base.md create mode 100644 docs/internals/data-ui.md create mode 100644 docs/later.md diff --git a/docs/internals/backbone-base.md b/docs/internals/backbone-base.md new file mode 100644 index 0000000..78d1f51 --- /dev/null +++ b/docs/internals/backbone-base.md @@ -0,0 +1,6 @@ +# Backbone Base classes + +- Properties, Methods +- Subclass customization +- Call flow +- Events diff --git a/docs/internals/data-ui.md b/docs/internals/data-ui.md new file mode 100644 index 0000000..944ebfa --- /dev/null +++ b/docs/internals/data-ui.md @@ -0,0 +1,2 @@ +# Data UI + diff --git a/docs/internals/dataset-spec.yaml b/docs/internals/dataset-spec.yaml index a2f1e95..b113386 100644 --- a/docs/internals/dataset-spec.yaml +++ b/docs/internals/dataset-spec.yaml @@ -1,31 +1,39 @@ -### 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. diff --git a/docs/later.md b/docs/later.md new file mode 100644 index 0000000..59c494f --- /dev/null +++ b/docs/later.md @@ -0,0 +1,20 @@ +# todo 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 + +- 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 + diff --git a/docs/notes.md b/docs/notes.md index 13cad96..10c7463 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -1,6 +1,12 @@ # notes -- [Name Ideas] GraphKit, VisKit, VisHub +## GraphKit + + + + + +## Data UI ## Value Formatter @@ -29,4 +35,3 @@ type ::= Use type-specific formatting: screen -dr kraken ./lib/server/server.co | tee -a logs/kraken.log - diff --git a/docs/todo.md b/docs/todo.md index 754b112..b421a5e 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -1,53 +1,160 @@ # 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 `` +- 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` + -- 1.7.0.4