Skip to content

Commit fb05d24

Browse files
weaverryanweaverryan
committed
Refactoring all docs to .rst files to host on symfony.com
1 parent 8953ff2 commit fb05d24

File tree

28 files changed

+3633
-3337
lines changed

28 files changed

+3633
-3337
lines changed

‎README.md

+10-10
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
Symfony UX is an initiative and set of libraries to seamlessly
1010
integrate JavaScript tools into your application. For example,
1111
want to render a chart with [Chart.js](https://www.chartjs.org/)? Use
12-
[UX Chart.js](https://github.com/symfony/ux-chartjs)
12+
[UX Chart.js](https://symfony.com/bundles/ux-chartjs/current/index.html)
1313
to build the chart in PHP. The JavaScript is handled for you automatically.
1414

1515
**That's Symfony UX.**
@@ -26,20 +26,20 @@ integrating it into [Webpack Encore](https://github.com/symfony/webpack-encore).
2626

2727
## Packages
2828

29-
- [UX Chart.js](https://github.com/symfony/ux-chartjs):
29+
- [UX Chart.js](https://symfony.com/bundles/ux-chartjs/current/index.html):
3030
[Chart.js](https://www.chartjs.org/) chart library integration for Symfony
31-
- [UX Cropper.js](https://github.com/symfony/ux-cropperjs):
31+
- [UX Cropper.js](https://symfony.com/bundles/ux-cropperjs/current/index.html):
3232
[Cropper.js](https://fengyuanchen.github.io/cropperjs/) image cropper library integration for Symfony
33-
- [UX Dropzone](https://github.com/symfony/ux-dropzone):
33+
- [UX Dropzone](https://symfony.com/bundles/ux-dropzone/current/index.html):
3434
File input drag-and-drop zones for Symfony Forms
35-
- [UX LazyImage](https://github.com/symfony/ux-lazy-image):
35+
- [UX LazyImage](https://symfony.com/bundles/ux-lazy-image/current/index.html):
3636
Improve image loading performances through lazy-loading and data-uri thumbnails
37-
- [UX Swup](https://github.com/symfony/ux-swup):
37+
- [UX Swup](https://symfony.com/bundles/ux-swup/current/index.html):
3838
[Swup](https://swup.js.org/) page transition library integration for Symfony
39-
- [UX Turbo](https://github.com/symfony/ux-turbo): [Hotwire Turbo](https://turbo.hotwired.dev/) library integration for Symfony
40-
- [Twig Component](https://github.com/symfony/ux-twig-component):
39+
- [UX Turbo](https://symfony.com/bundles/ux-turbo/current/index.html): [Hotwire Turbo](https://turbo.hotwired.dev/) library integration for Symfony
40+
- [Twig Component](https://symfony.com/bundles/ux-twig-component/current/index.html):
4141
A system to build reusable "components" with Twig
42-
- [Live Component](https://github.com/symfony/ux-live-component):
42+
- [Live Component](https://symfony.com/bundles/ux-live-component/current/index.html):
4343
Gives Twig Components a URL and a JavaScript library to automatically re-render via Ajax as your user interacts with it
4444

4545
## Stimulus Tools around the World
@@ -68,7 +68,7 @@ fields of your Symfony forms? Or the ability to make the `EntityType` render wit
6868
[AJAX auto-completion](https://tarekraafat.github.io/autoComplete.js)? Anything you
6969
do in JavaScript could be done streamlined as a UX package.
7070

71-
We have some ideas and we will release more packages in the coming days. The rest
71+
We have some ideas, and we will release more packages in the coming days. The rest
7272
is on you: let's create an amazing ecosystem together!
7373

7474
## Contributing

‎src/Chartjs/.symfony.bundle.yaml

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
branches: ["2.x"]
2+
maintained_branches: ["2.x"]
3+
doc_dir: "Resources/doc"

‎src/Chartjs/README.md

+7-156
Original file line numberDiff line numberDiff line change
@@ -3,161 +3,12 @@
33
Symfony UX Chart.js is a Symfony bundle integrating the [Chart.js](https://www.chartjs.org/)
44
library in Symfony applications. It is part of [the Symfony UX initiative](https://symfony.com/ux).
55

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.
78

8-
Symfony UX Chart.js requires PHP 7.2+ and Symfony 4.4+.
9+
## Resources
910

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)

‎src/Chartjs/Resources/doc/index.rst

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

‎src/Cropperjs/.symfony.bundle.yaml

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
branches: ["2.x"]
2+
maintained_branches: ["2.x"]
3+
doc_dir: "Resources/doc"

0 commit comments

Comments
 (0)