README

Google Charts the Yii 2.0 way

yii2-gcharts is a collection of widgets to render selected Google Charts in the Yii 2.0 PHP Framework, like you would use a GridView.

Currently, yii2-gcharts consists of the following widgets:

• AreaChart
• BarChart
• BubbleChart
• ColumnChart
• GeoChart
• LineChart
• PieChart
• ScatterChart

A demonstration of Yii2-gcharts is here.

Installation

Install yii2-gcharts with Composer. Either add the following to the require section of your composer.json file:

"sjaakp/yii2-gcharts": "*"

Or run:

composer require sjaakp/yii2-gcharts "*"

You can manually install yii2-gcharts by downloading the source in ZIP-format.

Using yii2-gcharts

Use the yii2 charts widgets just like you would use a GridView. For instance, in the Controller you might have something like:

<?php
// ...
public function actionPie()	{
	$dataProvider = new ActiveDataProvider([
		'query' => Country::find(),
	    'pagination' => false
	]);
	
	return $this->render('pie', [
		'dataProvider' => $dataProvider
	]);
}
// ...
?>

To render a PieChart in the View we could use:

<?php
use sjaakp\gcharts\PieChart;
?>
...
<?= PieChart::widget([
    'height' => '400px',
    'dataProvider' => $dataProvider,
    'columns' => [
        'name:string',
        'population'
    ],
    'options' => [
        'title' => 'Countries by Population'
    ],
]) ?>
...

Each of the chart types has slight variations in the column interpretation, and its own set of options. Consult the Google Charts documentation.

Options

All the yii2-gcharts widgets share the same options:

dataProvider

The data provider for the chart. This property is required. In most cases, it will be an ActiveDataProvider or an ArrayDataProvider.

columns

Chart column configuration array. Each array element configures one chart column. Each column configuration is an array or a string shortcut.

An array column configuration can have the following members (all are optional, but at least one must be given):

• attribute The attribute name associated with this column. When value is not specified, the value of the attribute will be retrieved from each data model.

• formatted The Google Charts formatted version of the data. Can be a callable of the form function($model, $attribute, $index, $widget).

• label The label assigned to the data. If not given, it is either retrieved from the model or derived from attribute.

• pattern The Google Charts pattern.

• role The Google Charts role. Can be one of:

  • "annotation"
  • "annotationText"
  • "certainty"
  • "emphasis"
  • "interval"
  • "scope"
  • "style"
  • "tooltip"

• type The Google Charts data type. Can be one of:

  • "number" (default)
  • "string"
  • "boolean"
  • "date"
  • "datetime"
  • "timeofday"

• value The data value. This can be a callable of the form function($model, $attribute, $index, $widget). If not given, the value of the model's attribute is taken.

The string shortcut configuration specifies the attribute, type, and label in the format "attribute:type:label". Both type and label are optional; they take their default values if omitted.

mode

string This determines which variant of the chart is drawn. Must be one of:

• "classic" (default) Draws the 'ordinary' version of the chart,
• "material" Draws the new, Material version of the chart, if available,
• "transition" Draws the Material version, if available, and also applies convertOptions() to the options

Notice that only a few of the charts are currently available in Material version and that they're in early beta, lacking lots of the 'classic' options.

Notice also that currently, the Material options are undocumented, so the only practical way to work with Material charts is using the "transition" mode.

version

string The version of the gcharts library used. Must be one of:

• "current" (default),
• "upcoming",
• number

More information.

mapsApiKey

string Applies to GeoChart only. It is advised to provide GeoChart with an API-key of Google Maps.