|
3 | 3 | Symfony UX Chart.js is a Symfony bundle integrating the [Chart.js](https://www.chartjs.org/) |
4 | 4 | library in Symfony applications. It is part of [the Symfony UX initiative](https://symfony.com/ux). |
5 | 5 |
|
6 | | -## Installation |
| 6 | +**This repository is a READ-ONLY sub-tree split**. See |
| 7 | +https://github.com/symfony/ux to create issues or submit pull requests. |
7 | 8 |
|
8 | | -Symfony UX Chart.js requires PHP 7.2+ and Symfony 4.4+. |
| 9 | +## Resources |
9 | 10 |
|
10 | | -Install this bundle using Composer and Symfony Flex: |
11 | | - |
12 | | -```sh |
13 | | -composer require symfony/ux-chartjs |
14 | | - |
15 | | -# Don't forget to install the JavaScript dependencies as well and compile |
16 | | -yarn install --force |
17 | | -yarn encore dev |
18 | | -``` |
19 | | - |
20 | | -Also make sure you have at least version 3.0 of [@symfony/stimulus-bridge](https://github.com/symfony/stimulus-bridge) |
21 | | -in your `package.json` file. |
22 | | - |
23 | | -## Usage |
24 | | - |
25 | | -To use Symfony UX Chart.js, inject the `ChartBuilderInterface` service and |
26 | | -create charts in PHP: |
27 | | - |
28 | | -```php |
29 | | -// ... |
30 | | -use Symfony\UX\Chartjs\Builder\ChartBuilderInterface; |
31 | | -use Symfony\UX\Chartjs\Model\Chart; |
32 | | - |
33 | | -class HomeController extends AbstractController |
34 | | -{ |
35 | | - #[Route('/', name: 'app_homepage')] |
36 | | - public function index(ChartBuilderInterface $chartBuilder): Response |
37 | | - { |
38 | | - $chart = $chartBuilder->createChart(Chart::TYPE_LINE); |
39 | | - |
40 | | - $chart->setData([ |
41 | | - 'labels' => ['January', 'February', 'March', 'April', 'May', 'June', 'July'], |
42 | | - 'datasets' => [ |
43 | | - [ |
44 | | - 'label' => 'My First dataset', |
45 | | - 'backgroundColor' => 'rgb(255, 99, 132)', |
46 | | - 'borderColor' => 'rgb(255, 99, 132)', |
47 | | - 'data' => [0, 10, 5, 2, 20, 30, 45], |
48 | | - ], |
49 | | - ], |
50 | | - ]); |
51 | | - |
52 | | - $chart->setOptions([ |
53 | | - 'scales' => [ |
54 | | - 'y' => [ |
55 | | - 'suggestedMin' => 0, |
56 | | - 'suggestedMax' => 100, |
57 | | - ], |
58 | | - ], |
59 | | - ]); |
60 | | - |
61 | | - return $this->render('home/index.html.twig', [ |
62 | | - 'chart' => $chart, |
63 | | - ]); |
64 | | - } |
65 | | -} |
66 | | -``` |
67 | | - |
68 | | -All options and data are provided as-is to Chart.js. You can read |
69 | | -[Chart.js documentation](https://www.chartjs.org/docs/latest/) to discover them all. |
70 | | - |
71 | | -Once created in PHP, a chart can be displayed using Twig if installed |
72 | | -(requires [Symfony Webpack Encore](https://symfony.com/doc/current/frontend/encore/installation.html)): |
73 | | - |
74 | | -```twig |
75 | | -{{ render_chart(chart) }} |
76 | | -
|
77 | | -{# You can pass HTML attributes as a second argument to add them on the <canvas> tag #} |
78 | | -{{ render_chart(chart, {'class': 'my-chart'}) }} |
79 | | -``` |
80 | | - |
81 | | -### Extend the default behavior |
82 | | - |
83 | | -Symfony UX Chart.js allows you to extend its default behavior using a custom Stimulus controller: |
84 | | - |
85 | | -```js |
86 | | -// mychart_controller.js |
87 | | - |
88 | | -import { Controller } from '@hotwired/stimulus'; |
89 | | - |
90 | | -export default class extends Controller { |
91 | | - connect() { |
92 | | - this.element.addEventListener('chartjs:pre-connect', this._onPreConnect); |
93 | | - this.element.addEventListener('chartjs:connect', this._onConnect); |
94 | | - } |
95 | | - |
96 | | - disconnect() { |
97 | | - // You should always remove listeners when the controller is disconnected to avoid side effects |
98 | | - this.element.removeEventListener('chartjs:pre-connect', this._onPreConnect); |
99 | | - this.element.removeEventListener('chartjs:connect', this._onConnect); |
100 | | - } |
101 | | - |
102 | | - _onPreConnect(event) { |
103 | | - // The chart is not yet created |
104 | | - console.log(event.detail.options); // You can access the chart options using the event details |
105 | | - |
106 | | - // For instance you can format Y axis |
107 | | - event.detail.options.scales = { |
108 | | - yAxes: [ |
109 | | - { |
110 | | - ticks: { |
111 | | - callback: function (value, index, values) { |
112 | | - /* ... */ |
113 | | - }, |
114 | | - }, |
115 | | - }, |
116 | | - ], |
117 | | - }; |
118 | | - } |
119 | | - |
120 | | - _onConnect(event) { |
121 | | - // The chart was just created |
122 | | - console.log(event.detail.chart); // You can access the chart instance using the event details |
123 | | - |
124 | | - // For instance you can listen to additional events |
125 | | - event.detail.chart.options.onHover = (mouseEvent) => { |
126 | | - /* ... */ |
127 | | - }; |
128 | | - event.detail.chart.options.onClick = (mouseEvent) => { |
129 | | - /* ... */ |
130 | | - }; |
131 | | - } |
132 | | -} |
133 | | -``` |
134 | | - |
135 | | -Then in your render call, add your controller as an HTML attribute: |
136 | | - |
137 | | -```twig |
138 | | -{{ render_chart(chart, {'data-controller': 'mychart'}) }} |
139 | | -``` |
140 | | - |
141 | | -## Backward Compatibility promise |
142 | | - |
143 | | -This bundle aims at following the same Backward Compatibility promise as the Symfony framework: |
144 | | -[https://symfony.com/doc/current/contributing/code/bc.html](https://symfony.com/doc/current/contributing/code/bc.html) |
145 | | - |
146 | | -However it is currently considered |
147 | | -[**experimental**](https://symfony.com/doc/current/contributing/code/experimental.html), |
148 | | -meaning it is not bound to Symfony's BC policy for the moment. |
149 | | - |
150 | | -## Run tests |
151 | | - |
152 | | -### PHP tests |
153 | | - |
154 | | -```sh |
155 | | -php vendor/bin/phpunit |
156 | | -``` |
157 | | - |
158 | | -### JavaScript tests |
159 | | - |
160 | | -```sh |
161 | | -cd Resources/assets |
162 | | -yarn test |
163 | | -``` |
| 11 | +- [Documentation](https://symfony.com/bundles/ux-chartjs/current/index.html) |
| 12 | +- [Report issues](https://github.com/symfony/ux/issues) and |
| 13 | + [send Pull Requests](https://github.com/symfony/ux/pulls) |
| 14 | + in the [main Symfony UX repository](https://github.com/symfony/ux) |
0 commit comments