RenderBase

Rendering

Rendering your visualization is done through the create and update methods of RenderBase. These methods implement the initialization and update phase of a render cycle. For more information, see Rendering. You can override these methods to provide your own render initialization and updates. Overriding these methods is optional, if you do not override them, a default implementation is provided in RenderBase.

create()

create( _node: HTMLElement ): Element | void | Promise<Element | void>

The create method is called exactly once, when the visualization is created. You basically put all your initialization code here. Or you set up your drawing context (maybe an svg node with some fixed child elements or groups). The return value becomes the root element of your visualization and is passed to you in the update method. If you do not return a value from this function, or choose not to implement it at all, then the passed _node becomes the root element for your visualization.

update()

update( _info: UpdateInfo ): void | Promise<void>

The update method is called each time that the visualization needs to be redrawn. Reasons for redrawing the visualization are new data, modified properties, or a modified visualization size. A parameter holding UpdateInfo is passed to the update method, allowing you to access the latest data, properties and a set of flags that tell you the reason for the update call.

Properties

Your visualization will probably expose one or more properties that allow the user to control specific behaviors of the visualization. RenderBase gives you access to these properties using the properties attribute. In addition to retrieving property values, RenderBase also lets you monitor changes to properties. This is useful if you need to activate or deactivate properties based on the values of other properties. For instance, a bar chart might have a stacked and a stackPercent property. If stacked is not set, then stackPercent might be disabled.

properties: Properties

This attribute holds the properties that are available in the visualization. You can access the value of a property by calling properties.get( "propname" ). Getting and setting the active state of a property can be done by calling isActive and setActive on the properties attribute respectively. The properties are also passed to you in the UpdateInfo object. For more information, see update().

updateProperty

updateProperty( _name: string, _value: any ): void

Called immediately if the host assigns a new value to a property. You can override this method to process property changes. For instance, they can set the active state of properties based on the value of another property.

protected updateProperty( _name: string, _value: any ): void
{
    if ( _name === "stacked" )
        this.properties.setActive( "stackedPercent", _value );
}

The updateProperty method is also called at initialization time for each property in the visualization. You can set the correct initial active state for all properties.

If you want to access the value of a property in this method, use properties.peek instead of properties.value. The former gives synchronous access to the property value meaning it is not influenced by locking. For more information, see Property locking.

Localization

If your visualization needs to expose translated text or messages, then you can set up an nls directory structure and add your text to the resources.js file in the root of the nls directories. You can create sub directories and add translated resources.js files for each language you want to support. When your visualization is loaded, your text resources are loaded and made available in your RenderBase subclass through the nls attribute.

The RequireJS nls plugin is used internally to load and process nls files.

nls

nls( _name: string ): string

Returns a translated string given a unique name.

protected update( _info: UpdateInfo ): void
{
    if ( _info.data === null )
    {
        _info.node.textContent = this.nls( "no_data" );
        return;
    }
}

Hit testing

Your visualization can provide custom hit testing functions, that allow the hosting application to show tooltips, selections and highlights. A default hit testing function is already provided for you in RenderBase. This function checks for the existence of d3 data binding and use that if available.

hitTest

hitTest( _elem: Element | null, _client: Point, _viewport: Point ): DataPoint | Tuple | null

Returns a data element based on an element and coordinate. The coordinate is passed both as client point (relative to browser window) and viewport point (relative to visualization). You are supposed to return a data object that was passed to you in the update() method. For more information, see Interactivity.

meta

meta: MetaInfo

Currently, the following fields are available:

• legendShape - Defines the shape of elements in a categorical legend. The default value is null, indicating that the host can determine a default shape.
• slotLimits - This is a map from slot name to a number of supported tuples in that slot. The information in this map is passed to the host as an indication of how much data can be handled by the visualization. Slots that are not in this map, or have a limit of -1, are not limited to a maximum number of tuples.
• dataLimit - The maximum number of data points that the visualization supports, or -1 if there is no limit.