Issue #3277589 by 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.

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

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

        ],

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:

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

        "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

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

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

Charts

======

The Charts module provides a unified format to build any kind of chart with any

chart provider.

Each chart solution found on internet, such as Google Charts or Highcharts,

has a specific data scheme. Its very hard and even impossible to build a unique

chart data scheme that would be used in more that one chart provider. Or users

get bound to a solution forever. Or they have to rewrite all exported data

again.

That's why Charts is so great. It uses a standard data scheme to describe charts

data, and through filters, it automatically converts to each solution. You can

change to another solution at anytime.

The Chart schema is very similar to Drupal's Form API schema.

Chart Providers

---------------

Out of the Box, you will be able to use 4 chart solutions. Each of them has

particular advantages and disadvantages.

* C3: This library is a D3-based reusable chart library makes it easy to

  generate D3-based charts by wrapping the code required to construct the

  entire chart. You don't need to write D3 code any more.

* Chart.js: This is a simple yet flexible JavaScript charting for designers

  & developers.

* Google Charts: This library does not require any external downloads. It

  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

Installing Libraries

---------------------

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/8.x/composer.json

3: In each sub-module, there is a README.txt file that you can use to copy the

   info inside the composer.json of your project.

4: After updating your project's composer.json file, run the 'composer require'

   command specified in each sub-module's README.txt 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

There are numerous tutorials on Drupal.org and elsewhere on the web if you are

looking for more information about how to use Composer with Drupal 8.

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"

     ],

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:

     "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 sub-modules you want is included.

   For example:

     "merge-plugin": {

         "include": [

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

         ]

     },

6: Run the 'composer require' specified in the sub-module's README.txt 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).

In order to actually create a chart through the UI, you'll need to use Views

module.

- Create a new view:

  Visit admin/structure/views/add and select the display format of "Chart" for

  your new page or block.

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

- Add data fields:

  Now 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 charts

  (e.g. Pie) only support a single data column.

- Configure the chart display:

  Click on the "Settings" link in the Format section to configure the chart.

  Select your chart type. Some options may not be available to all chart types

  and will be adjusted based on the type selected.

- Save your view.

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 Multiple Series and Combo Charts in the UI

---------------------------------------------------

A major difference between the Drupal 7 and Drupal 8 versions of this module is

that the Drupal 8 module uses a Chart Attachment plugin for creating a separate

chart series that can be attached to a parent display.

Using Charts with custom Views Fields

-------------------------------------

If you are using custom views fields (extended from

Drupal\views\Plugin\views\field\FieldPluginBase) to generate numbers or other

data, you will need to set the getValue() function in your custom field to

return your data. Data returned in render() is not used when building the chart.

You may look in src/Util/Util.php to see how the field data is extracted and

used by the Charts module.

Support

-------

For bug reports and feature requests please use the Drupal.org issue tracker:

http://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 sub-module for a library not

currently supported (for example, Flot), please contact @andileco

#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

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

To see the example, navigate to:

/charts/example/display

Settings for this chart derive from the Charts module's 

default settings, which are configured here:

/admin/config/content/charts

charts_api_example:

  version: VERSION

  js:

    js/charts_api_example_js_override.js: { weight: -5 }

  dependencies:

    - charts/global