Transforms & Client-Side Routing

[aalpern]

Basic layout transforms are in place on the client side - having them as part of the JavaScript model works best. Right now a layout class is super-simple; it takes a dashboard item (such as the definition) and returns another dashboard item with the contents re-arranged. Number of column switching is handled this way.

Notes

Rename layouts to transforms - the one convention can cover basic re-layout (i.e. column switching) and drill-downs, where we take one graph and get more detail on it.

Transformed items and Queries

Dashboard items currently have a query_name to reference a query stored in the dashboard_definition.

• That needs to optionally have an immediate query object instead, as some of the transforms will need to transform the query as well as the presentation (i.e. time-shifting, expanding to multiple time scales, etc...
• Oh, that means that ds.models.data.Query needs to have options from/until fields as well) for showing the same metric over multiple time scales

  Usage

• Add an attribute to transforms indicating whether they apply to individual items or dashboards? (i.e. purely layouts vs. drilldowns)
• Optionally attach transform instance with parameters to dashboards? One way of limiting the available transforms to only those that make sense.

  Management

• central registry of transforms for populating action menus
• still need a central component (like current DashboardManager but cleaner) to handle transforms, and managing browser history API.
  • Indicate transforms in URL hash? Need to be permalinkable
  • will probably need a client side router component for sanity
  • will need to make individual item IDs persistent again, for permalinking. Generate in API on save only if they don't exist already, not at render time.

    Navigation

In order to display a proper breadcrumb navigation trail for drilldowns, we're going to need to move the breadcrumb template client-side as well.

(at this point, it looks like almost all the UI will client-side eventually, leaving the server side code to handle API, persistence, and serving static assets).

[aalpern]

Client Side Routing

Client side routing uses the HTML5 browser history API to integrate in-page state changes with the browser history (i.e. "the back button"). Given the in-page nature of transforms, it's necessary to allow linking to a transform (and for generate sanity -- after digging in to a transform, the back button should not take the user back to the dashboard list, but to the pre-transform state)

Routes

Here are some random noodlings on what client-side routed URLs should look like:

Base dashboard URL:

/dashboards/3/detailed-overview
/dashboards/:id/:slug

Time-shifting first graph:

/dashboards/3/detailed-overview/d3/transform/time_shift

General transform routing:

/dashboards/:id/:slug/:item-id/transform/:transform-name?from=:from-time

Router Components

• YUI Router has an excellent explanation of client-side routing, and may be a good candidate too.
• crossroads.js
• director is one strong possibility
• page.js looks particularly strong in its ability to chain asynchronous handlers (i.e. for actions that require multiple AJAX calls). See also Building SPAs with page.js

[aalpern]

Limitations

• At least initially, we should restrict the ability to apply transforms to one deep. While it's vaguely possible that arbitrarily composable transforms might be useful, they're probably much more likely to be confusing and bug-ridden.

Tasks

• [x] MUST support direct-linking to a transform. On dashboard page load, check current window.location URL and apply any transform indicated there. A router component can probably handle most of that mechanism for us
• [x] refresh button should refresh the transform if a transform is current, not reload the full dashboard
• [x] disable and/or hide the transform menu items when rendering a transform
• [x] provide an in-page button to return to the full dashboard, for accessing the full dashboard when there is no browser history for it (i.e. after following a permalink to a transform). this icon has the right "up and out" feel to it

We can continue to control visibility using data attributes; can effectively have multi-valent visibility attribute using CSS substring matching operators:

[data-ds-visible-in-mode*="transform"] for strict substring matching, or use the ~= operator for whitespace-separated matching.

• [x] Only allow one mode active at a time. It's currently possible to enter edit mode, then display mode. Then you can't exit edit mode without first exiting display mode, because the toolbar's been hidden.
• transform mode
  • [x] hide edit button in toolbar
  • [x] hide transform menu items
  • show back-to-dashboard button in toolbar
  • would be appropriate to disable range picker for some transforms, but probably messy
• edit mode
  • [x] disable transform menu items
  • [x] disable display mode button

[aalpern]

The behavior described here is now functionally pretty much complete, but the implementation is pretty ad-hoc and a bit messy. Going to leave this open for a while, or punt it to R2 or R3 for later cleanup. I think nearly all the UI needs to come client-side so it's all routed.