Understanding Our Auto-Generated Code: Views
In this post, we discuss the views auto-generated by Gii.
By default, the views are generated in a folder under the views folder under protected, i.e. protected/views. The name of the folder generated is the same as the table name. For example, if the name of the table is users, like in our case, then the folder will be called
The admin view is rendered from the render method. The render method accepts 3 parameters:
string $view- The name of the view to be rendered.
array $data- An array having the parameters to be sent to the view. (Optional)
boolean $return- whether the rendering result should be returned instead of being displayed. (Optional)
In the code snippet above, we’re rendering the admin view. And the data being sent is
$model. The key used in the array is what will be used in the view. So in the case above, we’ll refer to the variable using the variable
$model. If we used ‘userModel’ as the key in the array, we’d use
$userModel in the view.
Partial Views are rendered using the
renderPartial method. They are usually used within main views.
The admin view displays your data in a
CGridView. It has the following items:
- Breadcrumbs - This refers to the links that appear on the top of the users admin page
- Menu - This refers to the links that appear on the side of the page. Menu contents are defined in an array having the following keys:
string 'label'- defines the text that will be displayed to the user, e.g. ‘Manage Users’
array 'url'- defines the URL for the link (i.e. the HTML
hrefproperty). It’s usually defined in the format
users/create. A custom URL can also be defined
array 'linkOptions'- defines any additional properties that should be added to the HTML Link Tag. For example, if we want the link to be opened in a new tab, we can add the key => value pair:
'target' => '_BLANK', so that the property
targetwill be defined for the link. You can read more about Yii CMenu .
- A button to toggle the search form, and a partial render for the search form
- The CGridView widget.
We’ll discuss the partial render and the CGridView in more detail.
A CGridView is a Yii widget used to display data in a tabular form. Widgets in Yii are fetched using the
The first parameter to the method is the alias of the widget; second is an array having parameters used by the widget. CGridView uses the following parameters as keys:
id, dataProvider, filter, columns. More parameters are explained here.
Columns to be displayed are defined in the
columns parameter. The data columns can be defined as:
- a string representing the column name in the database, e.g.
- an array representing CDataColumn properties, i.e.
Normally, we don’t want to display raw IDs to the users in our grid view, especially for cases where a value in a column is a foreign key of another table. For example, in our system, all tables have the column
status. The value of the
status column references a value in the
entityStates table. So instead of displaying
1 in that field, we can display the corresponding
To do this, we need to ensure that the relation to
EntityStates is defined in the Users model. First, use Gii to generate a model for the
entityStates table. Then modify the
relations function in the Users model to include a relation to
EntityStates. The updated code should be as below:
I normally append an underscore for
BELONGS_TO relations to differentiate them from the
HAS_MANY relations, in this case,
Then update the users admin view file; add the string:
If you refresh the users admin page view, you should see the entity state name in the status field.
Finally, we can change what is displayed as the header of the column having entity state Name to Status. In the Users model, update the
attributeLabels() function to include the label
status_.entityStateName. It’s value should be Status. The header for that column is now Status.
The last item of the columns array is
CButtonColumn. This defines the buttons that appear on the last column of the table. Additional properties can be defined to format how items are displayed on that column. You can read up on additional CButtonColumn properties here.
Also defined in the admin view is a partial render of the search form.
_search.php is one of the partial views that was auto-generated in the users view folder. The
renderPartial method takes the same parameters as the render method. In this case, the name of the partial view is
_search, and the array contains the parameter that will be passed, i.e.
model. If you go ahead and take a peek at the code in the
_search.php file, you’ll notice that it is basically a form that displays some search fields. We’ll discuss the form fields when going through the _form partial view.
That’s it for this post. In the next one, we’ll discuss the other views.
Your questions, comments and suggestions are always welcome below.
NB: I’ve uploaded the code for this project on GitHub. Check it out (or clone :) here