opensaucesystems/chartwire

Charts.js for Livewire

v1.0.0 2021-01-08 21:31 UTC

This package is auto-updated.

Last update: 2021-04-08 22:14:43 UTC


README

Chart.wire are simple charts for use with Laravel Livewire.

Requirements ^

This package requires the following packages/libraries:

Installation ^

You can install the package via composer:

composer require opensaucesystems/chartwire

Usage ^

Chart.wire supports out of the box the following types of charts

  • Line Chart
  • Bar Chart
  • Doughnut Chart
  • Pie Chart
  • Area Chart
  • Sparkline Chart

Each one comes with its own "model" class that allows you to define the chart's data and render behavior.

  • Line Chart uses LineChartModel
  • Bar Chart uses BarChartModel
  • Doughnut Chart uses DoughnutChartModel
  • Pie Chart uses PieChartModel
  • Area Chart uses AreaChartModel
  • Sparkline Chart uses SparklineChartModel

For example, to render a line chart, we create an instance of LineChartModel and pass it to the Livewire Line Chart component:

$colors = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(54, 162, 235, 0.6)',
    'border' => 'rgba(54, 162, 235, 0.6)',
    'pointBackground' => 'rgba(54, 162, 235, 0.6)',
]);

$lineChartModel = (new \Opensaucesystems\Chartwire\Models\LineChartModel())
    ->addDataToDataset('Populations 2020', 1405544000, 'China', $colors)
    ->addDataToDataset('Populations 2020', 1370279686, 'India', $colors)
    ->addDataToDataset('Populations 2020', 330736378, 'United States', $colors)
    ->addDataToDataset('Populations 2020', 269603400, 'Indonesia', $colors)
    ->addDataToDataset('Populations 2020', 220892331, 'Pakistan', $colors)
    ->addDataToDataset('Populations 2020', 212404659, 'Brazil', $colors)
    ->addDataToDataset('Populations 2020', 206139587, 'Nigeria', $colors);
<livewire:line-chartwire :line-chart-model="$lineChartModel" />

Chart Model Methods ^

Common methods

These methods are common to all chart models

MethodArgumentsDescription
addDataToDatasetstring $datasetName name of the dataset
string|int|float $value data value
string $label data label
Opensaucesystems\Chartwire\Values\ColorValue $color color of data on chart
null|string $type chart type
array $extras extra chart options
Add data to chart dataset
reactiveKeyreturns a string based on its data
setOptionsarray $options chart.js optionsThis will override any of the options set by the model methods as well as the default options. See Chart.js docs


Legend methods

The following chart types support these methods:

  • Line Chart
  • Bar Chart
  • Doughnut Chart
  • Pie Chart
  • Area Chart
MethodArgumentsDescription
withLegendShow legend
withoutLegendHide legend
legendPositionTopSet legend position to top
legendPositionLeftSet legend position to left
legendPositionRightSet legend position to right
legendPositionBottomSet legend position to bottom
legendHorizontallyAlignedLeftAlign legend horizontal left
legendHorizontallyAlignedCenterAlign legend horizontal center
legendHorizontallyAlignedRightAlign legend horizontal right


Axis methods

The following chart types support these methods:

  • Line Chart
  • Bar Chart
  • Doughnut Chart
  • Pie Chart
  • Area Chart
MethodArgumentsDescription
withoutXAxisHide x-axis
withXAxisShow x-axis
withoutYAxisHide y-axis
withYAxisShow y-axis


Title methods

The following chart types support these methods:

  • Line Chart
  • Bar Chart
  • Doughnut Chart
  • Pie Chart
  • Area Chart
MethodArgumentsDescription
withTitleShow title
withoutTitleHide title
setTitleTextstring $textSet chart title
titlePositionTopSet title position to top
titlePositionLeftSet title position to left
titlePositionRightSet title position to right
titlePositionBottomSet title position to bottom


Event methods

The following chart types support these methods:

  • Line Chart
  • Bar Chart
  • Doughnut Chart
  • Pie Chart
  • Area Chart
MethodArgumentsDescription
withOnClickEventNamestring $onClickEventNameLivewire event name that will be fired when chart data is clicked

When an event of type mouseup or click is triggered on the chart, then Livewire will emit an event with the name of the argument passed into this method. It will also pass the label and value that was clicked.

$lineChartModel = (new \Opensaucesystems\Chartwire\Models\LineChartModel())
    ->withOnClickEventName('onMyLineChartClicked');

Now you may register this event in another components $listeners property:

class ShowData extends Component
{
    public $label;
    public $value;

    protected $listeners = ['onMyLineChartClicked' => 'handleMyLineChartClicked'];

    public function handleMyLineChartClicked(array $data)
    {
        $this->label = $data['label'];
        $this->value = $data['value'];
    }
}


Stacked methods

The following chart types support these methods:

  • Line Chart
  • Bar Chart
  • Area Chart
MethodArgumentsDescription
isStackedbool $stacked = trueStacked charts can be used to show how one data is made up of a number of smaller pieces.


Sparkline charts ^

Sparkline charts are just a normal Line Chart with the default options hiding the legend, title, axes, tooltips etc.

To set the height and width of the Sparline Chart just use CSS.

This examples use TailwindCSS:

$colors = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(54, 162, 235, 0.6)',
    'border' => 'rgba(54, 162, 235, 0.6)',
])

$sparklineChartModel = (new \Opensaucesystems\Chartwire\Models\SparklineChartModel())
        ->addDataToDataset('Populations 2020', 1405544000, 'China', $colors)
        ->addDataToDataset('Populations 2020', 1370279686, 'India', $colors)
        ->addDataToDataset('Populations 2020', 330736378, 'United States', $colors)
        ->addDataToDataset('Populations 2020', 269603400, 'Indonesia', $colors)
        ->addDataToDataset('Populations 2020', 220892331, 'Pakistan', $colors)
        ->addDataToDataset('Populations 2020', 212404659, 'Brazil', $colors)
        ->addDataToDataset('Populations 2020', 206139587, 'Nigeria', $colors);
<div class="h-10 w-20">
    <livewire:sparkline-chartwire :sparkline-chart-model="$sparklineChartModel" />
</div>


Colors ^

Each dataset requires a ColorValue object.

The ColorValue instance requires a border color. The background and pointBackground is optional.

The color can be simple a hexadecimal, RGB, or their color names.

$colors = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'border' => 'rgba(54, 162, 235, 0.6)',
])

Since Chart.js supports a CanvasGradient object, the ColorValue supports a LinearGradientValue object that is converted into a JS CanvasGradient object.

use Opensaucesystems\Chartwire\Values\ColorStopValue;
use Opensaucesystems\Chartwire\Values\LinearGradientValue;

$backgroundColorStops = [
    new ColorStopValue(['color' => 'rgba(54, 162, 235, 0.6)', 'offset' => 0]),
    new ColorStopValue(['color' => 'rgba(54, 162, 235, 0)', 'offset' => 1]),
];
$borderColorStops = [
    new ColorStopValue(['color' => '#80b6f4', 'offset' => 0]),
    new ColorStopValue(['color' => '#f49080', 'offset' => 1]),
];

$backgroundGradient = new LinearGradientValue([
    'x1' => 0,
    'y1' => 100,
    'x2' => 0,
    'y2' => 370,
    'colorStops' => $backgroundColorStops,
])
$borderGradient = new LinearGradientValue([
    'x1' => 500,
    'y1' => 0,
    'x2' => 100,
    'y2' => 0,
    'colorStops' => $borderColorStops,
]);


Multiple Datasets ^

You can also add multiple datasets to a chart that will allow you to group data.

Stacked

Stacked charts allows you to see that data is made up of a number of smaller pieces.

$colors2010 = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(54, 162, 235, 0.6)',
    'border' => 'rgba(54, 162, 235, 1)',
]);
$colors2020 = new \Opensaucesystems\Chartwire\Values\ColorValue([
    'background' => 'rgba(37, 194, 160, 0.6)',
    'border' => 'rgba(37, 194, 160, 1)',
]);

$barChartModel = (new \Opensaucesystems\Chartwire\Models\BarChartModel())
    ->addDataToDataset('Populations 2010', 1339724852, 'China', $colors2010)
    ->addDataToDataset('Populations 2010', 1182105564, 'India', $colors2010)
    ->addDataToDataset('Populations 2010', 309349689, 'United States', $colors2010)
    ->addDataToDataset('Populations 2010', 237641326, 'Indonesia', $colors2010)
    ->addDataToDataset('Populations 2010', 173510000, 'Pakistan', $colors2010)
    ->addDataToDataset('Populations 2010', 193252604, 'Brazil', $colors2010)
    ->addDataToDataset('Populations 2010', 158258917, 'Nigeria', $colors2010)
    ->addDataToDataset('Populations 2020', 1405544000, 'China', $colors2020)
    ->addDataToDataset('Populations 2020', 1370279686, 'India', $colors2020)
    ->addDataToDataset('Populations 2020', 330736378, 'United States', $colors2020)
    ->addDataToDataset('Populations 2020', 269603400, 'Indonesia', $colors2020)
    ->addDataToDataset('Populations 2020', 220892331, 'Pakistan', $colors2020)
    ->addDataToDataset('Populations 2020', 212404659, 'Brazil', $colors2020)
    ->addDataToDataset('Populations 2020', 206139587, 'Nigeria', $colors2020);
<livewire:bar-chartwire :bar-chart-model="$barChartModel" />

Troubleshooting ^

Chart components must be placed inside a container with fixed height. This is because the chart will use all the given vertical space. A fixed height is needed to render properly.

<div style="height: 32rem;">
    <livewire:livewire-column-chart .../>
</div>

>Note: if a fixed height is not given, the chart will grow vertically infinitely. That's not what we want, right?

Testing ^

composer test

Changelog ^

Please see CHANGELOG for more information what has changed recently.

Contributing ^

Please see CONTRIBUTING for details.

Security ^

If you discover any security related issues, please email ashley@opensauce.systems instead of using the issue tracker.

Credits and Influences ^

License ^

The MIT License (MIT). Please see License File for more information.