Issue #3277589 by nikathone, andileco: Clean up code documentation, add return types, etc.

#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.

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.

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.

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.

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.

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

* 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

##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).

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:

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:

```json

{

    "type": "package",

    "package": {

        }

    }

}

```

   to your project's composer.json, and then running:

        composer require --prefer-dist google/charts:45

   `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:

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:

```json

"installer-types": [

    "npm-asset"

],

4. 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:

```

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:

```json

"web/libraries/{$name}": [

    "type:drupal-library",

    "type:npm-asset"

],

5. 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:

```

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:

```json

"merge-plugin": {

    "include": [

        "web/modules/contrib/charts/modules/charts_highcharts/composer.json"

    ]

},

6: Run the `composer require` specified in the submodule's README.md file

```

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.

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

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.

   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`.

   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.

   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.

   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.

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.

**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.

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.

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.

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).

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).

## Support

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

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.

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 (https://www.drupal.org/u/andileco).

If you are interested in creating your own submodule for a library not

currently supported, please contact

[@andileco](https://www.drupal.org/u/andileco).

<?php

/**

 * @file Charts - Module.

 * @file

 * Charts - Module.

 */

use Drupal\views\ViewExecutable;

<?php

/**

 * @file Charts post-update file.

 * @file

 * Charts post-update file.

 */

use Drupal\Core\Serialization\Yaml;

}

/**

 * Update the existing default config display colors to increase them

 * from 10 to 25.

 * Update the existing default config display colors to increase from 10 to 25.

 */

function charts_post_update_existing_default_colors_to_twenty_five(&$sandbox) {

  $config = \Drupal::service('config.factory')->getEditable('charts.settings');

#Charts API Example

This module shows you how to create charts using render arrays. There are numerous examples in the `ChartsApiExample.php` controller file. In the `charts_api_example.module` file, you can also see how some hooks described in `charts.api.php` can be used. One hook overrides a chart using PHP. Another overrides with JavaScript - this is necessary in some cases when the charting library API is expecting a function rather than a string. You can read more about overriding with JavaScript here: https://www.drupal.org/project/charts/issues/3197574#comment-13999765

This module shows you how to create charts using render arrays. There are

numerous examples in the `ChartsApiExample.php` controller file. In the

`charts_api_example.module` file, you can also see how some hooks described in

`charts.api.php` can be used. One hook overrides a chart using PHP. Another

overrides with JavaScript - this is necessary in some cases when the charting

library API is expecting a function rather than a string. You can read more

about overriding with JavaScript here:

https://www.drupal.org/project/charts/issues/3197574#comment-13999765

To see the examples in your site, navigate to: /charts/example/display

To see the examples in your site, navigate to: `/charts/example/display`

Settings for these charts are set in the Charts configuration page (/admin/config/content/charts).

Settings for these charts are set in the Charts configuration page

(`/admin/config/content/charts`).

use Drupal\views\ViewExecutable;

/**

 * Util.

 * Utilities class containing various helper methods.

 */

class Util {