Charts

Transform data into information. The Charts module for Drupal enables you to build dynamic charts without needing to write a line of code. If you are comfortable coding, you can use the Charts API to generate or update charts. Instructions for creating charts are included below.

There are many charting libraries (also sometimes referred to as providers) that you can find online. Each has their own benefits, drawbacks, and APIs. To use one of them without this module, you would need to 1) be familiar with the charting library's API, 2) add its JavaScript file(s) in your page, and 3) write code for every chart you want to include. That's a lot of effort, and it requires knowledge and access that many Drupal site builders will not have.

Charts is designed so that anyone who wants a chart on their site can have a chart -- and be happy with it.

How Does The Charts Module Work (Technically)?

The Charts module takes data and configuration from your site, and with the help of a submodule, organizes it into a JSON object that is saved as an attribute on an HTML element on your page; the JSON objected is handed to your selected charting library, which renders it into a chart.

Charting Providers / Libraries

Out of the box, you will be able to use 5 charting solutions (referred to as "providers" or "libraries". Each of them has particular advantages and disadvantages.

• Billboard.js: This library is a fork of the C3 charting library. It has additional features, such as radar charts.
• C3.js: This library is a D3-based reusable chart library that makes it easy to generate D3-based charts.
• Chart.js: This is a simple yet flexible JavaScript charting for designers & developers.
• Google Charts: This library generates interactive charts using SVG and VML.
• Highcharts: This library is one of the premier solutions for generating charts. Although it is very powerful and aesthetically pleasing with smooth animations, it requires a commercial license. It's free for non-commercial use. See http://www.highcharts.com

Chart Types

Each charting library has its own set of chart types. The Charts module focuses on chart types that are available in most of the libraries. To avoid a confusing user interface, the Charts module no longer includes chart types that are not supported by the selected library in the Chart Type selection. For example, if you select the Chart.js library, you will not see the "Gauge" chart type.

Installing Libraries

All the Charts submodules default to using a content delivery network (CDN) to pull in the necessary JavaScript files unless a local copy is present, or you have disabled the CDN option on the "Charts configuration" page (/admin/config/content/charts).

Below are a couple outlines for adding the libraries locally.

Using Composer

1. Ensure that you have the composer/installers package installed.
2. Ensure you have an installer-paths for the drupal-library type. Such as in the composer.json of https://github.com/drupal-composer/drupal-project/blob/9.x/composer.json
3. In each submodule, there is a README.md file that has code to add to your site's composer.json file.
4. After updating your project's composer.json file, run the 'composer require' command specified in each submodule's README.md file. For example, if you are using Google Charts, step three would mean adding:

{
    "type": "package",
    "package": {
        "name": "google/charts",
        "version": "45",
        "type": "drupal-library",
        "extra": {
            "installer-name": "google_charts"
        },
        "dist": {
            "url": "https://www.gstatic.com/charts/loader.js",
            "type": "file"
        },
        "require": {
            "composer/installers": "^1.0 || ^2.0"
        }
    }
}

to your project's composer.json, and then running: composer require --prefer-dist google/charts:45

Using Composer and wikimedia/composer-merge-plugin:

1. Ensure that you have the wikimedia/composer-merge-plugin package installed.
2. Ensure that you have the oomphinc/composer-installers-extender package installed.
3. Add an "installer-types" section in the "extra" of your project composer.json file, make sure you have "npm-asset" listed. For example:

"installer-types": [
    "npm-asset"
],

5. In the "installer-paths" section in the "extra" of your project composer.json file, ensure you have the types drupal-library and npm-asset. For example:

"web/libraries/{$name}": [
    "type:drupal-library",
    "type:npm-asset"
],

6. Add a "merge-plugin" section in the "extra" of your project composer.json file, so that the composer.json file of the submodules you want is included. For example:

"merge-plugin": {
    "include": [
        "web/modules/contrib/charts/modules/charts_highcharts/composer.json"
    ]
},

7. Run the composer require specified in the submodule's README.md file

Creating Charts in the UI

This module provides a configuration page at /admin/config/content/charts. You may set site-wide defaults on this page (for example: set the default color scheme). It also has library-specific configuration available after saving a default library.

There are three options for creating a chart within the UI:

1. Using Views
2. Using a Chart Field
3. Using a Chart Block

Creating Charts with Views

1. Create a new view: Visit admin/structure/views/add and select the display format of "Chart" for your new page or block.

2. Add a label field: Under the "Fields" section, add a field you would like to be used as labels along one axis of the chart (or slices of the pie). If you are visualizing an Event content type, you might select title.

3. Add a data field or fields: Now add a second field that will be used to determine the data values. If you are visualizing an Event content type, this field might be field_number_attendees. The label you give this field will be used in the chart's legend to represent this series. Do this again for each different quantity you would like to chart. Note that some chart types (e.g. "pie") only support a single data column.

4. Configure the chart display: Click on the "Settings" link in the "Format" section to configure the chart. Select your chart library, type, the label field, and the data provider. There are many other options to customize your chart. Some options may not be available to all chart types and will be adjusted based on the type selected.

5. Save your view.

As described in the steps above - if you have a field representing a number, you do not necessarily need to aggregate your view. If the content you want to visualize does not include a numeric field, you may need to aggregate your view and use the count function to generate a number for your data field.

Tip: You may find it easier to start with a "Table" display and convert it to a chart display after setting up the data. It can be easier to visualize what the result of the chart will be if it's been laid out in a table first.

Creating Combo Charts

If you are creating your chart in Views and want to a chart that includes multiple chart types (such as columns and a line - aka a "combo" chart), add a new display of type "Chart attachment". Use the middle column of this display to attach the "Chart attachment" to a parent display (this is required). In this section, you can also instruct the "Chart attachment" to inherit exposed or contextual filters and if it should use the primary y-axis or a secondary y-axis. You still need to configure the "Settings" in the "Format" section.

Creating Charts in the UI with a Chart Field

If you want a chart in your entity (e.g. "node"), but don't need its data to be dynamic (like Views could generate), you can use a Chart field. Add this field to your bundle (e.g. "content type") via the "Manage Fields" tab - like you would any other field. When you add a new entity, you can select the charting library, chart type, and other configurations. You can add data using a CSV or by manually adding it into the table input. The chart will show on your entity after saving.

Creating Charts in the UI with a Chart Block

If you are using Layout Builder or want to place a chart on several pages, and the chart does not need dynamic data (like Views could generate), you can use a Chart Block. When you add a Chart Block, you can select the charting library, chart type, and other configurations. You can add data using a CSV or by manually adding it into the table input.

Creating Charts Using the API

Charts are elements that can be rendered using a Drupal render array. Please refer to the charts.api.php file and also look at the included submodule, charts_api_examples (specifically the controller, which has many examples).

Debugging Your Charts

There is a checkbox in the "Advanced" tab of the config form (/admin/config/content/charts/advanced) that enabled debugging. Checking this box will enable a collapsible "details" element that includes the JSON object generated by the Charts module - this can often be added directly into a code playground provided by the charting library. If you are implementing your own Charts submodule, you can add a line like this into your charts_MYMODULE.js file (it may need modification):

if (element.nextElementSibling &&
element.nextElementSibling.hasAttribute('data-charts-debug-container')) {
   element.nextElementSibling.querySelector('code').innerText = JSON.stringify(
       config,
       null,
       ' '
   );
}

Support

For bug reports and feature requests please use the Drupal.org issue tracker: https://www.drupal.org/project/issues/charts.

We welcome your support in improving code documentation, tests, and providing example use-cases not addressed by the existing module.

If you are interested in creating your own submodule for a library not currently supported, please contact @andileco.