Overview

 

A JavaScript Chart is essentially made up of two components: JavaScript and CSS code. CSS is optional.

For the JavaScript portion, you could write your own or leverage an existing library. We ship with multiple different libraries which you can find in the /js/chartingLibraries/ folder. It is recommended that you add any extra libraries you need to this folder. Note that it is not technically necessary to always use a charting library, you can create anything you like using JavaScript and your report data.

When defining CSS rules, it is recommended that you give them unique names so that they don’t conflict with Yellowfin styling. For example, a good unique name is mycompanyname_chart_ textcolour 

 

Chart Data Options

Option

Description

JavaScript Code Panel

Use this panel to enter the JavaScript code.

CSS PanelThis panel is used to provide the CSS code.
Preview PanelYou can generate a preview of the your code in this panel.

 

Security

To switch on JavaScript Chart functionality within Yellowfin, the administrator needs to engage a 2-layer system. To switch it on, you need to:

It is recommended to have a new role set up just for JavaScript Chart creators and editors. This ensures that JavaScript Chart functionality is carefully managed and can be revoked when not needed.

Click here to learn how to enable the JavaScript functionality.

 

What happens when JavaScript Chart functionality is switched off?

If JavaScript Chart functionality is switched off at the Configuration level:

Note that it is also not possible for someone to import a JavaScript Chart into the platform without the function enabled against their role.

It is recommended to have your chart developers utilize proper content development and migration strategies in regards to development and testing environments, as well as leveraging our Approval Workflows to ensure governance. 

 

 

How the generateChart function works

The only function required when creating a JavaScript Chart is generateChart. The other functions provided in the example code are recommendations. Yellowfin will call generateChart to execute your JavaScript code.

All the options and data that you need from Yellowfin will be sent as part of the Options JSON object to the generateChart function.

You will be drawing everything into a provided div (options. divSelector) which the dataset will give you the id for. 


JavaScript Chart Example

This is an example of a very simple piece of JavaScript which will use the width and height sent in via the Options object and set the chart div to be purple. 


Require and Shim

Use Require to load any libraries that you need for your JavaScript Chart. If you are planning to embed via JavaScript API or publicly share the report, you will need to use absolute paths. Otherwise, relative paths will be fine. 

To use Require, simply define the path of what you need to load as follows: 


In certain scenarios where a non-AMD JavaScript library is used, Shim is required. While the shipped charting libraries within Yellowfin does not require Shim, you might need it for specific libraries sourced from the Web.

For more information about Shim, please see the requireJS documentation. 

 

Here is an example of using Shim to require the non-AMD library VizJS

 

Options JSON object

Example of a data set

We will be using the example shown below in our explanations. Please note that some of the data in this example is abbreviated (as shown by . . . . ) 

 

1. divSelector (options.divSelector)

A CSS selector using the ID of the div which the chart should be drawn within. This can be used with jQuery, D3 or any library which uses CSS style selectors.

E.g: to select the chart div in jQuery, you would do the following

var $chartDrawDiv = $(options.divSelector);

 

2. chartId (options.chartId)

The internal Yellowfin ID of the current chart.

 

3. errorCallback (options.errorCallback)

This is a function you can call to show the default Yellowfin error message. Use this if you want errors from the JavaScript Chart to look consistent with Yellowfin styling. It is not required that you use this. This will also print to console the error which occurred.

 

4. dataset (options.dataset)

An object whose attributes represent the report’s data and some rendering information. The dataset object will contain the following attributes:

4.1 chart_information (options.dataset.chart_information)

An object containing information used for chart rendering.

 

4.2 metadata (options.dataset.metadata)


Information about the fields in the report. 
Attribute names are based on the fields in the report (all lowercase with spaces replaced by underscores, and duplicate field names will append numbers to the end of the names). Field names used here correspond to the field names used for the data. 
Within metadata, these objects below contain the following attributes for each field: 


AttributeDescription
data_type 
A string representing the data type of the field (TEXT, NUMERIC, etc). 


field_name 

The formatted name of the field. If translations are switched on, the translated version of the field name for the user’s preferred language will be returned. 

metric_colour 

<Optional> Ifametriccolour has been set for this field at the view level then there will be a metric_colour attribute which contains the hex code (e.g #FFFFFF)fortheselectedcolour. 

org_refcode 

<Optional> If a field has a ref code applied to it on the data page, then this ref code information will be included with the JavaScript Chart dataset object.

This returns the ref code name e.g “DEMOGRAPHIC” according to our example above.

The Attributes object contains the actual data for the ref code (e.g sort order, display text, colour, etc). See orgrefcode_ definitions below. 

 

4.3 data (options.dataset.data)

An object containing the actual data in the report. As with metadata de ned above, attribute names are based on the
elds in the report e.g all lowercase with spaces replaced with underscores. These represent arrays of objects with the following attributes for each field:

AttributeDescription
raw_data

The underlying data contained within this field.

formatted_data

The formatted data for this field with prefix, sufix, decimal places, etc.

These data arrays are in the order that the data appears in the report. This means that options.dataset.data.camp_region[4] and options.dataset.data.camp_rating[4] refer to the same row of data. 

 

4.4 attributes (options.dataset.attributes)

An object which contains additional rendering information. This contains the following attributes:

AttributeDescription
default_colours

An array ofthedefaultchartcoloursconfiguredintheAdministration->Content Settings page. These are also in the order that they are specified within that page.

orgrefcode_definitions

Contains all the org ref code definitions used by any fields on the report.

This is a map of maps. The key is the org ref code which matches with the org ref code for the field in the metadata object defined earlier above and is keyed by the field name used in the data object.

Each definition contains thecolourand sort order if they exist, as well as the display text for the org ref code. 

 

 

Behind the scene operations

Calling a JavaScript Chart will first generate a dataset server side which contains the following:

If JavaScript Chart functionality is turned off at the Configuration level, the JavaScript, CSS and dataset will not be returned.

The JavaScript handler will call your generateChart function, sending in the JavaScript Chart dataset object, chartId, divSelector and an errorCallback function.

The CSS is appended to the chart div within a style tag.

All of this logic is wrapped within a try/catch function which will show the standard error message for charts if there is a failure.

Additional Data Processing

Yellowfin simply returns the dataset as you see from the table output in your report.

However, you can define additional functions within your JavaScript Chart code to process the data further as needed. 

 

Below is a very simple example of using a self-defined processData function to aggregate the data by SUM, and returning a dataset which contains demographic and the totals of camp rating: 

 

You can also write your own processData function definitions to either:

For example, certain D3.js charts (e.g Sunburst, Bubble Cloud, or charts that consume the flare.json example, etc) consume data in a hierarchical object structure. In this example, the Yellowfin report data set within options.dataset.data is further processed by: 


  1. Transposing each column to include its name 

  2. Merging it into an Array 


 

Another example is using the GoogleCharts library - for example, to use this library and draw a bar chart, the library is expecting the dataset to be in an Array that looks like this: 

In this scenario, the options.dataset.data can be massaged into this form. Below is a simple example of this being done with a dataset that contains demographic and invoiced amount: 

 

Useful tips

Here are a few useful things that will aid the development of JavaScript Charts:

Use a try/catch block in your require statement to catch
any errors and use our callback error function defined in
 the dataset as below so that any errors generated have the same look and feel as other chart errors. Yellowfin will also print the JavaScript error to browser console so that you can debug this.

E.g: 

 

 

 

Limitations

Currently, there are a few minor JavaScript charting limitations :