12. GridView

The basic default layout for displaying tabular data in Yii is GridView. It is very powerful, very easy and will be the default layout when you view the index page of a controller that has been generated by Gii for a model. All the table data associated with the model will be displayed in a nice table complete with pagination.

The default pagination is 20 records per page. This can easily be changed to anything you like.

I have loaded the customers table with test data. On my installation, navigating to the customers page (http://yii-basic.loc/customers in my case, yii-basic.loc would be replaced by your domain) produces the following output:

This entire grid is created by default when generating the view code with Gii. You will notice that not all the fields are represented. You can easily enable or disable which fields are shown.

The far left column is simply the grid row count. I generally remove this column.

On the far right is the action column. By default, you will see three icons representing three actions. Clicking on the open eye will display all the data for that one record. Clicking the pencil will allow you to edit the record. Clicking the trashcan will delete the record.

These actions are fully customizable. You can remove any or add new actions as needed.

Right above the grid you will see the row count and what rows are being displayed. In this grid I have changed the pagination to 10 so it is showing rows 1 through 10 of 122 items.

Beneath the grid you will see the pagination controls. Clicking on a number takes you to that page. 10 pages are listed by default.

12.1 Sorting

You will notice that the column titles are clickable. Clicking on the title will sort the table by that column. Here is what it looks like when clicking Company Name:

12.2 Filtering

At the top of each column is a text input field. This allows you to filter the contents of that column.

Here is the result of entering the letters 'ltd' in the Company Name input field and clicking 'enter':

12.3 The Grid Code

Here is the code contained in the view file, /views/customers/index.php:

<?php

use yii\helpers\Html;
use yii\grid\GridView;

$this->title = 'Customers';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="customers-index">

    <h1><?= Html::encode($this->title) ?></h1>

    <p>
        <?= Html::a('Create Customers', ['create'], ['class' => 'btn btn-success']) ?>
    </p>

    <?= GridView::widget([
        'dataProvider' => $dataProvider,
        'filterModel' => $searchModel,
        'columns' => [
            ['class' => 'yii\grid\SerialColumn'],

            'customerNumber',
            'companyName',
            'contactLastName',
            'contactFirstName',
            'phone',

            ['class' => 'yii\grid\ActionColumn'],
        ],
    ]); ?>

</div>

GridView::widget is the function that generates the actual grid. It consists of the following parts:

'dataProvider' points to the data used to populate the grid.
'filterModel' enables the content filtering.
'columns' specifies what columns will be included in the table.

And remember to include the widget with use yii\grid\GridView at the top of the file.

12.4 Columns

The first column is defined by ['class' => 'yii\grid\SerialColumn']. This simply displays the row number and can generally be removed.

The next five columns match field names in the customers table. To show additional data fields, simply add the field name to the array. If you do not want to show a specific data field, remove the field name from the array.

The last column, the action column, is defined by ['class' => 'yii\grid\ActionColumn']. This column definition can be expanded and customized as needed. As shown, it will display the default three icons for the view, edit and delete actions.

12.4.1 Data Formats

Each cell in the rendered grid displays the data for that field according to a specific format. The possible formats are as follows:

boolean	Formats the value as a boolean.
currency	Formats the value as a currency number.
date	Formats the value as a date.
datetime	Formats the value as a datetime.
decimal	Formats the value as a decimal number.
duration	Represents the value as duration in human readable format.
email	Formats the value as a mailto link.
html	Formats the value as HTML text.
image	Formats the value as an image tag.
integer	Formats the value as an integer number by removing any decimal digits without rounding.
ntext	Formats the value as an HTML-encoded plain text with newlines converted into breaks.
ordinal	Formats the value as a ordinal value of a number.
paragraphs	Formats the value as HTML-encoded text paragraphs.
percent	Formats the value as a percent number with "%" sign.
raw	Formats the value as is without any formatting.
relativeTime	Formats the value as the time interval between a date and now in human readable form.
scientific	Formats the value as a scientific number.
shortSize	Formats the value in bytes as a size in human readable form for example `12 KB`.
size	Formats the value in bytes as a size in human readable form, for example `12 kilobytes`.
spellout	Formats the value as a number spelled out.
text	Formats the value as an HTML-encoded plain text.
time	Formats the value as a time.
timestamp	Formats a date, time or datetime in a float number as UNIX timestamp (seconds since 01-01-1970).
url	Formats the value as a hyperlink.

The default format, if none is specified, is 'text'.

12.4.1.1 Setting the Format

There are two ways to set the data format for a column: The shorthand way and the longhand way.

12.4.1.1.1 Shorthand to Set Format

The shorthand method to set a column format is using this construct: fieldName:Format

Thus, in the example above, if we wanted to set the format of the companyName field to 'ntext', where would change the attribute in the array to: 'companyName:ntext'

12.4.1.1.2 Longhand to Set Format

If you wanted to set companyName field to data format 'ntext', you could also replace companyName with the following code:

[
	'attribute' => ' companyName ',
	'format' => 'ntext',
],

12.4.2 Column Labels

How are the column labels in the header set?

There are four options.

12.4.2.1 Yii Automatically Creates Labels

By default, if you do not set a label for a field, Yii generates a label for you based on the field name.

Camel-case variable names are turned into multiple words with the first letter in each word in upper case. For example, username becomes Username, and firstName becomes First Name.

12.4.2.2 attributeLabels Method

When creating the model for a table, by default a function was included when generating the model through Gii. This function is attributeLabels(). All that this function does is map field names to labels as key/value pairs and returns the array.

Here is the function with the array for reference. This function goes in the customers.php model file.

public function attributeLabels()
 {
     return [
         'customerNumber' => 'Customer Number',
         'companyName' => 'Company Name',
         'contactLastName' => 'Contact Last Name',
         'contactFirstName' => 'Contact First Name',
         'phone' => 'Phone',
     ];

When GridView generates the grid, it processes the attributeLabels() function automatically and gets the labels for each field, which are used to populate the column headers.

12.4.2.3 Label Shorthand

A third way to set the column label is to use a shorthand when setting the field name. The format is as follows: fieldName:Format:Label

If setting the companyName field to format 'ntext' and specifying the column header label to be Company Name, the shorthand code would look like this:

'companyName:ntext:Company Name'

12.4.2.4 Label Longhand

The final way to specify a column label is to explicitly spell it out as follows:

[
	'attribute' => ' companyName ',
	'format' => 'ntext',
	'label' => 'Company Name',
],

12.4.3 Editing Action Column

The action column works through a templating system. The following code would produce the same output as the default:

[
    'class' => 'yii\grid\ActionColumn',
    'template' => '{view} {update} {delete}',
]

As you can see, the three default actions are listed for the template key. If you wanted to remove the delete action, you would simply change it the code as follows:

[
    'class' => 'yii\grid\ActionColumn',
    'template' => '{view} {update}',
]

There is a lot more customization you can do for the action column, including changing the icons from default, changing the action taken when clicking on an icon and adding entirely new actions with their own icons.

The gridview widget is entirely customizable, however that is beyond the scope of a quick start guide. This is enough to get you started.

12.5 The Data Provider

The big question is, how does the data get from the database into the grid? Let's answer that now.

It all comes down to the dataProvider.

12.5.1 Data Provider and the Controller

Let's first look at the controller as that is what is directing the traffic and connecting the grid to the data model.

The action in this case is index. As you will recall, index is the action called if no specific action is specified in the url. Here is the index action that ties the data to the grid:

public function actionIndex()
{
    $searchModel = new CustomersSearch();
    $dataProvider = $searchModel->search(Yii::$app->request->queryParams);

    return $this->render('index', [
        'searchModel' => $searchModel,
        'dataProvider' => $dataProvider,
    ]);
}

This controller action instantiates a new CustomersSearch object. Remember when we generated the CRUD code with Gii? We generated a second model related to the Customers model: app\models\CustomersSearch

This model does what it says, you pass it search parameters and it filters the data set returned based on those parameters (basically using where clauses in the SQL).

Yii::$app->request->queryParams

This property contains the $_GET parameters and can be accessed as needed in controllers. In this case, the parameters passed are the filter and sort requests initiated from the grid.

On the initial load of the grid page, there are no query parameters so we are basically assigning $searchModel->search() to $dataProvider variable.

We are then passing the searchModel and dataProvider variables to the render function, which passes it to the view for access by the GridView Widget.

12.5.2 The Search Model

Let's take a look at the actual search model to see what is happening. Here is the search function in CustomersSearch.php under models:

public function search($params)
{
    $query = Customers::find();

    $dataProvider = new ActiveDataProvider([
        'query' => $query,
        'pagination' => [
            'pageSize' => 10,
        ],
    ]);

    $this->load($params);

    if (!$this->validate()) {
        // uncomment the following line if you do not want to return any records when validation fails
        // $query->where('0=1');
        return $dataProvider;
    }

    $query->andFilterWhere([
        'customerNumber' => $this->customerNumber,
    ]);

    $query->andFilterWhere(['like', 'companyName', $this->companyName])
        ->andFilterWhere(['like', 'contactLastName', $this->contactLastName])
        ->andFilterWhere(['like', 'contactFirstName', $this->contactFirstName])
        ->andFilterWhere(['like', 'phone', $this->phone]);

    return $dataProvider;
}

The primary method doing the work is ActiveDataProvider. We are passing the static method of find() in the Customers model, which is an instance of Active Record for that model. This is assigned to the 'query' parameter.

You will notice we are also setting the page size to 10 records per page for pagination. If this is left out, the default will be 20 records per page.

andFilterWhere

This method adds an additional where clause using AND. However, the Filter part specifics that if the operand is empty, it is ignored. If you would rather add an OR where clause, you would use orFilterWhere().

The auto-generated where statements use equality for integer field types and 'like' for string. This allows you to filter the grid on partial strings.

The load() function takes the query parameters and makes them available to the Active Record methods for that model.

You will notice that the search model does have its own validation rules. Thus, the validate method can be called to validate any query parameters passed in.

	Preface
1.	SCOPE
2.	YII APPLICATION ARCHITECTURE (MVC)
2.1	Model
2.1.1	CRUD
2.2	View
2.3	Controller
3.	INSTALLATION
3.1	Composer
3.2	Advanced Vs. Basic
3.2.1	Advanced Template Features
3.2.1.1	Backend and Frontend
3.2.1.2	Environments
3.2.1.3	Migrations
3.3	Installing via Composer
3.3.1	Install Basic Template
3.3.2	Install Advanced Template
3.4	Configuration Files
3.4.1	Basic Template
3.4.2	Advanced Template
3.4.3	Database Connection
3.5	Initialize Database
3.6	Set Document Root in Server Config
3.6.1	Basic Template Document Root
3.6.2	Advanced Template Document Root
3.6.3	Apache Config Example
3.7	Default Install
3.7.1	Basic Template
3.7.2	Advanced Template Frontend
3.7.3	The Debug Bar
4.	DIRECTORY STRUCTURE
4.1	Basic Template Directory Structure
4.2	Advanced Template Directory Structure
5.	URL ROUTING
5.1	Default Controller and Action
5.2	Pretty Urls
6.	CALLING VIEWS
6.1	Anatomy of a View
6.2	View Layouts
6.2.1	Flash Messages
7.	NAMESPACING
7.1	The Use Statement
8.	ALIASES
8.1	Commonly Used Predefined Aliases
8.2	Defining Aliases
8.3	Resolving Aliases
8.4	Using Aliases
9.	HELLO WORLD
9.1	The Controller File
9.2	The View File
9.3	The Output
9.4	Hello World Using Advanced Template
10.	MODELS
10.1	Gii Code Generation Tool
10.1.1	Generate Model Uisng Gii
10.1.2	Generate CRUD Using Gii
10.2	Model Rules
10.2.1	Common Model Rules Explained
10.2.2	Generated Rules
11.	CONTROLLER CRUD
11.1	CRUD Basics
11.1.1	CRUD Create
11.1.2	CRUD Read
11.1.3	CRUD Update
11.1.4	CRUD Delete
12.	GRIDVIEW
12.1	Sorting
12.2	Filtering
12.3	The Grid Code
12.4	Columns
12.4.1	Data Formats
12.4.1.1	Setting the Format
12.4.2	Column Labels
12.4.2.1	Yii Automatically Creates Labels
12.4.2.2	attributeLabels Method
12.4.2.3	Label Shorthand
12.4.2.4	Label Longhand
12.4.3	Editing Action Column
12.5	The Data Provider
12.5.1	Data Provider and the Controller
12.5.2	The Search Model
13.	DETAILVIEW
13.1	The DetailView Code
13.2	Specify Label and Data Format
14.	ACTIVE FORM
14.1	The Active Form Code
14.2	The Resulting HTML From Code
14.3	Initialize Active Form
14.3.1	Setting the Form Action Value
14.3.2	Setting the Form ID
14.3.3	Setting the Form Submission Method
14.3.4	Other Form Tag Attributes
14.4	Active Form Fields
14.4.1	Text Input Field
14.4.1.1	Specify Text Input Field Attributes
14.4.2	Text Area
14.4.3	Dropdown List
14.4.3.1	Multi Select List Box
14.4.3.2	Option Grouping
14.4.4	ListBox
14.4.5	Checkbox
14.4.6	Radio Buttons
14.4.7	Checkbox List
14.4.8	Password Field
14.4.9	Hidden Field
14.4.10	Submit Button
14.4.11	HTML 5 Fields
14.4.11.1	Email Input Field
14.4.11.2	Number Input Field
14.4.11.3	Range
14.4.11.4	Min Max
14.5	Extra Controls
14.5.1	Form Field Label
14.5.2	Form Field Hint
14.5.3	isNewRecord
14.6	Form Validation Feedback
15.	RECORD CREATE AND UPDATE
15.1	Controller Namespace
15.2	Controller Actions
15.2.1	Create New Record
15.2.2	Updateing Exisitng Record
15.3	Load Submitted Data
15.3.1	Post Data
15.3.1.1	Anatomy of Post Data
15.3.2	Load Data Into Model
15.4	Validate Data
15.5	Saving the Submitted Data
16.	USER AUTHENTICATION
16.1	Restricting Access to Actions
16.1.1	The Only Attribute
16.1.2	The Except Attribute
16.2	User Identity
16.3	isGuest
16.4	RBAC
16.4.1	The Basics
16.4.2	Specify Manager Type
16.4.3	Create RBAC Directory
16.4.4	Configure authManager
16.4.5	Create Items File
16.4.5.1	The Migration File
16.4.6	Assignment File
16.4.6.1	Adding Users to Assignment
16.4.7	Setting the Access Control
17.	CONCLUSION

Contents