Creating custom charts

Don’t see your ideal chart as a default option in ClearPoint? We leverage a charting library that might be able to create exactly what you are looking for. The configuration is very particular, so pay very close attention to the details in this article.

Creating Custom JSON Charts

There are three primary ways that users can create custom charts in ClearPoint. Learn about each here in this article.

Browsing the JSON Library

The JSON chart library has a collection of charts that cover some of the more popular customizations we see.  Use one of these charts as a starting point for your perfect chart.

Open the Edit Chart window by double clicking the chart on the measure detail page. From the Chart Type dropdown, select Custom Chart JSON. Remove the existing JSON that is in the field to start with a blank slate.

The dropdown for Select Custom Chart JSON Template will be enabled. Click the dropdown to select the chart you would like to use be clicking next to the title of the chart. Once you click your desired chart type, that chart’s JSON will appear in the field. Click Save.

You will then see the chart in the preview panel of the edit window. Click Save and the chart will be on your detail page.

Use Current Chart JSON

The ClearPoint chart editor is designed to cover all your basic customization needs.  In some cases, however, this isn’t quite enough.  Use the ‘Get Chart JSON’ button to pull your chart data out as a customizable JSON payload.  You can then make additional customizations that ClearPoint’s UI doesn’t currently provide.

Open the Edit Chart window by double clicking the chart on the measure detail page. From Chart Type, select Custom Chart JSON. This field will automatically populate with the JSON of this particular chart.

Click Save. You will be taken back to the detail page where you will see the custom chart.

Start from scratch using Highcharts

Want to build a chart from the ground up?  The Highcharts documentation is extensive and can be a great resource for those who want to build it all on their own.

Open the Edit Chart window by double clicking the chart on the measure detail page. From Chart Type, select Custom Chart JSON.

In a new tab in your browser, go to ‘https://api.highcharts.com/highcharts/’. You will be redirected to the Highcharts Options Reference.  This page outlines all of the Highcharts customizations that exist. Each property can hold a variety of values, so read into each to see how it works. When you find the property you would like to change, click on the Try it button to open the chart in the JSFiddle editor.  This will open in a new tab.

Each property can be customized from the left panel.  Use the Highcharts documentation as your guide for how each property value should be structured.  For this example, modifications are being made to chart type. You can also see the legend object and some of its properties here. Changes can be made to things like alignment, location, or padding. Once you make changes, click on the Run button to see what those changes will look like in the sample chart on the right.

When you have the portions of JSON that you would like in mind, navigate back to ClearPoint. The image below in the ClearPoint chart editor shows the customizations made. Please ensure that you begin your chart JSON with a curly bracket like {.

After entering chart and designating type, enter the type of chart desired. For this example, the JSON specifies that the chart will be a “bar” chart rather than the standard “column”. There are many chart types possible with JSON, and they can be explored here.

Additionally, the JSON example below indicates that the legend will be aligned to the right while also being stacked vertically. As seen in the Highcharts API, there are numerous options to legends and even charts in general. Make sure there are commas used to break up multiple properties at the same level, as seen in this example.  These are required for valid JSON formatting. Other legend properties that can be applied can be seen here.

As mentioned previously, ensure that you end with a curly bracket like }.

Click Save when you have finished making your customizations. Click Refresh Preview to see how it will look. If it loads, your chart works and you have written a readable form of JSON. If it does not work, either ClearPoint doesn’t work with the designated chart type or you have written an incorrect portion of the JSON. When finished customizing your chart, click Save.

Saving and reusing custom charts

Once you are happy with a custom chart, you can save it and reuse it in other measures.  From the Custom JSON Format tab, click Add Custom Chart Type . You will be prompted to name this chart type. Click Add after naming the chart, and click Save one more time. After this, this chart will be added as a default chart option for new measures and charts.

Managing custom charts in Admin Options

Administrators can edit and delete existing custom charts from Admin Options.

After you have added a JSON chart as a custom chart type, you can navigate to see your Chart Library if you are an Administrator. To do this, click on System Settings, and then Admin Options.

Click the Advanced & Custom Charts tile and a new window will appear.

Click on the Custom Chart Types tab to see the charts in your library. You will see the chart that was just added. To edit existing charts, click the edit pencil icon. When all changes are made, click Save.

If you would like to add a new custom chart, click the plus icon. When adding a new chart, you will be prompted to enter a Name. Insert the JSON copied from Highcharts. Once you see the message indicating that the JSON is valid and can be used as a custom chart, click Save.

Your custom chart will now be available when you are selecting a chart type.

Formatting tips and troubleshooting

If you see the toaster above when creating a custom chart, something about what you have entered is either incorrect, or not supported by ClearPoint.  To help you narrow down on the possible errors, here is a list of things we’ve seen:

• Make sure you begin and end with a curly bracket: “{” and”}.”
• ClearPoint does not support Highcharts themes.  These are typically associated with chart colors and look something like this:
  • color: (Highcharts.theme && Highcharts.theme.textColor) || "gray"
  • Remove these from your JSON and try the chart again.
• If you remove pieces from the chart you are adding, make sure that every curly bracket still has an open and a close.
• Also, make sure there are commas used to break up multiple properties at the same level.  These are required for valid JSON formatting.