Skip to content

RenderersProvider

Jump to bottom
Scotty Aslan edited this page Sep 17, 2017 · 1 revision

A renderer (think of it as a "data visualization constructing" function) takes as arguements a dataView object and an opts object (as defined when configuring a renderer with the $rndrRenderersProvider service) and it returns an object. The returned object is not documented here since each renderer may define the object it returns. The only requirement, however, is that the returned object must have an html property that is the jQuery element representing the visualization to be appended to the DOM.

The $rndrRenderersProvider module

A "data visulization constructiing" function (renderer) must be configured before it can become available during the configuration of an ngRndr.RenderingEngine. The $rndrRenderersProvider singleton is a dictionary of such renderer functions and has the following methods:

  • add(name, renderer, dataViewName, opts, finalize): It takes as parameters:
    Parameter Type Description
    name string The lookup name of the renderer (any string will do but please note that you can only register one renerer function to per name).
    renderer function A "data visulization constructing" function.
    dataViewName string The name of the data view used by the renderer.
    opts (optional) object Overrides or extends the options for the renderer.
    finalize(element, result, opts) (optional) function The post rendering function for the attached and visible DOM ouput of the renderer. Allows users to apply other jQuery plugins to the visualization. It takes as parameters: 
      Parameter  | Type | Description
  ---------  | ---- | -----------
  `element` | jQuery | The jQuery object of the containing DOM element for the rendered visualization.
  `result` | object | The object returned from the renderer.
  `opts` | object | The `opts` object passed to the render function.
  • list(), Lists the available "data visualization constructing" functions.

Example registering a renderer plugin

To register window.ngRndr.plugins.renderers.myRenderer:

// for the purpose of this example let's assume that the `$rndrRenderersProvider` service singleton and is available in the current lexical scope (it could have been injected, created, or passed in).
$rndrRenderersProvider.add("RendererName",
    window.ngRndr.plugins.renderers.myRenderer["RendererName"],
    'CompatibleDataViewName');

renderer plugins

You can create your own renderer plugin and resigter it with the $rndrRenderersProvider singleton. A renderer plugin is an Universal Module Definition (UMD) that can be loaded with AMD or CJS and will add itself to the window.ngRndr.plugins.renderers object. It returns a dictionary of renderer functions where the keys are the name of the renderer.

Example renderer plugin

(function (root, factory) {
    if (root.ngRndr === undefined) {
        root.ngRndr = {};
    }
    if (root.ngRndr.plugins === undefined) {
        root.ngRndr.plugins = {};
    }
    if (root.ngRndr.plugins.renderers === undefined) {
        root.ngRndr.plugins.renderers = {};
    }
    if(typeof define === "function" && define.amd) {
    define(["jquery"], function($){
      return (root.ngRndr.plugins.renderers.myRenderer = factory($));
    });
    } else if(typeof module === "object" && module.exports) {
    module.exports = (root.ngRndr.plugins.renderers.myRenderer = factory(require("jquery")));
    } else {
    root.ngRndr.plugins.renderers.myRenderer = factory(root.$);
    }
}(this, function($) {
  return {
    RendererName: function(dataView, opts){
        // It is a best practice to set default values for any `opts`
        var defaults = {
            heightOffset: 0,
            widthOffset: 0,
            locales: {
                en: {
                    localeStrings: {
                        renderError: "An error occurred rendering the results.",
                        computeError: "An error occurred computing the results."
                    }
                }
            }
        };

        // The `defaults` should then be overridden by any `opts` set during
        //  registration of the `renderer` with the `ngRndr.renderers` module.
        //   NOTE the `renderingEngine` always sets the following properties 
        //   on the `opts`:
        //      Parameter  | Type | Description
        //      ---------  | ---- | -----------
        //      `renderingEngine` | object | The meta data for the rendering engine.
        //      `height` | number | The height (in px) of the DOM element containing this visualizaiton.
        //      `width` | number | The height (in px) of the DOM element containing this visualizaiton.
        opts = $.extend(defaults, opts);

        var result = $('<div></div>');
        
        // The `renderer` interacts with a `dataView` to construct a 
        // visualization of the data. The renderer mechanism is fairly 
        // generic, so it should be possible to write some interesting
        // renderers in a variety of frameworks. DOM elements to display that
        // interaction should be constructed and appended to the `result`
        // object here...

        // The return object of a `renderer` must contain the `html` property
        // which is the jQuery element representing the visualization to be 
        // appended to the DOM. This object can be extended to include more 
        // properties as necessary for access in the renderer's finalization 
        // function.
        return {
            html: result
        }
    }
  };
}));
Clone this wiki locally