Visual is a Javascript library for data visualization developed by the Statistical Institute of Catalonia (Idescat). It is based on popular open source solutions. Visual offers a simple interface that encapsulates the complexity of these solutions for the most common chart types.

Not a web developer? Don't worry: you can try Visual online by simply filling in fields in the Visual Maker.

• Supported visualizations
• Test
• Configuration
• Installation
• The Visual Object
• Maps
• Public functions
• Dependencies
• Known limitations
• How to contribute

Supported visualizations

Visual currently supports the following visualizations:

• Distribution of a categorical variable (vertical bar chart): bar
• Ranking (horizontal bar chart): rank
• Pie (circle chart): pie
• Stacked/non-stacked time series (vertical bar chart): tsbar
• Time series (line chart): tsline
• Population pyramid: pyram
• Scatter plot (XY chart): xy
• Choropleth map: cmap

Test

Download the full source and tests and then start your browser and try the examples in the test folder. Or play with the Visual Viewer included in the package. Or build your own charts and store them online with the Visual Maker.

Configuration

Edit visual.setup.js and visual.css to meet your needs. You might need to provide your own maps and adapt the VisualJS.func.legend function inside visual.maps.js (see the maps folder).

Installation

Visual allows three running modes: webpage (recommended), simple and manual. See the examples in the test folder.

Not ready to install? You can try Visual online: visit the Visual Maker.

Webpage mode

In webpage mode, the visualization is the only content on an html5 page. Use the webpage template to build your page. To embed the visualization, use an iframe pointing to your page (example).

If you don't want to install Visual in your server, use the CDN template to build your page (example).

Simple mode

In simple mode, the visualization is embedded in a page using the VisualJS.iframe function. Use the simple template to build your page. To embed the visualization, include the visual.js and visual.setup.js files and use a script tag with a unique id and invoke VisualJS.iframe passing a Visual Object (with the same id as the script tag) and a CSS file (or CSS rules) (example).

Manual mode

In manual mode, the visualization is directly embedded in a page. Use the manual template as an example. If you are embedding a single visualization, include the same javascripts as in the webpage template (example).

If you are embedding more than one visualization in the page, LazyLoad will only include the javascripts needed for the first visualization in the visual function. Instead, include all the needed javascripts manually. Do not include LazyLoad. You will also need to specify an id and its size (in the fixed property: [width, height]) for each visualization.

The Visual Object

Visual is executed by passing a Visual Object, or an array of Visual Objects, to the visual function.

visual( {...} )

If you already have a defined visual function, you can run Visual like this:

VisualJS.load( {...} )

The Visual Object accepts the following properties:

General properties

lang

String ("ca", "es", "en"). Language. Default (ca) is set in visual.setup.js.

title

String. Text of first level title.

footer

String. Text of footer. Since version 1, an array of strings is also accepted.

geo

String. Geographical area.

time

String (optional) or array of strings (required). Time period or periods.

Visual will treat the following string time formats using the quarter, month and template properties in visual.setup.js: "20131" (first quarter of 2013) and "201301" (January 2013). Any other time pattern will be displayed untreated.

autoheading

Boolean. This determines whether the heading is built by composition from title, geo and time. If false, only title will be used as a heading. Default (true) is set in visual.setup.js.

legend

Boolean. This determines whether the chart legend should be shown. Default (true) is set in visual.setup.js.

The position of the legend in Cartesian charts is set in visual.setup.js (canvas position property). The position of the legend in maps is particular to each map and is set in the canvas properties of the Visual map object.

grid

Object with the following properties: border (number: grid border width), line (number: line width), shadow (number: line shadow width), point (number: point radius) and markings (array of markings). Default border (0), line (2), shadow (4) and point (1) are set in visual.setup.js. A default collection of markings can also be set.

The markings property is supported when type is "tsline", "tsbar", "bar", "rank", "pyram" or "xy". See the Flot API for details.

Take into account that Visual comes with a default marking in the zero value of the Y-axis when type is "tsline". Specifying your own markings overrides it.

axis

Object with the following properties: x (boolean), y (boolean) and, since version 1, ticks (object) and labels (object). The first two determine whether the axes should be shown. Default (true) is set in visual.setup.js.

When the axes are shown, ticks and labels, both objects with properties x (boolean) and y (boolean), can be used to hide (false) axis ticks and axis tick labels.

unit

Object with three properties: label (string or, since version 1, object), symbol (string or, since version 1, object) and symbol position ("start" or "end" string, or, since version 1, object). All properties are optional.

To support several value axes, since version 1, label, symbol and position can be objects with properties x, y and z. Currently, x and y are only used simultaneously in XY charts.

Default (no label, no symbol, position: end) is set in visual.setup.js.

Warning: label and symbol cannot contain HTML entities when type is "cmap".

dec

Number (non-negative integer) or, since version 1, object. Number of decimals in the data. This is used in tooltips, map legends and value axes. To support several value axes, since version 1, dec can be objects with properties x, y and z. Currently, only in XY charts x and y are used simultaneously. When dec is a number, the same number of decimals is used in all value axes.

Although dec is an optional property, it is highly recommended that the number of decimals is specified: otherwise, all unneeded trailing zeros will be removed and computed values could be shown with more decimals than the original values. Default value can be set in visual.setup.js.

type

String ("bar", "rank", "tsbar", "tsline", "pyram", "cmap" and, since version 1, "pie" and "xy"). Required. Chart type. This determines the data and time formats and the specific properties available.

data

Array. Required. This includes the data values but also series labels and identifiers. The format is determined by type.

id

String. In simple mode and manual mode, this is the id of the HTML element where the visualization has to be embedded.

fixed

Array. In simple mode and manual mode, this is the [width, height] in pixels of the visualization container.

callback

Function. This function will be called after the chart has been drawn. The this keyword will point to an object with the following properties: id (the chart's identifier: string), chart (a boolean indica