Download the PHP package avpretty/grid-bundle without Composer

• Overview
• Installation
• Grid View
  • Nested Grid View
• Grid Filters
  • Full Example
  • Filter By Relation
• Columns
  • Data Column
  • Counter Column
  • Action Column
• Sort
  • Relation Sort
• Pagination

Overview

Allows you to quickly display the data of any entity or array in the form of a table. This table already contains filtering, sorting and pagination.

So using 9 lines of code you can build something like this

Installation

install the GridBundle executing this console command in your project:

Update your AppKernel.php:

GridBundle contains js and css and you need to include them manually. To use code example below the AsseticBundle must be installed:

NOTE: GridBundle uses bootstrap framework and jQuery.

Grid View

GridView is the main component that allows you to create and manage you grid. Each grid for each entity or array requires new instance of GridView.

Shortest way to create new grid:

And update your template:

DONE!

GridViewBundle provides a lot of options for configure your grid. Detailed explanation of sorting, filtering, pagination and columns options are described in corresponding sections of this documentation.

Extended example:

GridView options: Grid filter options:

• dataSource - Provides data for grid. Should implement BaseDataSource interface.
  • Type: BaseDataSource
  • Required: yes
• containerOptions - List of html attributes that will be applied to grid container.
  • Type: array
  • Required: no
  • Example: ['containerOptions' => ['data-type' => 'grid-container', 'class' => 'outer']]
• tableOptions - List of html attributes that will be applied to grid table. Here you can override table css style.
  • Type: array
  • Required: no
  • Example: ['tableOptions' => ['class' => 'table table-hover']]
• tableCaption - Grid table caption.
  • Type: string
  • Required: no
  • Example: ['tableCaption' => 'Table Caption']
• showHeader - Whether the table header row will be shown.
  • Type: bool
  • Required: no
• headerRowOptions - List of html attributes that will be applied to grid table header row.
  • Type: array
  • Required: no
• rowOptions - Options for grid table rows.
  • Type: array
  • Required: no
• filterRowOptions - List of html attributes that will be applied row that contains filters.
  • Type: array
  • Required: no
• emptyCell - Value that will be used for empty table cell.
  • Type: string
  • Required: no
• filterEntity - Instance of target entity that will be used for creating filter fields.
  • Type: object
  • Required: no
• filterUrl - Target url which will accept filter data. Current route will be used by default.
  • Type: string
  • Required: no

Nested Grid

You can insert one grid into another. To do this you need to render nested grid manually:

Grid Filters

By default grid filters are disabled. To enable them add next code to your grid configuration:

Specifying entity instance you allowed to build filter fields.

By default filter fields will be created for each entity attributes. But you also can add filter fields for custom column.

Example:

NOTE: If you won't specify filter type then symfony will try to guess it. Concerning this you might got an error Unable to transform value for property path.... The main reason of this is doctrine fields validation so there are two options: manually specify filter type like shown above or remove validation.

You can get all available filter types at symfony's form documentation as well as filter options.

In case of using ArrayDataSource you should still specify filter entity (any).

Grid filter options:

• filterEntity - Entity instance that will be used to build filter form.
  • Type: object
  • Example: 'filterEntity' => new User,
• filterUrl - Target url which will accept filter data. Current route will be used by default.
  • Type: string
  • Example: 'filterUrl' => 'custom-url'

Full example for User entity. We have next fields: firstName, lastName and created. Let's create search method in UserRepository:

Now let's describe our filters in Controller:

Now filter form will be displayed and you are able to work with incoming filter data.

Filters with relations

Also you can apply filters to related entities. For example we will be using User entity and related Country entity. Let's create dropdown filter by country.

NOTE!!!: TO BE ABLE TO USE FILTRATION ON RELATED ENTITIES YOU SHOULD SPECIFY THOSE ENTITIES IN YOUR QUERY BUILDER. DO NOT USE PROXY OBJECTS.

Example:

Some explanation to example above: attributeName is compulsory and it's value should be specified in User entity. You also can specify arbitrary value of attributeName BUT selected filter value won't be remembered by form field UNLESS you add this field to target (User) entity.

Columns

Columns provides simple interface for controlling data displaying within grid. There are three types of columns and one base interface BaseColumn:

• Column
• ActionColumn
• CounterColumn

Column

Responsible for rendering common data within grid. This type of column displays all user data such as entities or arrays. There are a bunch of display options that can be customize by user.

For example we will be using QueryDataSource of User entity.Our entity contains next fields: firstName, lastName, age, email, created.

Simple example:

NOTE: If we just omit column configuration the result will be the same.

In case of using relations you can use next syntax:

Extended example:

Column options:

• attributeName - Entity field name or key name in case of using ArrayDataSource.
  • Type: string
  • Example: 'attributeName' => 'lastName'
  • Required: yes if there no content value
• label - Column header label. If not specified then attributeName will be used.
  • Type: string
  • Example: 'label' => 'Column Label'
  • Required: yes if there no attributeName value
• encodeLabel - Whether the header will be encoded. False by default.
  • Type: string
  • Example: 'encodeLabel' => true
  • Required: no
• content - Column cell content. This parameter can contain string value or callback function.
  • Type: string|callable
  • Example: 'content' => 'custom string contetn' . Callback function example was shown above.
  • Required: no
• contentOptions - List of option that will be applied to content cell.
  • Type: array|callable
  • Example: 'contentOptions' => ['width' => '100px']
  • Required: no
• format - Format of column cell data. Default ColumnFormat::TEXT_FORMAT
  • Type: string
  • Example: 'contentOptions' => ['width' => '100px']
  • Required: no
• visible - Whether the column should be visible. Parameter can accept bool value or callable.
  • Type: bool|callable
  • Example: 'visible' => false
  • Required: no
• sortable - Whether the column is sortable.
  • Type: bool
  • Example: 'sortable' => false
  • Required: no
• filterType - Filter input field type. Can apply one of Symfony form input types.
  • Type: string
  • Example: 'filterType' => EmailType::class
  • Required: no
• filterFieldOptions - List of options that will be applied to filter input field. Text field type options
  • Type: array
  • Required: no
• filterOptions - List of option that will be applied to filter cell.
  • Type: array
  • Example: 'filterOptions' => ['class' => 'custom-filter-cell-class']
  • Required: no

CounterColumn

Provides simple counter for table rows. Included by default for both data sources QueryDataSource and ArrayDataSource.

Inherits most properties of data column.

Example:

ActionColumn

Action columns allows to create control buttons for each grid row. For now there are two types of buttons: show, edit. Each button configurable. Action columns will be included to grid by default IF you are using QueryDataSource in other case you should specify it manually.

NOTE: By default all action buttons will be visible and will use the current route. Also there is no need to specify each button manually. They will be displayed by default.

Example:

Each button has two configurable options: url, visibility. Both options accept both a scalar value and a callback function.

If you are using callback function there are two arguments available:

• entity instance
• default button url

buttons and hiddenButtons values are optional. By default for url creation will be used current route with show path and edit respectively.

For example if current url is .../admin/user/ then for show button will be generated next url .../admin/user/{userId}/show until you won't change it.

Column data format

This component allow to apply different format type to Column data. There are four available formats:

• ColumnFormat::TEXT_FORMAT - Default column cell data format. Encodes all html, js or twig entities.
• ColumnFormat::RAW_FORMAT - No encoding at all. Can be use to apply some html or js to column cell data.
• ColumnFormat::TWIG_FORMAT - Allows to use any twig constructions.
• ColumnFormat::DATE_FORMAT - Date formatting. For now there are only two date formats that can be formatted: timestamp (int|string), \DateTime, \DateInterval.

Example:

DataSource

This entity acts as an intermediary between the grid and the data source. It is this component that creates the final query and passes the result of its execution to the grid component that works with the BaseDataSource interface.

There are two entities that implements BaseDataSource:

• QueryDataSource
• ArrayDataSource

QueryDataSource

QueryDataSource allows to pass your instance of QueryBuilder to grid. Example:

NOTE: There is no need to manually configure sort and pagination for QueryDataSource. Each instance of BaseDataSource is created with sort and pagination with default params. For example if we did not specify sorting params then all field of User entity will be sortable.

Now we can get user entities with sorting and pagination settings, using fetchEntities:

NOTE: As mentioned above we should specify entity alias like we did it for User. Concerning this we should ALWAYS specify entity alias for QueryDataSource. If you won't do this then alias will be taken from entity name and it will be User. The reason of this is default sorting configuration that should know full field name. From the other hand you will use constructions like JOIN.

ArrayDataSource

ArrayDataSource allows to pass your array data to grid.

Example:

Now we can pass our $dataSource to grid and it will be properly displayed.

NOTE: We did not set alias u for sorting as in case of QueryDataSource. We should use only array keys while working with ArrayDataSource.

Sort

The sorting component allows you to flexibly set and expand the sorting parameters for specific attributes. You can use this component with one of the data source component (QueryDataSource or ArrayDataSource).

Let's assume that we have User entity with next fields:

• firstName
• lastName
• email

Example:

If attribute name specified without any params then default params will be used. Next example shows how the email attribute will be interpreted.

The attribute names used in the configuration are the names of the entity fields if you are using the QueryDataSource and the array keys name if you are using the ArrayDataSource.

NOTE: In expanded attribute configuration we used custom field title name but specified sortable fields using specified alias u. In case of short notation we should specify entity alias like we did it with u.email.

Attribute options:

• Sort::ASC - Configuration of ascend sorting. This param defines sorting by one or multiply attributes. Although this param defines ascend sorting it's allowed to use both types of sorting for any attributes.
  • Type: array
  • Required: no
  • Example: Sort::ASC => ['first_name' => Sort::ASC, 'last_name' => Sort::ASC]
• Sort::DESC - See Sort::ASC
  • Type: array
  • Required: no
  • Example: Sort::DESC => ['first_name' => Sort::DESC, 'age' => Sort::ASC]
• default - Default sort params. This sort type will be used by default.
  • Type: string
  • Required: no
  • Example: ['default' => Sort::DESC]
• label - Attribute name that will be used in request string. If label was not defined attribute name will be used.
  • Type: string
  • Required: no
  • Example: ['label' => 'FullName']

There are few additional params of Sort instance that can be configured:

• sortParam - The name of the parameter that will contain the sorting data in the query string. This param can be changed to allow multiply sort instances on single page. Default value sort.
  • Type: string
  • Example: $sortInstance->setSortParam('customSortParam')
• separator - Symbol that uses to separate sort attributes in query string. Default value ,.
  • Type: string
  • Required: no
  • Example: $sortInstance->setSeparator('.')
• defaultOrder - Default sort params.
  • Type: array
  • Required: no
  • Example: $sortInstance->setDefaultOrder(['email' => Sort::DESC])

Relation Sort

As well as filter you can sort by related entities fields. For example we will be using User entity and related Country entity.

NOTE!!!: TO BE ABLE TO USE SORT ON RELATED ENTITIES YOU SHOULD SPECIFY THOSE ENTITIES IN YOUR QUERY BUILDER. DO NOT USE PROXY OBJECTS.

Example:

Some explanation to example above: c is Country entity alias that you should specify in you query builder.

Pagination

Pagination component allows you to easily limit the amount of data displayed on the page. This component consists from three parts:

• Pagination - responsible for the managing of the parameters of limitation and offset of QueryBuilder.
• PaginationView - responsible for the building of the pagination block. Also this component generates pagination links.
• PaginationExtension - twig extension for rendering pagination block.

Pagination example:

Using these parameters, the pagination component is able to generate the values of the limit and offset based on the query parameters.

NOTE: There might be a names conflict. For example one of your routes already uses page query param name. In that case you can rename page param name:

Pagination options:

• pageSize - Number of items per page.
  • Type: int
  • Example: $pagination->setPageSize(10)
  • Required: no
• totalCount - Total number of items.
  • Type: int
  • Required: yes
  • Example: $pagination->setTotalCount(100)
• pageParam - Name of query parameter that contains page number. This param can be changed to allow multiply pagination blocks on single page. Default value page.
  • Type: string
  • Required: no
  • Example: $pagination->setPageParam('customPageName') // .../?per-page=3&customPageName=3
• pageSizeParam - Name of query parameter that contains number of items on page. This param can be changed to allow multiply pagination blocks on single page. Default value per-page.
  • Type: string
  • Required: no
  • Example: $pagination->setPageSizeParam('customPageSize')
• route - Name of route. If route was not specified then current route will be used.
  • Type: string
  • Required: no
  • Example: $pagination->setRoute('post_index')
• defaultPageSize - Default number of items per page. Will be used if pageSize was not specified. Default 20.
  • Type: int
  • Required: no
  • Example: $pagination->setDefaultPageSize(50)

NOTE: BaseDataSource instances already contains pagination instance. So there is no need to specify pagination instance manually and set it to QueryDataSource or ArrayDataSource. Instead default pagination configuration will be used.

To display pagination block call twig extension in you template:

gridPagination extension can apply additional params. ALL PARAMETERS ARE OPTIONAL: