Developing Visualizations

Creating jQuery Widgets

Tangelo visualizations can be implemented as jQuery widgets. They extend the base jQuery UI widget class, but otherwise do not need to depend on anything else from jQuery UI.

Visualization Options

Basic Options

  • data - The data associated with the visualization, normally an array.
  • width, height - The width and height of the visualization, in pixels. If omitted, the visualization should resize to fit the DOM element.

Visualization Mapping Options

The following options are optional, but if your visualization is able to map data element properties to visual attributes like size, color, and label, you should use this standard naming convention. If you have multiple sets of visual elements (such as nodes and links in a graph), prefix these attributes as appropriate (e.g. nodeSize, nodeStrokeWidth).

  • size - The size of the visual element as a number of pixels. For example, if drawing a square for each data element, the squares should have sizes equal to the square-root of what the size option returns for each data element.
  • color - The main color of the visual element, specified as a CSS color string.
  • symbol - The symbol to use for the visual element. This should use D3’s standard set of symbol names.
  • label - The label for the visual element (a string).
  • stroke - The color of the stroke (outline) of the visual element specified in pixels.
  • strokeWidth - The width of the stroke of the visual element in pixels.
  • opacity - The opacity of the entire visual element, as a number between 0 to 1.

Accessor Specifications

AccessorSpec

Each visual mapping should take an AccessorSpec for a value. Accessor specifications work much like DataRef specs do in Vega, though they also allow programmatic ways to generate arbitrary accessors and scales.

  • function (d) { ... } - The most general purpose way to generate a visual mapping. The argument is the data element and the return value is the value for the visual property.
  • {value: v} - Sets the visual property to the same constant value v for all data elements.
  • {index: true} - Evaluates to the index of the data item within its array.
  • {field: "dot.separated.name"} - Retrieves the specified field or subfield from the data element and passes it through the visualization’s default scale for that visual property. Unlike Vega, fields from the original data do not need to be prefixed by "data.". The special field name "." refers to the entire data element.
  • {field: "dot.separated.name", scale: ScaleSpec} - Overrides the default scale using a scale specification. Set scale to tangelo.identity to use a field directly as the visual property.
  • {} - The undefined accessor. This is a function that, if called, throws an exception. The function also has a property undefined set to true. This is meant as a stand-in for the case when an accessor must be assigned but there is no clear choice for a default. It is also used when creating Tangelo jQuery widgets to mark a property as being an accessor. Calling tangelo.accessor() with no arguments also results in an undefined accessor being created and returned.

ScaleSpec

A scale specification defines how to map data properties to visual properties. For example, if you want to color your visual elements using a data field continent containing values such as North America, Europe, Asia, etc. you will need a scale that maps North America to "blue", Europe to "green", etc. Vega has a number of built-in named scales that together define the ScaleSpec. In Tangelo, a ScaleSpec may also be an arbitrary function.