=========================
Developing Visualizations
=========================

Extend jQuery Widget
--------------------

Tangelo visualizations are 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.
*   ``{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.

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.

Callbacks
---------

Data Callbacks
~~~~~~~~~~~~~~

*   `enter`
*   `update`
*   `exit`

Interaction Callbacks
~~~~~~~~~~~~~~~~~~~~~

*   `click`
*   `dblclick`
*   `mouseover`
*   `mouseout`

Behavior Callbacks
~~~~~~~~~~~~~~~~~~

*   `select`
*   `focus`
*   `toggle`
