README

Wrapper for chart js in Yii2. Easily turn Yii2 querys into beautiful charts.

Installation

The preferred way is with composer.

composer require practically/yii2-chartjs

Note: This package does not handle the installation of chart js library. For that you can visit the chart js website

You can also install with the asset packagist

composer require bower-asset/chart-js

Chart JS Versions

Please note that there are API changes in the clientOptions of the config for chart js between versions 2 and 3. We have documented the basic API for this library in the relevent sections of the docs. If you are updating to v3 you can find more info in the Chart JS 3.x Migration Guide

There may be some changes in the way you import the Chat JS javascript depending on the way you have implemented it in your application. You can read more about integration on the Chart JS Documentation

Usage

Basic usage

use practically\chartjs\Chart;

echo Chart::widget([
    'type' => Chart::TYPE_BAR,
    'datasets' => [
        [
            'data' => [
                'Label 1' => 10,
                'Label 2' => 20,
                'Label 3' => 30
            ]
        ]
    ]
]);

Using a db query to define the data

echo Chart::widget([
    'type' => Chart::TYPE_BAR,
    'datasets' => [
        [
            'query' => Model::find()
                ->select('type')
                ->addSelect('count(*) as data')
                ->groupBy('type')
                ->createCommand(),
            'labelAttribute' => 'type'
        ]
    ]
]);

Using a db query with a scatter chart

echo Chart::widget([
    'type' => Chart::TYPE_SCATTER,
    'datasets' => [
        [
            'query' => Model::find()
                ->select('type')
                ->addSelect('sum(column_one) as x')
                ->addSelect('sum(column_two) as y')
                ->groupBy('type')
                ->createCommand(),
            'labelAttribute' => 'type'
        ]
    ]
]);

Adding dom options

echo Chart::widget([
    ...

    'options' => [
        'class' => 'chart',
        'data-attribute' => 'my-value'
    ],

    ...
]);

Adding client options

In the client options array you can define any property to be json encoded and passed to the chart js constructor.

echo Chart::widget([
    ...

    'clientOptions' => [
        'title' => [
            'display' => true,
            'text' => 'My New Title',
        ],
        'legend' => ['display' => false],
    ]

    ...
]);

Formatting the y axes

echo Chart::widget([
    ...

     'clientOptions' => [
        'scales' => [
            'yAxes' => [
                [
                    'ticks' => [
						'min' => 0,
						'max' => 100,
						'callback' => new JsExpression('function(value, index, values) {
                             return \'£\'+value;
                        }')
                    ],
					'scaleLabel' => [
						'display' => true,
						'labelString' => 'Average (%)',
					]
				]
			]
        ],
        'tooltips' => [
            'callbacks' => [
                'label' => new JsExpression('function(tooltipItem, chart) {
                    var datasetLabel = chart.datasets[tooltipItem.datasetIndex].label || \'\';
                    return datasetLabel + \' £\'+tooltipItem.yLabel;
                }')
            ]
        ]
    ]

    ...
]);

echo Chart::widget([
    ...

     'clientOptions' => [
        'scales' => [
            'y' => [
				'min' => 0,
				'max' => 100,
				'title' => [
					'display' => true,
					'text' => 'Average (%)',
				],
				'ticks' => [
					'callback' => new JsExpression('function(value, index, values) {
							return \'£\'+value;
					}')
				]
            ]
        ],
		'plugins' => [
			'tooltip' => [
				'callbacks' => [
					'label' => new JsExpression('function(context) {
						return \'£\'+context.chart.data.labels[context.dataIndex];
					}')
				]
			]
		]
    ]

    ...
]);

Adding chart js events

Chart::widget([
    'type' => Chart::TYPE_DOUGHNUT,
    'jsVar' => 'DoughnutChart',
    'jsEvents' => [
        'onclick' => new JsExpression('function(e) {
            var el = DoughnutChart.getElementAtEvent(e);
            window.location.href = "/search/ + el[0]._model.label;
        }')
    ]
]);

Contributing

Getting set up

Clone the repo and run composer install. Then start hacking!

Testing

All new features of bug fixes must be tested. Testing is with phpunit and can be run with the following command

composer run-script test

Coding Standards

This library uses psr2 coding standards and squizlabs/php_codesniffer for linting. There is a composer script for this:

composer run-script lint

Pull Requests

Before you create a pull request with you changes, the pre-commit script must pass. That can be run as follows:

composer run-script pre-commit

Credits

This package is created and maintained by Practically.io