Extension JS APIs

Endpoints

JavaScript module returns an object that may implement one of the endpoints: version(), supported(), settings(), disableDraw(), beforeDraw(), afterDraw(), and afterDataRequest().

version()

This must exist, and reports on the version of the API that this object implements. Currently supported version strings is "1". This must be a string, not a number.

supported()

If this member exists, it is expected to be an object that contains a member called visualType. This member must point to a string with the type of visual supported, or an array of strings that contain the types of visuals supported.

For example,

supported: {
  visualType: "trellis-bars"
},

Supported Visual Types
Visual Type	Object Name
Table	`table`
Cross Tabulation	`crosstab`
Bars	`trellis-bars`
Lines	`trellis-lines`
Combo	`combo`
Areas	`trellis-areas`
Grouped Bars	`trellis-groupedbars`
KPI	`kpi`
Packed Bubbles	`packed-bubbles`
Scatter	`scatter`
Flow	`flow`
Funnel	`funnel`
Pie	`pie`
Radial	`radial`
Chord	`chord`
Correlation Heatmap	`correlation`
Correlation Flow	`correlation-flow`
Calendar Heatmap	`calendar-heatmap`
Map	`map`
Interactive Map	`leaflet`
Sparklines	`sparklines`
External Link	`link`
Histogram	`histogram`
Extension	`extension`
Field Statistics	`column-stats`
Queries	`rawtable`
Rich Text	`html`
Network	`network`
Dendrogram	`dendrogram`
Treemap	`treemap`
Bullet	`bullet`
Gauge	`gauge`
Word Cloud	`wordcloud`
Box Plot	`boxplot`
Timeline	`timeline`

settings()

If a member with this name exists, it is expected to be a function that returns an array. Each array element is then expected to be an object with the following members:

settings: function() {
  return [
    {
      id: "Column Name"
    },
    {
      id: "Max bar width",
      defaultValue: "50"
    },
    {
      id: "Color",
      defaultValue: "steelblue"
    }
  ];
},

Settings Specifications
Member	Name	Description	Default Value	Mandatory
`id`	Column Name	The ID of this setting.	None	Yes
`displayName`	Column Name	Name used to display this setting.	Same as ID	No
`type`	String	The data type of the variable. Supported types include `String`, and `boolean`.	`String`	No
`defaultValue`	""	The default value for this setting.	`null`	No

disableDraw()

If a member with this name exists, and it is a function that returns a boolean variable set to true, we disable the drawing of the visual.

beforeDraw()

If a member with this name exists, it must be a function that executes after receiving data but before the draw event on the visual.

afterDraw()

If a member with this name exists, it must be a function that executes after the draw event on the underlying visual.

afterDataRequest()

If a member with this name exists, it must be a function that executes after creating the request object, but before the data request call. This function accepts the current request object in the arguments, adds your modifications, and returns an updated valid request object. If the function does not return a valid request object, the request is not sent, and the system returns an error.

arcapi Functions

Developer Notes:

There are additional functions currently available on the arcapi object, but we do not list them here. These functions were developed for internal use only, and we do not warrant them for use by our clients. Arcadia Data cautions against using them in your customizations because of expected forward compatibility issues.

The extension JS module has access to an arcapi object. Arcadia Data supports the following functions fully:

arcapi Functions
Function	Description
`arcapi.addScripts()`	Adds script elements.
`arcapi.addStyles()`	Adds style elements.
`arcapi.chartId()`	Returns the id DOM element.
`arcapi.dataResult()`	Returns the data result object and gives access to the raw data for plotting the visual.
`arcapi.getParameters()`	Returns information on all current parameters.
`arcapi.getSetting()`	Returns the value of the specified setting.
`arcapi.sendParameters()`	Forwards parameter definitions to other visuals in the app.
`arcapi.settings()`	Returns information on all current settings.

arcapi.addScripts(filepaths, callback)

Adds script elements for the additional styles specified in the filepaths array. The function callback is invoked after load completes.

Syntax

arcapi.addScripts(
  filepaths, 
  callback);

Parameters

filepaths An array that specifies the additional JS files to load.
callback Call-back function that is invoked after the load is completed.

Examples

In program code, you can use this API in the following manner:

arcapi.addScripts(
  ['https://cdnjs.cloudflare.com/ajax/libs/highcharts/7.0.1/highcharts.js'], 
  function() {
    console.log('highcharts.js has been loaded');
    }
  );

This code embeds the following <script> as the last element of the <head> tag in the HTML file:

<script 
  type="text/javascript" 
  src="https://cdnjs.cloudflare.com/ajax/libs/highcharts/7.0.1/highcharts.js" 
  data-loaded="true">
</script>

arcapi.addStyles(filepaths, callback)

Adds style elements for the additional styles specified in the filepaths array. The function callback is invoked after load completes.

Syntax

arcapi.addStyles(
  filepaths, 
  callback);

Parameters

filepaths An array that specifies the additional CSS files to load.
callback Callback function that is invoked after the load is completed.

Examples

In program code, you can use this API in the following manner:

arcapi.addStyles(
  ['https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.2.1/css/bootstrap.css'],
  function() {
    console.log('Twitter Bootstrap has been loaded');
    }
  );

This code embeds the following <link> as the last element of the <head> tag in the HTML file:

<link 
  type="text/css" 
  rel="stylesheet" 
  href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.2.1/css/bootstrap.css" 
  data-loaded="true"
>

arcapi.chartId()

Returns the id attribute of the DOM element used to draw the visual.

Syntax

arcapi.chartId();

Usage

$("#" + arcapi.chartId())

Returns

A jquery selector to the DOM element.

arcapi.dataResult()

Returns the dataResult object that gives the extension access to the raw data used to plot the visual. This object supports the arc.data.result interface.

Syntax

arcapi.dataResult();

This example shows the result of the arcapi.dataResult() call:

f (){return"arc.data.result"}

See Also

arcapi.dataResult Functions

arcapi.getParameters()

Returns a hash object that contains key-value mappings for all current parameters. The key is the parameter name.

Syntax

arcapi.getParameters();

Example

The following is a typical result of the arcapi.getParameters() command:

{
  "productCategory": "Analytics", 
  "year": "2019", 
  "companies.data": "'Apple', 'Google', 'Arcadia'", 
  "companies.exclude": "in"
}

See Also

arcapi.sendParameters(params_hash)

arcapi.getSetting(settingName)

Returns the value of the specified setting of the current JS extension.

Syntax

arcapi.getSetting(settingName);

Parameters

settingName Name of setting.

Example

The following command retrieves the "Color" setting:

arcapi.getSetting("Color");

Our example's result follows:

"red"

See Also

arcapi.settings()

arcapi.sendParameters(params_hash)

Accepts a hash definition, and sends out the keys and values of the hash as parameters to other visuals in the app.

Syntax

arcapi.sendParameters(params_hash);

Parameters

params_hash Hash definition.

Example

To pass a parameter with name 'company' and value 'Arcadia Data' to all visuals and filters in the dashboard, issue the following command:

arcapi.sendParameters({"company": "'Arcadia Data'"});

See Also

arcapi.getParameters()

arcapi.settings()

Returns information on all current settings for the custom style: an array of objects, with id of a setting, and value of that setting.

The order of the array is specified by the JS extension's settings() function.

Syntax

arcapi.settings();

Example

A typical example output after running the arcapi.settings() function looks similar to this:

 [
    {
      id: "Column Name",
      value: "",
    },
    {
      id: "Max bar width",
      defaultValue: "50",
      value: "50",
    },
    {
      id: "Color",
      defaultValue: "steelblue",
      value: "red",
    }
  ];

See Also

settings()

arcapi.dataResult Functions

Developer Notes:

There are additional functions currently available on the arcapi.dataResult object, but we do not list them here. These functions were developed for internal use only, and we do not warrant them for use by our clients. Arcadia Data cautions against using them in your customizations because of expected forward compatibility issues.

The extension JS module has direct access to an arcapi.dataResult object. Arcadia Data supports the following functions fully:

arcapi.dataResult Functions
Function	Description
arcapi.dataResult().columnNameToIndex(colname)	Returns the column index that corresponds to the specified column name.
arcapi.dataResult().columns()	Returns the full array of all columns in the current `dataResult` object.
arcapi.dataResult().columns()[index].colname()	Returns the name of the column at the specified index position.
arcapi.dataResult().columns()[index].colindex()	Returns the index of the column at the index position.
arcapi.dataResult().rows()	Returns all available data rows in the current `dataResult` object.

arcapi.dataResult().columnNameToIndex(colname)

Returns the column index that corresponds to the specified colname, the name of the column.

Syntax

arcapi.dataResult().columnNameToIndex(colname)

Parameter

colname The name of the dataResult column.

Example

The expected result may look something like this:

> arcapi.dataResult().columnNameToIndex("Calories")
< 2

arcapi.dataResult().columns()

Returns the full array of all columns in the current dataResult object.

Syntax

arcapi.dataResult().columns()

Example

The expected result may look something like this:

> arcapi.dataResult().columns()
< (3) [ƒ, ƒ, ƒ]

arcapi.dataResult().columns()[index].colname()

Returns the name of the column at the specified index position.

Syntax

arcapi.dataResult().columns()[index].colname()

Parameter

index The index of the dataResult row.

Example

The expected result may look something like this:

> arcapi.dataResult().columns()[0].colname()
< "Cereal Name"

arcapi.dataResult().columns()[index].colindex()

Returns the index of the column at the index position.

Syntax

arcapi.dataResult().columns()[index].colindex()

Parameter

index The index of the dataResult row.

Example

The expected result may look something like this:

> arcapi.dataResult().columns()[0].colindex()
< 0

arcapi.dataResult().rows()

Returns all available data rows in the current dataResult object.

Syntax

arcapi.dataResult().rows()

Example

The expected result may look something like this:

> arcapi.dataResult().rows()
< (5) [Array(3), Array(3), Array(3), Array(3), Array(3)]
     0: (3) ["100%_Bran", "Nabisco", 70]
     1: (3) ["100%_Natural_Bran", "Quaker Oats", 120]
     2: (3) ["All-Bran", "Kelloggs", 70]
     3: (3) ["All-Bran_with_Extra_Fiber", "Kelloggs", 50]
     4: (3) ["Almond_Delight", "Ralston Purina", 110]