GridView

API reference › yii › grid › GridView

class	yii\grid\GridView
Extends	yii\widgets\BaseListView » yii\base\Widget » yii\base\Component » yii\base\BaseObject
Implements	yii\base\ViewContextInterface, yii\base\Configurable
Since	2.0
Source	framework/grid/GridView.php

1 subclass

• yii\debug\widgets\GridView

The GridView widget is used to display data in a grid.

It provides features like sorting, paging and also filtering the data.

A basic usage looks like the following:

<?= GridView::widget([
    'dataProvider' => $dataProvider,
    'columns' => [
        'id',
        'name',
        'created_at:datetime',
        // ...
    ],
]) ?>

The columns of the grid table are configured in terms of Column classes, which are configured via $columns.

The look and feel of a grid view can be customized using the large amount of properties.

For more details and usage information on GridView, see the guide article on data widgets.

Properties

Property	Type	Description	Defined by
$afterRow	Closure	An anonymous function that is called once AFTER rendering each data model. Default: null.	GridView
$autoIdPrefix static	string	The prefix to the automatically generated widget IDs. Default: 'w'.	yii\base\Widget
$beforeRow	Closure	An anonymous function that is called once BEFORE rendering each data model. Default: null.	GridView
$behaviors read-only	array<yii\base\Behavior<static>>	List of behaviors attached to this component.	yii\base\Component
$caption	string	The caption of the grid table Default: null.	GridView
$captionOptions	array	The HTML attributes for the caption element. Default: [].	GridView
$clientScript	array|yii\web\client\ClientScriptInterface|null	Client script class to use for client-side validation. Default: null.	GridView
$columns	array	Grid column configuration. Default: [].	GridView
$dataColumnClass	string	The default data column class if the class name is not explicitly specified when configuring a data column. Default: null.	GridView
$dataProvider	yii\data\DataProviderInterface	The data provider for the view. Default: null.	yii\widgets\BaseListView
$emptyCell	string	The HTML display when the content of a cell is empty. Default: '&nbsp;'.	GridView
$emptyText	string|false|null	The HTML content to be displayed when $dataProvider does not have any data. Default: null.	yii\widgets\BaseListView
$emptyTextOptions	array	The HTML attributes for the emptyText of the list view. Default: ['class' => 'empty'].	yii\widgets\BaseListView
$filterErrorOptions	array	The options for rendering every filter error message. Default: ['class' => 'field-error'].	GridView
$filterErrorSummaryOptions	array	The options for rendering the filter error summary. Default: ['class' => 'error-summary'].	GridView
$filterModel	yii\base\Model|null	The model that keeps the user-entered filter data. Default: null.	GridView
$filterOnFocusOut	bool	Whatever to apply filters on losing focus. Default: true. Available since 2.0.16.	GridView
$filterPosition	string	Whether the filters should be displayed in the grid view. Default: self::FILTER_POS_BODY.	GridView
$filterRowOptions	array	The HTML attributes for the filter row element. Default: ['class' => 'filters'].	GridView
$filterSelector	string|Closure(string, string): string	JQuery selector for selecting filter input fields. Default: null.	GridView
$filterUrl	string|array|null	The URL for returning the filtering result. Url::to() will be called to normalize the URL. Default: null.	GridView
$footerRowOptions	array	The HTML attributes for the table footer row. Default: [].	GridView
$formatter	array|yii\i18n\Formatter|null	The formatter used to format model attribute values into displayable texts. Default: null.	GridView
$headerRowOptions	array	The HTML attributes for the table header row. Default: [].	GridView
$id	string	Id of the widget.	yii\base\Widget
$layout	string	The layout that determines how different sections of the grid view should be organized. Default: "{summary}\n{items}\n{pager}".	GridView
$options	array	The HTML attributes for the container tag of the grid view. Default: ['class' => 'grid-view'].	GridView
$overrideFilterSelector	bool	If set, $filterSelector overrides the default selector of ’#$id input, #$id select’ (where $id is the filter row ID) rather than being added to it. Default: false.	GridView
$pager	array	The configuration for the pager widget. Default: [].	yii\widgets\BaseListView
$placeFooterAfterBody	bool	Whether to place footer after body in DOM if $showFooter is true Default: false. Available since 2.0.14.	GridView
$rowOptions	array|Closure	The HTML attributes for the table body rows. Default: [].	GridView
$showFooter	bool	Whether to show the footer section of the grid table. Default: false.	GridView
$showHeader	bool	Whether to show the header section of the grid table. Default: true.	GridView
$showOnEmpty	bool	Whether to show the grid view if $dataProvider returns no data. Default: true.	GridView
$sorter	array	The configuration for the sorter widget. Default: [].	yii\widgets\BaseListView
$summary	string|null	The HTML content to be displayed as the summary of the list view. Default: null.	yii\widgets\BaseListView
$summaryOptions	array	The HTML attributes for the summary of the list view. Default: ['class' => 'summary'].	yii\widgets\BaseListView
$tableOptions	array	The HTML attributes for the grid table element. Default: [].	GridView
$view	yii\web\View	The view object that can be used to render views or view files.	yii\base\Widget
$viewPath read-only	string	The directory containing the view files for this widget.	yii\base\Widget

Methods

Method	Description	Defined by
__construct()	Constructor.	yii\base\BaseObject
__call()	Calls the named method which is not a class method.	yii\base\Component
__clone()	This method is called after the object is created by cloning an existing one.	yii\base\Component
__get()	Returns the value of a component property.	yii\base\Component
__isset()	Checks if a property is set, i.e. defined and not null.	yii\base\Component
__set()	Sets the value of a component property.	yii\base\Component
__unset()	Sets a component property to be null.	yii\base\Component
afterRun()	This method is invoked right after a widget is executed.	yii\base\Widget
attachBehavior()	Attaches a behavior to this component.	yii\base\Component
attachBehaviors()	Attaches a list of behaviors to the component.	yii\base\Component
beforeRun()	This method is invoked right before the widget is executed.	yii\base\Widget
begin() static	Begins a widget.	yii\base\Widget
behaviors()	Returns a list of behaviors that this component should behave as.	yii\base\Component
canGetProperty()	Returns a value indicating whether a property can be read.	yii\base\Component
canSetProperty()	Returns a value indicating whether a property can be set.	yii\base\Component
className() static	Returns the fully qualified name of this class.	yii\base\BaseObject
detachBehavior()	Detaches a behavior from the component.	yii\base\Component
detachBehaviors()	Detaches all behaviors from the component.	yii\base\Component
end() static	Ends a widget.	yii\base\Widget
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.	yii\base\Component
getBehavior()	Returns the named behavior object.	yii\base\Component
getBehaviors()	Returns all behaviors attached to this component.	yii\base\Component
getId()	Returns the ID of the widget.	yii\base\Widget
getView()	Returns the view object that can be used to render views or view files.	yii\base\Widget
getViewPath()	Returns the directory containing the view files for this widget.	yii\base\Widget
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.	yii\base\Component
hasMethod()	Returns a value indicating whether a method is defined.	yii\base\Component
hasProperty()	Returns a value indicating whether a property is defined for this component.	yii\base\Component
init()	Initializes the grid view.	GridView
off()	Detaches an existing event handler from this component.	yii\base\Component
on()	Attaches an event handler to an event.	yii\base\Component
render()	Renders a view.	yii\base\Widget
renderCaption()	Renders the caption element.	GridView
renderColumnGroup()	Renders the column group HTML.	GridView
renderEmpty()	Renders the HTML content indicating that the list view has no data.	yii\widgets\BaseListView
renderErrors()	Renders validator errors of filter model.	GridView
renderFile()	Renders a view file.	yii\base\Widget
renderFilters()	Renders the filter.	GridView
renderItems()	Renders the data models for the grid view.	GridView
renderPager()	Renders the pager.	yii\widgets\BaseListView
renderSection()	Renders a section of the specified name.	GridView
renderSorter()	Renders the sorter.	yii\widgets\BaseListView
renderSummary()	Renders the summary text.	yii\widgets\BaseListView
renderTableBody()	Renders the table body.	GridView
renderTableFooter()	Renders the table footer.	GridView
renderTableHeader()	Renders the table header.	GridView
renderTableRow()	Renders a table row with the given data model and key.	GridView
run()	Runs the widget.	GridView
setId()	Sets the ID of the widget.	yii\base\Widget
setView()	Sets the view object to be used by this widget.	yii\base\Widget
trigger()	Triggers an event.	yii\base\Component
widget() static	Creates a widget instance and runs it.	yii\base\Widget
createDataColumn() protected	Creates a DataColumn object based on a string in the format of “attribute:format:label”.	GridView
getClientOptions() protected	Returns the options for the grid view JS widget.	GridView
guessColumns() protected	This function tries to guess the columns to show from the given data if $columns are not explicitly specified.	GridView
initColumns() protected	Creates column objects and initializes them.	GridView

Events

Event	Type	Description	Defined by
EVENT_INIT	yii\base\Event	An event that is triggered when the widget is initialized via init(). Event name: 'init'. Available since 2.0.11.	yii\base\Widget
EVENT_BEFORE_RUN	yii\base\WidgetEvent	An event raised right before executing a widget. Event name: 'beforeRun'. Available since 2.0.11.	yii\base\Widget
EVENT_AFTER_RUN	yii\base\WidgetEvent	An event raised right after executing a widget. Event name: 'afterRun'. Available since 2.0.11.	yii\base\Widget

Constants

Constant	Value	Description	Defined by
FILTER_POS_HEADER	'header'		GridView
FILTER_POS_FOOTER	'footer'		GridView
FILTER_POS_BODY	'body'		GridView

Property details

$afterRow

public Closure $afterRow = null

An anonymous function that is called once AFTER rendering each data model.

It should have the similar signature as $rowOptions. The return result of the function will be rendered directly.

$beforeRow

public Closure $beforeRow = null

An anonymous function that is called once BEFORE rendering each data model.

It should have the similar signature as $rowOptions. The return result of the function will be rendered directly.

$columns

public array $columns = []

Grid column configuration.

Each array element represents the configuration for one particular grid column. For example,

[
    ['class' => SerialColumn::class],
    [
        'class' => DataColumn::class, // this line is optional
        'attribute' => 'name',
        'format' => 'text',
        'label' => 'Name',
    ],
    ['class' => CheckboxColumn::class],
]

If a column is of class DataColumn, the “class” element can be omitted.

As a shortcut format, a string may be used to specify the configuration of a data column which only contains attribute, format, and/or label options: "attribute:format:label". For example, the above “name” column can also be specified as: "name:text:Name". Both “format” and “label” are optional. They will take default values if absent.

Using the shortcut format the configuration for columns in simple cases would look like this:

[
    'id',
    'amount:currency:Total Amount',
    'created_at:datetime',
]

When using a $dataProvider with active records, you can also display values from related records, e.g. the name attribute of the author relation:

// shortcut syntax
'author.name',
// full syntax
[
    'attribute' => 'author.name',
    // ...
]

$dataColumnClass

public string $dataColumnClass = null

The default data column class if the class name is not explicitly specified when configuring a data column.

Defaults to ‘yii\grid\DataColumn’.

$emptyCell

public string $emptyCell = ' '

The HTML display when the content of a cell is empty.

This property is used to render cells that have no defined content, e.g. empty footer or filter cells.

Note that this is not used by the DataColumn if a data item is null. In that case the nullDisplay property of the $formatter will be used to indicate an empty data value.

$filterErrorOptions

public array $filterErrorOptions = ['class' => 'field-error']

The options for rendering every filter error message.

This is mainly used by Html::error() when rendering an error message next to every filter input field.

$filterErrorSummaryOptions

public array $filterErrorSummaryOptions = ['class' => 'error-summary']

The options for rendering the filter error summary.

Please refer to Html::errorSummary() for more details about how to specify the options.

$filterModel

public yii\base\Model|null $filterModel = null

The model that keeps the user-entered filter data.

When this property is set, the grid view will enable column-based filtering. Each data column by default will display a text field at the top that users can fill in to filter the data.

Note that in order to show an input field for filtering, a column must have its DataColumn::$attribute property set and the attribute should be active in the current scenario of $filterModel or have DataColumn::$filter set as the HTML code for the input field.

When this property is not set (null) the filtering feature is disabled.

$filterOnFocusOut

public bool $filterOnFocusOut = true

Whatever to apply filters on losing focus.

Leaves an ability to manage filters via yiiGridView JS

Since

2.0.16

$filterPosition

public string $filterPosition = self::FILTER_POS_BODY

Whether the filters should be displayed in the grid view.

Valid values include:

• FILTER_POS_HEADER: the filters will be displayed on top of each column’s header cell.
• FILTER_POS_BODY: the filters will be displayed right below each column’s header cell.
• FILTER_POS_FOOTER: the filters will be displayed below each column’s footer cell.

$filterSelector

public string|Closure(string, string): string $filterSelector = null

JQuery selector for selecting filter input fields.

If this is a Closure, it gets the widget ID and the filter row ID as parameters and is expected to return the selector.

By default, this selector is added to the default selector ’#$id input, #$id select’ (where $id is the filter row ID). If $overrideFilterSelector is set, this selector is used instead of the default selector.

$filterUrl

public string|array|null $filterUrl = null

The URL for returning the filtering result. Url::to() will be called to normalize the URL.

If not set, the current controller action will be used. When the user makes change to any filter input, the current filtering inputs will be appended as GET parameters to this URL.

$formatter

public array|yii\i18n\Formatter|null $formatter = null

The formatter used to format model attribute values into displayable texts.

This can be either an instance of Formatter or an configuration array for creating the Formatter instance. If this property is not set, the “formatter” application component will be used.

$layout

public string $layout = "{summary}\n{items}\n{pager}"

The layout that determines how different sections of the grid view should be organized.

The following tokens will be replaced with the corresponding section contents:

• {summary}: the summary section. See renderSummary().
• {errors}: the filter model error summary. See renderErrors().
• {items}: the list items. See renderItems().
• {sorter}: the sorter. See renderSorter().
• {pager}: the pager. See renderPager().

$options

public array $options = ['class' => 'grid-view']

The HTML attributes for the container tag of the grid view.

The “tag” element specifies the tag name of the container element and defaults to “div”.

$rowOptions

public array|Closure $rowOptions = []

The HTML attributes for the table body rows.

This can be either an array specifying the common HTML attributes for all body rows, or an anonymous function that returns an array of the HTML attributes. The anonymous function will be called once for every data model returned by $dataProvider. It should have the following signature:

function ($model, $key, $index, $grid)

• $model: the current data model being rendered
• $key: the key value associated with the current data model
• $index: the zero-based index of the data model in the model array returned by $dataProvider
• $grid: the GridView object

Method details

init()

public function init(): mixed

Initializes the grid view.

This method will initialize required property values and instantiate $columns objects.

Returns

mixed

renderCaption()

public function renderCaption(): bool|string

Renders the caption element.

Returns

bool|string: The rendered caption element or false if no caption element should be rendered.

renderColumnGroup()

public function renderColumnGroup(): bool|string

Renders the column group HTML.

Returns

bool|string: The column group HTML or false if no column group should be rendered.

renderErrors()

public function renderErrors(): string

Renders validator errors of filter model.

Returns

string: The rendering result.

renderFilters()

public function renderFilters(): string

Renders the filter.

Returns

string: The rendering result.

renderItems()

public function renderItems(): string

Renders the data models for the grid view.

Returns

string: The HTML code of table

renderSection()

public function renderSection(mixed $name): string|bool

Renders a section of the specified name.

If the named section is not supported, false will be returned.

Parameters

Parameter	Type	Description
$name	mixed	The section name, e.g., {summary}, {items}.

Returns

string|bool: The rendering result of the section, or false if the named section is not supported.

renderTableBody()

public function renderTableBody(): string

Renders the table body.

Returns

string: The rendering result.

renderTableFooter()

public function renderTableFooter(): string

Renders the table footer.

Returns

string: The rendering result.

renderTableHeader()

public function renderTableHeader(): string

Renders the table header.

Returns

string: The rendering result.

renderTableRow()

public function renderTableRow(mixed $model, mixed $key, int $index): string

Renders a table row with the given data model and key.

Parameters

Parameter	Type	Description
$model	mixed	The data model to be rendered
$key	mixed	The key associated with the data model
$index	int	The zero-based index of the data model among the model array returned by $dataProvider.

Returns

string: The rendering result

run()

public function run(): mixed

Runs the widget.

Returns

mixed

createDataColumn()

protected function createDataColumn(string $text): yii\grid\DataColumn

Creates a DataColumn object based on a string in the format of “attribute:format:label”.

Parameters

Parameter	Type	Description
$text	string	The column specification string

Returns

DataColumn: The column instance

Throws

• yii\base\InvalidConfigException: if the column specification is invalid

getClientOptions()

protected function getClientOptions(): array

Returns the options for the grid view JS widget.

Returns

array: The options

guessColumns()

protected function guessColumns(): mixed

This function tries to guess the columns to show from the given data if $columns are not explicitly specified.

Returns

mixed

initColumns()

protected function initColumns(): mixed

Creates column objects and initializes them.

Returns

mixed