Welcome To Our Shell

Mister Spy & Souheyl Bypass Shell

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