Options
All
  • Public
  • Public/Protected
  • All
Menu

Class 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:

let grid = new MyGridView({
      dataProvider,
      filterModel,
      columns: [
        { class: CheckboxColumn },
        { class: RadioButtonColumn },
        { class: SerialColumn },
        'id',
        'title',
        { class: ActionColumn, visibleButtons: { update: false } },
      ],
    });

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.

author

Mahesh S Warrier maheshs60@gmail.com

since

1.0

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

Protected _models

_models: Model[] = []

caption

caption: string = ''

The caption of the grid table

see

captionOptions

captionOptions

captionOptions: {} = {}

The HTML attributes for the caption element.

see

Html.renderTagAttributes for details on how attributes are being rendered.

see

caption

Type declaration

  • [key: string]: any

columns

columns: (string | column)[]

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

[
    { class: SerialColumn },
    {
        class: DataColumn, // this line is optional
        attribute: 'name',
        label: 'Name',
    },
    { class: CheckboxColumn },
]

If a column is of class DataColumn, the "class" property can be omitted.

As a shortcut format, a string may be used to specify the configuration of a data column which only contains attribute 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:text:Total Amount',
    'created_at:text',
]

Note: Format is now restricted to 'text' only. You can convert the data to a specific format by using callbacks as of now:

[ 'id', 'title:text:Company Name', { title: 'Created Date', value: (model, attribute) => (new Date(form.startDate.value)).toString('dd MMMM yyyy') } ]

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

dataColumnClass: typeof DataColumn = DataColumn

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

dataProvider

dataProvider: DataProvider
var

\yii\data\DataProviderInterface the data provider for the view. This property is required.

emptyCell

emptyCell: string = ' '

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.

emptyText

emptyText: string | false

The HTML content to be displayed when dataProvider does not have any data. When this is set to false no extra HTML content will be generated. The default value is the text "No results found."

see

showOnEmpty

see

emptyTextOptions

emptyTextOptions

emptyTextOptions: {} = ...

Type declaration

  • [key: string]: any

enablePjax

enablePjax: boolean = true

Whether to enable Pjax on this widget.

filterErrorOptions

filterErrorOptions: {} = ...

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.

Type declaration

  • [key: string]: any

filterErrorSummaryOptions

filterErrorSummaryOptions: {} = ...

The options for rendering the filter error summary. Please refer to Html.errorSummary for more details about how to specify the options.

see

renderErrors

Type declaration

  • [key: string]: any

filterModel

filterModel: Model

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

filterOnfocusOut: boolean = true

Whatever to apply filters on losing focus. Leaves an ability to manage filters via gridView JS

filterPosition

filterPosition: string = 'body'

Whether the filters should be displayed in the grid view. Valid values include:

  • header: the filters will be displayed on top of each column's header cell.
  • body: the filters will be displayed right below each column's header cell.
  • footer: the filters will be displayed below each column's footer cell.

filterRowOptions

filterRowOptions: {} = ...

The HTML attributes for the filter row element.

see

[[Html::renderTagAttributes]] for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

filterSelector

filterSelector: string

Additional jQuery selector for selecting filter input fields

filterUrl

filterUrl: string

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.

footerRowOptions

footerRowOptions: {} = {}

The HTML attributes for the table footer row.

see

Html.renderTagAttributes for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

headerRowOptions

headerRowOptions: {} = {}

The HTML attributes for the table header row.

see

Html.renderTagAttributes for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

initialization

initialization: Promise<void>

A Promise which resolves when this Component has been successfully initialized.

layout

layout: string = '{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

options: {} = ...

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".

see

Html.renderTagAttributes for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

pager

pager: LinkPager

The configuration for the pager widget. By default, LinkPager will be used to render the pager. You can use a different widget class by configuring the "class" property. Note that the widget must support the pagination property which will be populated with the [[DataProvider.pagination|pagination]] value of the dataProvider and will overwrite this value.

placeFooterAfterBody

placeFooterAfterBody: boolean = false

Whether to place footer after body in DOM if $showFooter is true

rowOptions

rowOptions: {} = {}

The HTML attributes for the table body rows.

see

Html.renderTagAttributes for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

showFooter

showFooter: boolean = false

Whether to show the footer section of the grid table.

showHeader

showHeader: boolean = true

Whether to show the header section of the grid table.

showOnEmpty

showOnEmpty: boolean = true

Whether to show the grid view if dataProvider returns no data.

sorter

sorter: LinkSorter

The configuration for the sorter widget. By default, LinkSorter will be used to render the sorter. You can use a different widget class by configuring the "class" property. Note that the widget must support the sort property which will be populated with the [[DataProvider.sort|sort]] value of the dataProvider and will overwrite this value.

summary

summary: string

The HTML content to be displayed as the summary of the list view. If you do not want to show the summary, you may set it with an empty string.

The following tokens will be replaced with the corresponding values:

  • {begin}: the starting row number (1-based) currently being displayed
  • {end}: the ending row number (1-based) currently being displayed
  • {count}: the number of rows currently being displayed
  • {totalCount}: the total number of rows available
  • {page}: the page number (1-based) current being displayed
  • {pageCount}: the number of pages available

summaryOptions

summaryOptions: {} = {}

The HTML attributes for the summary of the list view. The "tag" element specifies the tag name of the summary element and defaults to "div".

see

Html.renderTagAttributes for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

tableOptions

tableOptions: {} = ...

The HTML attributes for the grid table element.

see

Html.renderTagAttributes for details on how attributes are being rendered.

Type declaration

  • [key: string]: any

Static autoIdPrefix

autoIdPrefix: string = 'w'

The prefix to the automatically generated widget IDs.

see

getId

Static counter

counter: number = 0

A counter used to generate id for widgets.

internal

Methods

Protected createDataColumn

  • Creates a DataColumn object based on a string in the format of "attribute:format:label".

    throws

    Error if the column specification is invalid

    Parameters

    • text: string

      the column specification string

    Returns DataColumn

    the column instance

Protected getClientOptions

  • getClientOptions(): { filterSelector: string; filterUrl: string }

  • Returns the options for the grid view JS widget.

    Returns { filterSelector: string; filterUrl: string }

    the options

    • filterSelector: string
    • filterUrl: string

getId

  • getId(autogenerate?: boolean): string

Protected guessColumns

  • guessColumns(): void

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

    Returns void

init

  • init(): Promise<void>

initColumns

  • initColumns(): Promise<void>

registerAssets

  • registerAssets(): void

render

  • render(): Promise<string>

  • Renders a widget.

    throws

    InvalidArgumentException if the view file does not exist.

    Returns Promise<string>

    string the rendering result.

renderCaption

  • renderCaption(): string | false

  • Renders the caption element.

    Returns string | false

    the rendered caption element or false if no caption element should be rendered.

renderColumnGroup

  • renderColumnGroup(): Promise<string | false>

  • Renders the column group HTML.

    Returns Promise<string | false>

    the column group HTML or false if no column group should be rendered.

renderEmpty

  • renderEmpty(): string

renderErrors

  • renderErrors(): string

  • Renders validator errors of filter model.

    Returns string

    the rendering result.

renderFilters

  • renderFilters(): Promise<string>

renderItems

  • renderItems(): Promise<string>

renderPager

  • renderPager(): Promise<string>

renderSection

  • renderSection(name: string): Promise<string>

  • Renders a section of the specified name. If the named section is not supported, false will be returned.

    Parameters

    • name: string

      the section name, e.g., {summary}, {items}.

    Returns Promise<string>

    the rendering result of the section, or false if the named section is not supported.

renderSorter

  • renderSorter(): Promise<string>

renderSummary

  • renderSummary(): Promise<string>

renderTableBody

  • renderTableBody(): Promise<string>

  • Renders the table body.

    Returns Promise<string>

    the rendering result.

renderTableFooter

  • renderTableFooter(): Promise<string>

  • Renders the table footer.

    Returns Promise<string>

    the rendering result.

renderTableHeader

  • renderTableHeader(): Promise<string>

  • Renders the table header.

    Returns Promise<string>

    the rendering result.

renderTableRow

  • renderTableRow(model: Model, key: string, index: number): Promise<string>

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

    Parameters

    • model: Model

      the data model to be rendered

    • key: string

      the key associated with the data model

    • index: number

      the zero-based index of the data model among the model array returned by dataProvider.

    Returns Promise<string>

    the rendering result

run

  • run(): Promise<string>

Generated using TypeDoc