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 app/config/resources.yml, import it in the app/config/config.yml.

# app/config/resources.yml
sylius_resource:
    resources:
        app.supplier:
            driver: doctrine/orm
            classes:
                model: AppBundle\Entity\Supplier
# app/config/config.yml
imports:
    - { resource: "resources.yml" }

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.

# app/config/grids/admin/supplier.yml
sylius_grid:
    grids:
        app_admin_supplier:
            driver:
                name: doctrine/orm
                options:
                    class: AppBundle\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

Remember to import your grid in the app/config/grids/grids.yml file which has to be imported in the app/config/config.yml.

# app/config/grids/grids.yml
imports:
    - { resource: 'admin/supplier.yml' }
# app/config/config.yml
imports:
    - { resource: "grids/grids.yml" }

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!

# app/config/routing/admin/supplier.yml
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
# app/config/routing/admin.yml
app_admin_supplier:
    resource: 'supplier.yml'
# app/config/routing.yml
app_admin:
    resource: 'routing/admin.yml'
    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):

# app/Resources/translations/messages.en.yml
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:

# app/config/grids/admin/supplier.yml
sylius_grid:
    grids:
        app_admin_supplier:
            driver:
                name: doctrine/orm
                options:
                    class: AppBundle\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.

# app/config/grids/admin/supplier.yml
sylius_grid:
    grids:
        app_admin_supplier:
                ...
            sorting:
                name: asc
                ...

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

# app/config/grids/admin/supplier.yml
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:

# app/config/grids/admin/supplier.yml
sylius_grid:
    grids:
        app_admin_supplier:
            ...
            fields:
                ....
                origin:
                    type: twig
                    options:
                        template: "@AppBundle/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.

# app/config/grids/admin/supplier.yml
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!