Content decorators are a less heralded but interesting feature of the Yii framework. Content decorators allow you to hijack the view rendering process and add some additional stuff around the view file being rendered. In this excerpt from Chapter 7, “Working with Controllers,” of “The Yii Book”, I’ll explain what content decorators are and how you use them. (This does assume you have some familiarity with Yii and how it renders the complete layout.)
Continue Reading...Archives For view
In the MVC architecture, the Controller reacts to a user request. In doing so, the Controller often loads an instance of a particular Model and then renders a specific View. “Rendering” just means compiling all the pieces together, including static text (HTML and such) and the output from executed PHP code. For example, when a user goes to a page for updating a record, the Controller loads the associated record, and then renders the “update” View, which will display the pre-populated form:
public function actionUpdate($id) {
$data=$this->loadModel($id);
$this->render('update',array(
'model'=>$data
));
}
Note: That method would also have code in it for handling the submission of the update form, but I’m trying not to complicate the discussion.
As you can see in that code, the render() method, defined in the CController class, is how a View file is chosen for rendering. The first argument to the method is the View file to be rendered, without its .php extension. The render() method will render the View file within the appropriate layout file. In other words, the View file will be rendered with its context. The above code renders update.php, for the associated Controller, wrapped within the views/layouts/main.php layout file (the default).
The second argument to render() is an array of data that can be sent to the View file. In the above code, the Model instance is being passed along. In update.php, references to the $model variable will refer to the loaded data (note that the View gets its variable names from the indexes used in the array).
The render() method takes an optional third argument, which is a Boolean indicating if the rendered result should be returned to the Controller instead of sent to the Web browser. This would be useful if you wanted to render the page and then send the output in an email or write it to a text file on the server (to act as a cached version).
Sometimes you’ll want to render a View file without incorporating the layout. To do that, invoke renderPartial(). For example, both the update.php and create.php View files, auto-generated by Yii, just provide a context, and then include the form file:
<?php echo $this->renderPartial('_form', array('model'=>$model)); ?>
Since the initial View file will have already be rendered within the layout context, the layout shouldn’t be rendered again. The renderPartial() method will render just the named View file. Its second argument, as with render(), can be used to pass data to the View file. In the above, the Model instance is passed along.
Tip: The renderPartial() method is also used for Ajax calls, where the layout isn’t appropriate.
As mentioned already, the file being rendered comes from the directory associated with the current Controller. For example, when updating an Employee record, the URL is something like www.example.com/index.php/employee/update/id/23. This calls the actionUpdate() method of the EmployeeController class (whose code is partially shown above). That method renders the “update” View, which is to say protected/views/employee/update.php. But there are rare cases where you’ll need to render View files from other subdirectories. For example, you may want to include a search form on a page, with that form found within another View directory. To change the reference point, start the View reference with a double slash, which means to start in the views folder. Then indicate the subdirectory and file, still omitting the extension:
<?php echo $this->renderPartial('//search/_form'); ?>
And that’s all there is to it!
View rendering is one of the most important concepts to grasp in an MVC design. Fortunately, it’s not that hard to follow in Yii. Just remember that if you want your layout file, use render(). If not, use renderPartial(). If you need to pass data to the View file, use the second argument to send along an array, whose indexes will become the names of the variables within the View. Finally, if you need to change the include path, begin with a double slash.
