• Example
• Chart settings
• Category column settings
• Data column settings
• Extra data column settings
• Chart groups
  • By xaxis category types and non-category
  • By scalar and vector yaxis values
• Chart data source structure
  • Helpers to convert data source structure
• Chart options
  • Flattened options array
• Support

ApexCharts

Example #

<?php
ColumnChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "title"=>"Sale Amount On Each Category"
    "columns"=>array(
        "category",
        "amount"=>array(
            "label"=>"Amount",
            "type"=>"number",
            "prefix"=>'$',
        )
    ),
))
?>

In above example, we use datastore category_amount as the dataSource for ColumnChart. We set the title for the chart to "Sale Amount On Each Category". We specify columns from datastore to be used for drawing chart. The first column category will be acted as label for xAxis while amount will be value for yAxis. We add extra settings for amount columns to make dollar sign appear in front of number.

We may add more data column to columns, for each added columns, new chart series will be added.

Chart settings #

Category column settings #

Data column settings #

Extra data column settings #

Example for column settings:

ColumnChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "category",
        "amount"=>array(
            "label"=>"Amount",
            "type"=>"number",
            "prefix"=>'$',
        )
    ),
));

SynchChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "category",
        "amount"=>array(
            "label"=>"Amount",
            "chartType"=>"line",
            "chartColor=>"blue",
            "charts"=>[1],
        ),
        "profit"=>array(
            "label"=>"Profit",
            "chartType"=>"column",
            "chartColor=>"green",
            "charts" => [2],
        ),        
    ),
));
?>

Chart groups #

There are several criteria to divide chart types into main groups.

By xaxis category types and non-category #

Based on xaxis category types, we have discrete types such as string, integer categories; continuous types such as datetime, real number; or non-category types such as scatter, bubble charts that only requires series of 2-dimension, 3-dimension coordinates. With category charts, the first column is by default the category one. You can set its category type with "categoryType" property:

ColumnChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "month" => array( // category column
            "categoryType" => "category", //discrete categories, categoryType value is "category" by default
        ),
        "sales" => array() // data column
    ),
));

ColumnChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "datetime" => array( // category column
            "categoryType" => "datetime", //continuous categories
        ),
        "sales" => array() // data column
    ),
));

In case all you have is data columns you can set autoCategoryColumn setting to true to create auto numeric categories (1, 2, 3, 4, etc).

With non-category charts, all columns are data columns by default:

        \koolreport\apexcharts\ScatterChart::create(array(
            "dataSource" => $data,
            "columns" => array(
                'SAMPLE A' => [ // data column, no category column
                    'combination' => [
                        'SampleA_x',
                        'SampleA_y',
                    ]
                ],
            ),
        ));

By scalar and vector yaxis values #

Based on yaxis value, we have scalar value (i.e single, non-vector, numeric values) types that most charts are; vector value types such as rangebar, timeline that requires 2-D dimension vectors or candlestick, boxplot that requires 4-dimension, 5-dimension vectors.

Scalar charts are straighforward, each data column is one series. Vector charts' columns need to combine several columns to create one series with combination column property. Here are examples for both types:

ColumnChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "month",
        "revenue", //scalar value
        "profit", //scalar value
    ),
));

RangeAreaChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "month",
        "temperature range" => array( // 2-dimension vector value
            "combination" => array(
                "lowest_day_sales",
                "hight_day_sales",
            )
        )
    ),
));

CandleStickChart::create(array(
    "dataSource"=>$this->dataStore("category_amount"),
    "columns"=>array(
        "columns" => array(
            'trade_date',
            'stock_price' => [ // 4-dimension vector value
                'combination' => [
                    'open',
                    'high',
                    'low',
                    'close',
                ]
            ]
        ),
    ),
));

Chart data source structure #

All ApexCharts widgets use data source in table structure where one or none column acts as category column and others act as data columns. Here's an example of a data source with one category column and two data columns:

        $data_line_chart = [
            [
                'year', // category column
                'series-1', // data column
                'series-2', // data column
            ],
            [
                "2001", // category value
                44, // data value
                53 // data value
            ],
            [
                "2002", // category value
                55, // data value
                32 // data value
            ],
            ...
        ];

        $data_scatter_chart = [
            [
                'SampleA_x', // data column
                'SampleA_y' // data column
            ],
            [
                16.4, // data value
                5.4 // data value
            ],
            [
                21.7, // data value
                2 // data value
            ],
            ...
        ];

Helpers to convert data source structure #

KoolReport Pro and ApexCharts package provides several methods and properties to convert other data structures into one its widgets can use.

One common case is that instead of single data table, users have multiple tables for multiple categories. In a lot of those cases they can use the following mergeDatasets method to merge multiples tables into one:

        $data_bob = [
            [
                'phase',
                'bob_start',
                'bob_end',
            ],
            [
                "Design",
                "2019-3-5",
                "2019-3-8"
            ],
            [
                "Code",
                "2019-3-2",
                "2019-3-5"
            ],
            ...
        ];
        $data_joe = [
            [
                'phase',
                'joe_start',
                'joe_end',
            ],
            [
                "Design",
                "2019-3-2",
                "2019-3-5"
            ],
            [
                "Test",
                "2019-3-6",
                "2019-3-16"
            ],
            ...
        ];
        $data = \koolreport\apexcharts\Chart::mergeDatasets(
            $data_bob,
            $data_joe
        );
        \koolreport\apexcharts\TimeLineChart::create(array(
            "dataSource" => $data,
            "columns" => array(
                "phase" => [],
                "Bob" => [
                    "combination" => [
                        "bob_start",
                        "bob_end",
                    ]
                ],
                "Joe" => [
                    "combination" => [
                        "joe_start",
                        "joe_end",
                    ]
                ],
            ],
            ...
        ]);

The common "phase" column will be used as the join column to merge the two datasets.

Another usual situation is when users want to tranpose a data table, i.e flip the table across its diagonal line so that the first row becomes the first column and vice versa:

        $data = [
            [
                'category',
                "W1",
                "W2",
                "W3",
                "W4",
                "W5"
            ],
            [
                "13:00",
                0,
                63,
                35,
                40,
                85
            ],
            [
                "13:30",
                72,
                78,
                67,
                50,
                75
            ]
            ...
        ];
        $transposeData = \koolreport\core\Utility::transpose($data);
        \koolreport\apexcharts\HeatMapChart::create(array(
            "dataSource" => $transposeData,
            "columns" => $transposeData[0],
            ...
        ));
        /* After tranposed:
        $transposedData = [
            [
                "category",
                "13:00",
                "13:30",
                ...
            ],
            [
                "W1",
                0,
                72,
                ...
            ],
            [
                "W2",
                63,
                78,
                ...
            ],
            [
                "W3",
                35,
                67,
                ...
            ],
            [
                "W4",
                40,
                50,
                ...
            ],
            [
                "W5",
                85,
                75,
                ...
            ],    
        ]
        */

Finally, sometimes users want to divide a single data table into multiple data series based on a specific column where each of the column's unique value separates a series. Consider the following example:

        $data = [
            [
                'name',
                'position',
                'date_start',
                'date_end',
            ],
            [
                "George Washington",
                "President",
                "1789/4/30",
                "1797/3/4"
            ],
            [
                "John Adams",
                "President",
                "1797/3/4",
                "1801/3/4"
            ],
            [
                "John Adams",
                "Vice President",
                "1789/4/21",
                "1797/3/4"
            ],
            [
                "Thomas Jefferson",
                "President",
                "1801/3/4",
                "1809/3/4"
            ],
            [
                "Thomas Jefferson",
                "Vice President",
                "1797/3/4",
                "1801/3/4"
            ],
            ...
        ];
        \koolreport\apexcharts\TimeLineChart::create(array(
            "dataSource" => $data,
            "columns" => [
                'name' => [
                    'seriesGroup' => true,
                ],
                'position',
                'term' => [
                    'combination' => [
                        'date_start',
                        'date_end',
                    ],
                ],
            ],
            ...
        ));
        /* This data and chart setup is equivalent to the following one:
        $data = [
            [
                'position',
                'George Washington__date_start',
                'George Washington__date_end',
                'John Adams__date_start',
                'John Adams__date_end',
                'Thomas Jefferson__date_start',
                'Thomas Jefferson__date_end',
            ],
            [
                "President",
                "1789/4/30",
                "1797/3/4",
                "1797/3/4",
                "1801/3/4",
                "1801/3/4",
                "1809/3/4"
            ],
            [
                "Vice President",
                null,
                null,
                "1789/4/21",
                "1797/3/4"
                "1797/3/4",
                "1801/3/4"
            ],
        ];
        \koolreport\apexcharts\TimeLineChart::create(array(
            "dataSource" => $data,
            "columns" => [
                'position',
                'George Washington' => [
                    'combination' => [
                        'George Washington__date_start',
                        'George Washington__date_end',
                    ],
                ],
                'John Adams' => [
                    'combination' => [
                        'John Adams__date_start',
                        'John Adams__date_end',
                    ],
                ],
                'Thomas Jefferson' => [
                    'combination' => [
                        'Thomas Jefferson__date_start',
                        'Thomas Jefferson__date_end',
                    ],
                ]
            ],
            ...
        ));
        */

The seriesGroup column property is a very convenient way to create series dynamically instead of knowing the number of series and their names in advance.

Chart options #

Beside a chart's settings, you can set detail options in its options array property. Full detail options can be found in ApexCharts' documentation link:

ApexCharts client-side options

To use them, convert an option's JSON object to PHP array and put it in ApexCharts widget's options like this:

\koolreport\apexcharts\LineChart::create(array(
    ...
    "options" => [
        'grid' => [
            'row' => [
                'colors' => [
                    '#f3f3f3',
                    'transparent',
                ],
                'opacity' => 0.5,
            ],
        ],
    ],
    ...
));

https://apexcharts.com/docs/options/grid/#row

Flattened options array #

As a convenience for ApexCharts users, the package allows flattening options array for deep options like this:

\koolreport\apexcharts\LineChart::create(array(
    ...
    "options" => [
        'grid | row | opacity' => 0.5, // is equivalent to
        'grid' => [
            'row' => [
                'opacity' => 0.5
            ]
        ],
        ...
    ],
    ...
));

The following options are equivalent in this package and one might find one way preferable to others for their specific situations:

\koolreport\apexcharts\LineChart::create(array(
    ...
    "options" => [
        'a | b | c | d1 | e | f' => 'value1',
        'a | b | c | d2 | e | f' => 'value2',

        'a | b | c' => [
            'd1 | e | f' => 'value1',
            'd2 | e | f' => 'value2'
        ],
        
        'a' => [
            'b' => [
                'c' => [
                    'd1 | e | f' => 'value1',
                    'd2 | e | f' =>'value2'
                ]
            ]
        ],

        'a | b | c' => [
            'd1' => [
                'e' => [
                    'f' => 'value1'
                ]
            ],
            'd2' => [
                'e' => [
                    'f' => 'value2'
                ]
            ]
        ],

        'a' => [
            'b' => [
                'c' => [
                    'd1' => [
                        'e' => [
                            'f' => 'value1'
                        ]
                    ],
                    'd2' => [
                        'e' => [
                            'f' => 'value2'
                        ]
                    ]
                ]
            ]
        ],
    ],
    ...
));

Support #

Please use our forum if you need support, by this way other people can benefit as well. If the support request need privacy, you may send email to us at support@koolreport.com.