du.widget

Module for creating and adding various widgets to an interactive dashboard. This module contains the base class for all widgets, and therefore it is required to be included. All widgets come with some default functionality which are implemented in this module.

There are some fundamental characteristics of all widgets that are listed here:

Font family of the widget is inherited from the parent div (or body if parent is not specified).
Some widgets come with methods to bind mouse events to them (mouseover, mouseleave and click).
For chart widgets, data can be bound to the (but they are needed to be rendered once data is changed) and the specific format of the data is described in the documentation of each chart.
If otherwise not specified, widget methods are implemented in a way that they return a reference to the current widget, in order to allow for chaining of the methods.
Each widget comes with a method describe which binds an explanation pop-up block to the context menu (right mouse click) on the widget.
Similarly, each widget is shipped with a placeholder method to easily toggle between the live widget and a static text replacement of it.

With a few exception, most of the widget methods return a reference to the widget itself for chaining.

Requires: d3@v4

du.widget.Widget(name, type[, element[, parent]])

The base widget class, all widgets inherit this parent class.

arg	type	description
name	`string`	Name of the widget. This is used to identify the element.
type	`string`	Widget type, part of the generated widget ID.
element	`string`	HTML element type to use in the widget. If not specified, SVG is used. `optional`
parent	`object`	Parent element to append widget to. If not specified, it is attached to body. `optional`

du.widget.Widget._IDS

Object Internal IDs.

du.widget.Widget.relative(on)

Whether to position widget relative to parent instead of absolute. Default is false.

arg	type	description
on	`boolean`	True if relative position should be turned on.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.x(x, dim)

Sets the horizontal position of the widget. Default is 0px.

arg	type	description
x	`number`	Position value.
dim	`string`	Dimension (unit) of the position. Supported values: px, %.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.y(y, dim)

Sets the vertical position of the widget. Default is 0px.

arg	type	description
y	`number`	Position value.
dim	`string`	Dimension (unit) of the position. Supported values: px, %.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.width(w)

Sets widget width in pixels. Default is 200.

arg	type	description
w	`number`	Width in pixels.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.height(h)

Sets widget height in pixels. Default is 150.

arg	type	description
h	`number`	Height in pixels.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.margins(margins)

Sets widget margins. Default is 0 for all sides.

arg	type	description
margins	`number` `object`	A single number to set all sides or an object specifying some of the sides.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.borders(borders)

Sets widget borders. Default is null for all sides.

arg	type	description
borders	`object`	A string to use for all sides or an object specifying some of the sides.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.fontColor(color)

Sets the font color of the widget. This color is used for axes and all other non-plot type elements. Default is black.

arg	type	description
color	`string`	Color to set font and axes to.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.fontSize(size)

Sets font size of the widget in pixels. Default is 10.

arg	type	description
size	`number`	Font size in pixels.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.fontWeight(weight)

Sets font weight of the text elements in the widget. Default is normal.

arg	type	description
weight	`string`	Font weight.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.label(text)

Sets the label of the widget. Default is an empty string.

arg	type	description
text	`string`	Label text.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.xLabel(text)

Sets the horizontal label of the widget. Default is an empty string.

arg	type	description
text	`string`	Label text.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.yLabel(text)

Sets the vertical label of the widget. Default is an empty string.

arg	type	description
text	`string`	Label text.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.xTicks(Array)

Sets explicit tick values for the X axis. Note that thick formatting set by xTickFormat still applies. Default it is off (generated automatically).

arg	type	description
Array	`number[]` `string[]`	of numbers or strings.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.yTicks(Array)

Sets explicit tick values for the Y axis. Note that thick formatting set by xTickFormat still applies. Default it is off (generated automatically).

arg	type	description
Array	`number[]` `string[]`	of numbers or strings.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.tickFormat(format)

Sets the format function for the ticks. Default is an SI prefixed number

arg	type	description
format	`function`	Function that converts a number to a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.xTickFormat(format)

Sets the format function for the X axis. Default is an SI prefixed number.

arg	type	description
format	`function`	Function that converts a number to a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.yTickFormat(format)

Sets the format function for the Y axis. Default is an SI prefixed number.

arg	type	description
format	`function`	Function that converts a number to a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.xTickAngle(angle)

Sets the angle of the horizontal tick labels. Default is 0.

arg	type	description
angle	`number`	The angle to set.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.yMin(value)

Sets vertical lower boundary of the widget. Default is 0.

arg	type	description
value	`number`	Value to set vertical minimum to.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.mouseover(callback)

Sets a callback when various elements of the widget are hovered. The behavior of this callback is specific to the widget type: for chart widgets, it is bound to the plot elements and the plot's name is passed to the specified callback as argument. This can be used as a selector for e.g, highlighting elements in the widget. For the map it is bound to countries and the name of the country is passed as parameter. For standalone widgets such as a label, it is bound to the widget itself. Default is null.

arg	type	description
callback	`function`	Callback to trigger on mouseover.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.mouseleave(callback)

Sets a callback when the mouse leaves various elements of the widget. The behavior of this callback is specific to the widget type: for chart widgets, it is bound to the plot elements and the plot's name is passed to the specified callback as argument. This can be used as a selector for e.g, highlighting elements in the widget. For the map it is bound to countries and the name of the country is passed as parameter. For standalone widgets such as a label, it is bound to the widget itself. Default is null.

arg	type	description
callback	`function`	Callback to trigger on mouseleave.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.click(callback)

Sets a callback when the various elements of the widget are clicked. The behavior of this callback is specific to the widget type: for chart widgets, it is bound to the plot elements and the plot's name is passed to the specified callback as argument. This can be used as a selector for e.g, highlighting elements in the widget. For the map it is bound to countries and the name of the country is passed as parameter. For standalone widgets such as a label, it is bound to the widget itself. Default is null.

arg	type	description
callback	`function`	Callback to trigger on click.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.colors(colors)

Sets the color(s) of the widget plot elements. By default, a combination of the Color Brewer schemes Set 1 and Set 3 is used. If single color is defined, a sequential color scheme is generated with the number of categories equal to the keys in data. If a full color mapping is specified, it is used directly without change.

arg	type	description
colors	`string` `object`	Single color to set all plot elements or an object specifying the color of each plot.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.tooltip(enable)

Enables tooltip for the chart widget. Default is false.

arg	type	description
enable	`boolean`	If tooltip should be enabled.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.tooltipTitleFormat(format)

Sets the format for the title in the tooltip. Default is just the title itself.

arg	type	description
format	`Function`	The formatting function that takes a string and returns a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.tooltipXFormat(format)

Sets the number format for X values in the tooltip. Default is just the number itself.

arg	type	description
format	`Function`	The formatting function that takes a number and returns a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.tooltipYFormat(format)

Sets the number format for Y values in the tooltip. Default is just the number itself.

arg	type	description
format	`Function`	The formatting function that takes a number and returns a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.tooltipZFormat(format)

Sets the number format for Z values in the tooltip whenever there is a third dimension. Default is just the number itself.

arg	type	description
format	`Function`	The formatting function that takes a number and returns a string.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.id()

Returns the widget ID.

return	description
`string`	Identifier of the current widget.

du.widget.Widget.describe(content)

Adds a description for the widget. A description is a tooltip that is shown if the user right-clicks on the widget. After 15 second or if the user leaves the widget, the description disappears.

arg	type	description
content	`string`	Content of the description. Can be HTML formatted.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.placeholder(content, offset)

Replaces the widget with a placeholder. Useful for showing missing data.

arg	type	description
content	`string`	Content to show in place of the widget. Can be HTML formatted. If nothing is passed,
offset	`offset`	Vertical offset for the placeholder. Default is 0.

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.render([duration])

Renders the widget. Note that without calling this method, the widget is not rendered at all. After any changes in style or bound data, this method should be called.

arg	type	description
duration	`number`	Duration of the rendering transition. If not specified, 500 ms is applied. `optional`

return	description
`du.widget.Widget`	Reference to the current widget.

du.widget.Widget.remove()

Removes widget from DOM.