Custom Visualizations

Zoho Analytics includes a set of default chart types for most reporting needs. When your reporting requirements go beyond these defaults, you can use Custom Visualizations to build and integrate your own chart types using third-party JavaScript libraries or custom scripts.

What You Need

To create a custom visualization, you must configure two files:

• ZAViz_Manifest.json — Defines the structure, data fields, dependencies, and user-configurable settings for the visualization.
• main.js — Contains the rendering logic that generates the visual output.

Both files must be packaged together in a ZIP file and uploaded to Zoho Analytics as a plugin by users with Admin privileges.

• Configuring a Custom Visualization
  • Configuring ZAViz_Manifest.json
  • Configuring main.js
• Utility APIs (ZAViz_Utils)
  • getFormattedValue
  • getSuitableStyle
  • Interaction API (ZAViz_ActionsAPI)
• Adding the Plugin
  • Steps to Add a Custom Visualization Plugin
  • Managing Custom Visualizations
• Using External Libraries
  • Licensing
• Supported Formatting Options

Configuring a Custom Visualization

Configuring ZAViz_Manifest.json

The ZAViz_Manifest.json file defines the structure and behavior of your custom visualization. It controls how the visualization appears in the Zoho Analytics UI, what type of data fields users can map to it, what external libraries it depends on, and what options appear in the Settings panel.

A typical ZAViz_Manifest.json file contains the following top-level properties:

A minimal ZAViz_Manifest.json looks like this:

{
  "name": "Sales Dashboard",
  "icon": "icons/sales-chart.png",
  "dependencies": [],
  "structure": ["Drop Area","multi","DIMENSIONAL",""],
  "settings": {}
}

Defining Drop Areas (structure)

The structure property defines the drop areas that appear in the chart builder. Each drop area is configured as an array with four parameters, in the following order:

Example for a Waterfall Chart:

{
  "name": "WaterFall",
  "icon": "localFile ",
  "dependencies": ["https://cdn.plot.ly/plotly-3.0.0.min.js"],
  "structure": [
    ["Category", "single", "DIMENSIONAL", ""],
    ["Value", "single", "MEASURE", ""]
  ]
}              

Defining User Settings (Settings)

The settings property defines the options that users can configure from the Settings panel. Settings are grouped into named tabs, and each tab contains one or more setting items.

Each setting item requires the following fields:

Supported Setting Types:

Example:

 "settings": {
  "Title": [
    {
      "uniqueName": "needComparison",
      "type": "checkBox",
      "label": "Need Comparison Line",
      "defaultValue": false
    },
    {
      "uniqueName": "title",
      "type": "inputText",
      "label": "Title",
      "defaultValue": ""
    },
    {
      "uniqueName": "bgColor",
      "type": "colorComponent",
      "label": "Background Color",
      "defaultValue": "#F3F3F3"
    }
  ],
  "Additional": [
    {
      "uniqueName": "chartEffect",
      "type": "multipleToggle",
      "label": "Chart Effect",
      "defaultValue": "Default",
      "options": ["Default", "Chalk", "Freehand"]
    },
    {
      "uniqueName": "Drill",
      "type": "toggle",
      "label": "Enable Drill",
      "defaultValue": true
    },
    {
      "uniqueName": "dropdown",
      "type": "dropdown",
      "label": "Show DropDown",
      "options": ["One", "Two", "Three"],
      "defaultValue": "Two"
    }
  ]
}

Configuring main.js

The main.js file contains the rendering logic for your custom visualization.

You must implement the generateCustomVisual function in this file. Zoho Analytics calls this function automatically whenever the visualization needs to be rendered or refreshed.

function generateCustomVisual(container, data, metaData) {
  // Your rendering logic here
}

This function receives three parameters: container, data, and metaData.

Each one is described in detail below.

container

The container parameter is the HTML element provided by Zoho Analytics as the drawing area for your visualization. All chart elements must be created and appended within this container.

function generateCustomVisual(container, data, metaData) {
  container.innerHTML = "

";
}

data

The data parameter contains the processed values of the columns that the user has dropped into the chart builder. The data is returned as a row-based array, where each row represents a single record.

• Each row contains values in the same order as the columns were dropped.
• Only the selected columns and their applied aggregations are included.
• Any change in column selection or aggregation is immediately reflected in the data structure.

Example - Columns dropped in the order: Region, Product Category, Sales

[
  ["Central", "Furniture", 17443.52],
  ["Central", "Grocery", 232572.5],
  ["Central", "Stationery", 58962.02],
  ["East", "Furniture", 68200.55],
  ["East", "Grocery", 414193.83],
  ["East", "Stationery", 116498.94],
  ["West", "Furniture", 45654.75],
  ["West", "Grocery", 266214.82],
  ["West", "Stationery", 80206.13]
]

metaData

The metaData parameter provides descriptive and structural information about the data and user configurations.

It contains two sections: columns and customSettings.

columns
The columns array describes each column dropped into the visualization, in the same order as the values in each data row.
Each column object contains the following fields:

customSettings

The customSettings object contains the current values of all user-configured settings from the Settings panel. 
Each value is accessible using the uniqueName defined in ZAViz_Manifest.json.

Example - Accessing customSettings values:

function generateCustomVisual(container, data, metaData) {
  const showLegend = metaData.customSettings.showLegend;
  const bgColor = metaData.customSettings.bgColor;
  const chartEffect = metaData.customSettings.chartEffect;
  // Use these values to customize your rendering logic
}

Utility APIs (ZAViz_Utils)

Zoho Analytics provides a set of built-in utility functions through the ZAViz_Utils object. Use these functions in your main.js code to format data values and retrieve theme-appropriate styles for your visualization.

Column Index

Before using the utility functions, it is important to understand how the column index works. The column index represents the order in which columns are dropped into the chart builder, starting from 1. Columns are counted from top to bottom and left to right across all drop areas.

Example:

getFormattedValue

Returns the formatted value of a data point based on the formatting details configured for the corresponding column.

Syntax:

ZAViz_Utils.getFormattedValue(columnIndex, data);

Parameters

Example:

const formattedSales = ZAViz_Utils.getFormattedValue(2, 17443.52);

getSuitableStyle

Returns a theme-appropriate color value in hex format based on the current dashboard theme or workspace color palette settings. Use this function to ensure your visualization adapts correctly when the user switches themes.

Syntax:

ZAViz_Utils.getSuitableStyle(styleType);

Parameters:

Example:

 const fontColor = ZAViz_Utils.getSuitableStyle('fontColor');
 const bgColor = ZAViz_Utils.getSuitableStyle('backgroundColor');
 const legendColor = ZAViz_Utils.getSuitableStyle('legendColor');

Interaction API (ZAViz_ActionsAPI)

Zoho Analytics provides the ZAViz_ActionsAPI object to enable user interactions within your custom visualization. Use this API to display the standard Zoho Analytics interaction menu when a user clicks on a data point in your chart.

showInteractionMenu

Displays the Zoho Analytics interaction menu at the position of the clicked data point.

Syntax:

ZAViz_ActionsAPI.showInteractionMenu(dataPoints, coordinates);

Parameters:

Example:

const dataPoints = { 1: "West", 2: "110.06" };
 const coordinates = { x: 250, y: 100 };
 ZAViz_ActionsAPI.showInteractionMenu(dataPoints, coordinates);

Implementation Examples

The following examples show how to integrate showInteractionMenu with commonly used third-party libraries.

Plotly

Plotly.newPlot(container, boxplotData, layout);
container.on('plotly_click', function(data) {
  const point = data.points[0];
  const dataPoints = {
    1: point.x,
    2: point.y
  };
  const coordinates = {
    x: data.event.x,
    y: data.event.y
  };
  ZAViz_ActionsAPI.showInteractionMenu(dataPoints, coordinates);
});

Highcharts

point: {
  events: {
    click: function(event) {
      const dataPoints = {
        1: event.point.from,
        2: event.point.to,
        3: event.point.weight
      };
      const coordinates = {
        x: event.chartX,
        y: event.chartY
      };
      ZAViz_ActionsAPI.showInteractionMenu(dataPoints, coordinates);
    }
  }
}

Adding the Plugin

Custom visualizations are added to Zoho Analytics as plugins. Only an Account or Organization Admin can add a plugin.

Before You Begin

Ensure that you have the following ready before uploading the plugin:

• A completed ZAViz_Manifest.json file
• A completed main.js file
• Both files packaged together in a single ZIP file

Steps to Add a Custom Visualization Plugin

1. Open the chart builder in Zoho Analytics and click the Plugin icon next to the Chart Type selector.
2. Click Add Custom Visuals.
   
3. In the File Explorer, select and upload the ZIP file containing your custom visualization files.
4. Once uploaded, the custom visualization appears under the Plugin icon.
   
5. Select the newly added plugin. The drop areas update according to the structure defined in your ZAViz_Manifest.json.
   
6. Drag and drop the required columns into the appropriate drop areas.
7. Click Generate Graph to render the custom visualization.
   

Configuring Settings

After adding a custom visualization, click the Settings icon at the top-right to open the Settings panel.

The panel contains the following tabs:

To configure your custom visualization's settings, click the Custom tab. The options defined in your ZAViz_Manifest.json appear here. 
Any changes you make are applied to the visualization immediately and passed to your main.js code through the metadata.customSettings object.

Managing Custom Visualizations

You can manage your uploaded custom visualizations from two entry points:

• From the chart builder - Click the plugin dropdown, then click Manage Visuals in the top-right corner of the Visuals panel.
  
• From Organization Settings - Navigate to Organization Settings > Custom Extensions > Visuals.
  

Both entry points open the Custom Visuals management page, where all uploaded visualizations are listed.

Available Actions

Hover over any custom visualization card to access the following options:

Using External Libraries

You can use any third-party JavaScript visualization library in your custom visualization. The following are some of the commonly used libraries:

• D3.js
• Highcharts
• Plotly
• Any other JavaScript visualization library

To use an external library, reference its URL in the dependencies array of your ZAViz_Manifest.json file.

{
  "dependencies": ["https://cdn.plot.ly/plotly-3.0.0.min.js"]
}

Licensing

When using third-party libraries, ensure that you comply with the library's licensing terms.

Depending on the license:

• Some libraries allow direct downloads and local bundling.
• Others require referencing a hosted URL.
• If the license requires attribution, include it as specified in the library's license documentation.

Supported Formatting Options

Custom visualizations currently support basic formatting options. To apply advanced formatting, use the JavaScript APIs provided by Zoho Analytics to match your visualization's appearance with Zoho Analytics' data formats and themes.

The following formatting parameters are available: