Merge pull request #6312 from TheMadeleine/docs/grid-bundle

[Documentation][Bundles] SyliusGridBundle docs update

docs/bundles/SyliusGridBundle/configuration.rst

@@ -1,38 +1,42 @@
 Configuration Reference
 =======================
 
+Here you will find all configuration options of ``sylius_grid``.
+
 .. code-block:: yaml
 
     sylius_grid:
         grids:
-            app_user: # Your grid name.
-                driver: doctrine/orm # Data source driver.
-                resource: app.user # Resource name.
+            app_user: # Your grid name
+                driver:
+                    name: doctrine/orm # Data source driver
+                    options:
+                        class: AppBundle\Entity\user
+                resource: app.user # Resource name
                 sorting:
-                    name: asc
-                columns:
                     name:
-                        type: twig # Type of column.
-                        label: Name # Label.
+                        path: name
+                        direction: asc
+                fields:
+                    name:
+                        type: twig # Type of field
+                        label: Name # Label
+                        path: name
                         sortable: true
                         options:
                             template: :Grid/Column:_name.html.twig # Only twig column
-                            path: name
-                            sort: name
                 filters:
-                    group:
-                        type: entity
-                        label: Group
-                        options:
-                            entity: AppBundle:Group
+                    name:
+                        type: string # Type of filter
+                        label: app.ui.name
                 actions:
-                    edit:
-                        type: link
-                        options:
-                            route: app_user_update
-                bulk_actions:
-                    delete:
-                        type: delete
-                    copy:
-                        type: copy
-
+                    main:
+                        create:
+                            type: create
+                    item:
+                        update:
+                            type: update
+                        delete:
+                            type: delete
+                        show:
+                            type: show

docs/bundles/SyliusGridBundle/custom_field_type.rst

@@ -0,0 +1,67 @@
+Custom Field Type
+=================
+
+There are certain cases when built-in field types are not enough. Sylius Grids allows to define new types with ease!
+
+All you need to do is create your own class implementing FieldTypeInterface and register it as a service.
+
+.. code-block:: php
+
+    <?php
+
+    namespace AppBundle\Grid\FieldType;
+
+    use Sylius\Component\Grid\Definition\Field;
+    use Sylius\Component\Grid\FieldTypes\FieldTypeInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    class CustomType implements FieldTypeInterface
+    {
+        public function render(Field $field, $data, array $options = [])
+        {
+            // Your rendering logic... Use Twig, PHP or even external api...
+        }
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver
+                ->setDefaults([
+                    'dynamic' => false
+                ])
+                ->setAllowedTypes([
+                    'dynamic' => ['boolean']
+                ])
+            ;
+        }
+
+        public function getName()
+        {
+            return 'custom';
+        }
+    }
+
+That is all. Now register your new field type as a service.
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    app.grid_field.custom:
+        class: AppBundle\Grid\FieldType\CustomType
+        tags:
+            - { name: sylius.grid_field, type: custom }
+
+Now you can use your new column type in the grid configuration!
+
+.. code-block:: yaml
+
+    sylius_grid:
+        grids:
+            app_admin_supplier:
+                driver:
+                    name: doctrine/orm
+                    options:
+                        class: AppBundle\Entity\Supplier
+                fields:
+                    name:
+                        type: custom
+                        label: sylius.ui.name

docs/bundles/SyliusGridBundle/custom_filter.rst

@@ -1,9 +1,9 @@
 Custom Filter
 =============
 
-Sylius grids come with a lot of built-in filters, but there are use-cases where you need something more than basic filter. Grids allow you to define your own filter types!
+Sylius Grids come with built-in filters, but there are use-cases where you need something more than basic filter. Grids allow you to define your own filter types!
 
-To add a new filter, we need to create appropriate class and form type.
+To add a new filter, we need to create an appropriate class and form type.
 
 .. code-block:: php
 
@@ -12,12 +12,12 @@ To add a new filter, we need to create appropriate class and form type.
     namespace App\Grid\Filter;
 
     use Sylius\Component\Grid\Data\DataSourceInterface;
-    use Sylius\Component\Grid\Filter\FilterInterface;
+    use Sylius\Component\Grid\Filtering\FilterInterface;
     use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
-    class TournamentStatisticsFilter implements FilterInterface
+    class SuppliersStatisticsFilter implements FilterInterface
     {
-        public function apply(DataSourceInterface $dataSource, $data, array $options = array())
+        public function apply(DataSourceInterface $dataSource, $name, $data, array $options = array())
         {
             // Your filtering logic. DataSource is kind of query builder.
             // $data['stats'] contains the submitted value!
@@ -37,7 +37,7 @@ To add a new filter, we need to create appropriate class and form type.
 
         public function getType()
         {
-            return 'tournament_statistics'
+            return 'supplier_statistics';
         }
     }
 
@@ -72,28 +72,36 @@ And the form type:
             ;
         }
 
-        public function getType()
+        public function getName()
         {
             return 'sylius_filter_tournament_statistics'; // The name is important to be sylius_filter_NAME
         }
     }
 
-That is all. Now let register your new filter type as service.
+Create a template for the filter, similar to the existing ones:
+
+.. code-block:: html
+
+    # AppBundle/Resources/views/Grid/Filter/suppliers_statistics.html.twig
+    {% form_theme form 'SyliusUiBundle:Form:theme.html.twig' %}
+
+    {{ form_row(form) }}
+
+That is all. Now let's register your new filter type as service.
 
 .. code-block:: yaml
 
     # app/config/services.yml
 
     services:
-        app.grid.filter.tournament_statistics:
-            class: App\Grid\Filter\TournamentStatisticsFilter
+        app.grid.filter.suppliers_statistics:
+            class: AppBundle\Grid\Filter\SuppliersStatisticsFilter
             tags:
-                - { name: sylius.grid_filter, type: tournament_statistics }
-        app.form.type.filter.tournament_statistics:
-            class: AppBundle\Form\Type\Filter\TournamentStatisticsFilterType
+                - { name: sylius.grid_filter, type: suppliers_statistics }
+        app.form.type.grid.filter.suppliers_statistics:
+            class: AppBundle\Form\Type\Filter\SuppliersStatisticsFilterType
             tags:
-                - { name: form.type, alias: sylius_filter_tournament_statistics }
-
+                - { name: form.type, alias: sylius_grid_filter_suppliers_statistics }
 
 Now you can use your new filter type in the grid configuration!
 
@@ -109,3 +117,6 @@ Now you can use your new filter type in the grid configuration!
                         type: tournament_statistics
                         options:
                             range: [0, 100]
+        templates:
+            filter:
+                suppliers_statistics: "AppBundle:Grid/Filter:suppliers_statistics.html.twig"

docs/bundles/SyliusGridBundle/field_configuration.rst

@@ -0,0 +1,26 @@
+Field configuration
+===================
+
+Each field can be configured with several configuration keys, to make it more suitable to your grid requirements.
+
++------------+------------+-----------------------------------------------------------------------------------------------------------+
+| Name       | Type       | Description                                                                                               |
++============+============+===========================================================================================================+
+| type       | string     | Type of column. Default field types are described :doc:`here </bundles/SyliusGridBundle/field_types>`.    |
++------------+------------+-----------------------------------------------------------------------------------------------------------+
+| label      | string     | Label displayed in the field header. By default, it is field name.                                        |
++------------+------------+-----------------------------------------------------------------------------------------------------------+
+| path       | string     | Path to property displayed in field (can be property of resource or one of its referenced objects).       |
++------------+------------+-----------------------------------------------------------------------------------------------------------+
+| options    | array      | Array of field options (see below).                                                                       |
++------------+------------+-----------------------------------------------------------------------------------------------------------+
+
+``options`` field can contains following fields:
+
++------------+--------------+-------------------------------------------------------------------------------------------------------------+-------------+
+| Name       | Type         | Description                                                                                                 | Default     |
++============+==============+=============================================================================================================+=============+
+| template   | string       | Available (and required) only for *twig* column type. Path to template that is used to render column value. |             |
++------------+--------------+-------------------------------------------------------------------------------------------------------------+-------------+
+| format     | string       | Available only for *datetime* field type.                                                                   | Y:m:d H:i:s |
++------------+--------------+-------------------------------------------------------------------------------------------------------------+-------------+