2. Your First Grid

In order to use grids, we need to register your entity as a Sylius resource. Let us assume you have a Supplier model in your application, which represents a supplier of goods in your shop and has several fields, including name, description and enabled field.

In order to make it a Sylius resource, you need to configure it under sylius_resource node. If you don’t have it yet, create a file config/packages/sylius_resource.yaml.

# config/packages/sylius_resource.yaml
sylius_resource:
    resources:
        app.supplier:
            driver: doctrine/orm
            classes:
                model: App\Entity\Supplier

That’s it! Your class is now a resource. In order to learn what does it mean, please refer to the SyliusResourceBundle documentation.

2.1. Grid Definition

Now we can configure our first grid:

Note

Remember that a grid is the way objects of a desired entity are displayed on its index view. Therefore only fields that are useful for identification of objects are available - only string and twig type. Then even though a Supplier has also a description field, it is not needed on index and can’t be displayed here.

# config/packages/sylius_grid.yaml
sylius_grid:
    grids:
        app_admin_supplier:
            driver:
                name: doctrine/orm
                options:
                    class: App\Entity\Supplier
            fields:
                name:
                    type: string
                    label: sylius.ui.name
                enabled:
                    type: twig
                    label: sylius.ui.enabled
                    options:
                        template: SyliusUiBundle:Grid/Field:enabled.html.twig # This will be a checkbox field

2.2. Generating The CRUD Routing

That’s it. SyliusResourceBundle allows to generate a default CRUD interface including the grid we have just defined. Just put this in your routing configuration!

# config/routes.yaml
app_admin_supplier:
    resource: |
        alias: app.supplier
        section: admin
        templates: SyliusAdminBundle:Crud
        except: ['show']
        redirect: update
        grid: app_admin_supplier
        vars:
            all:
                subheader: app.ui.supplier # define a translation key for your entity subheader
            index:
                icon: 'file image outline' # choose an icon that will be displayed next to the subheader
    type: sylius.resource
    prefix: admin

This will generate the following paths:

  • /admin/suppliers/ - [GET] - Your grid.
  • /admin/suppliers/new - [GET/POST] - Creating new supplier.
  • /admin/suppliers/{id}/edit - [GET/PUT] - Editing an existing supplier.
  • /admin/suppliers/{id} - [DELETE] - Deleting specific supplier.
  • /admin/suppliers/{id} - [GET] - Displaying specific supplier.

Tip

In the Semantic UI documentation you can find all possible icons you can choose for your grid.

Tip

Adding translations to the grid (read more here):

# translations/messages.en.yaml
app:
    ui:
        supplier: Supplier
        suppliers: Suppliers
    menu:
        admin:
            main:
                additional:
                    header: Additional
                    suppliers: Suppliers

After that your new grid should look like that when accessing the /admin/suppliers/new path in order to create new object:

../../../_images/grid_new.png

And when accessing index on the /admin/suppliers/ path it should look like that:

../../../_images/grid.png

2.3. Defining Filters

In order to make searching for certain things in your grid you can use filters.

sylius_grid:
    grids:
        app_admin_supplier:
                ...
            filters:
                name:
                    type: string
                enabled:
                    type: boolean

How will it look like in the admin panel?

../../../_images/grid_filters.png

What about filtering by fields of related entities? For instance if you would like to filter your suppliers by their country of origin, which is a property of the associated address entity.

This first requires a custom repository method for your grid query:

# config/packages/sylius_grid.yaml
sylius_grid:
    grids:
        app_admin_supplier:
            driver:
                name: doctrine/orm
                options:
                    class: App\Entity\Supplier
                    repository:
                        method: mySupplierGridQuery

Note

The repository method has to return a queryBuilder object, since the query has to adjustable depending on the filters and sorting the user later applies. Furthermore, all sub entities you wish to use later for filtering have to be joined explicitely in the query.

Then you can set up your filter to accordingly:

sylius_grid:
    grids:
        app_admin_supplier:
                ...
            filters:
                ...
                country:
                    type: string
                    label: origin
                    options:
                        fields: [address.country]
                    form_options:
                        type: contains

2.4. Default Sorting

You can define by which field you want the grid to be sorted and how.

# config/packages/sylius_grid.yaml
sylius_grid:
    grids:
        app_admin_supplier:
                ...
            sorting:
                name: asc
                ...

Then at the fields level, define that the field can be used for sorting:

# config/packages/sylius_grid.yaml
sylius_grid:
    grids:
        app_admin_supplier:
            ...
            fields:
                name:
                    type: string
                    label: sylius.ui.name
                    sortable: ~
                ...

If your field is not of a “simple” type, f.i. a twig template with a specific path, you get sorting working with the following definition:

# config/packages/sylius_grid.yaml
sylius_grid:
    grids:
        app_admin_supplier:
            ...
            fields:
                ....
                origin:
                    type: twig
                    options:
                        template: "@App/Grid/Fields/myCountryFlags.html.twig"
                    path: address.country
                    label: app.ui.country
                    sortable: address.country
                ...

2.6. Actions Configuration

Next step is adding some actions to the grid: create, update and delete.

Note

There are two types of actions that can be added to a grid: main which “influence” the whole grid (like adding new objects) and item which influence one row of the grid (one object) like editing or deleting.

# config/packages/sylius_grid.yaml
sylius_grid:
    grids:
        app_admin_supplier:
                ...
            actions:
                main:
                    create:
                        type: create
                item:
                    update:
                        type: update
                    delete:
                        type: delete

This activates such a view on the /admin/suppliers/ path:

../../../_images/grid_full.png

Your grid is ready to use!