Custom Views in Symfony 1.0

After seeing this feature request for symfony 1.3 I decided to write a tutorial explaining how to use custom views with symfony 1.0. Yes symfony 1.0 has this feature, a little bit hide inside, but is there since the ol’ good days.

So, there are three ways to have a custom View class for your actions. To show how this work, we will need a project with a module called example. 

First example:

After you have your module ready add an action called FirstExample which will have this code: 

public function executeFirstExample() {}

Then on the example module add a folder called views. Inside it we will add our custom view class. The name will be firstExampleSuccessView. Create a firstExampleSuccessView.class.php file with the following code inside:

class firstExampleSuccessView extends sfPHPView

{

  

}

As you can see, it extends the sfPHPView provided by symfony,  to get all the functionality inside. Please note that custom views in symfony need to extend sfView, which is the parent class of sfPHPView. 

At this point I’m going to tell you that we can customize a lot of features of the symfony views. For the tutorial I will just show you how to have new shortcut variables inside the templates like the $sf_request or $sf_user already provided by symfony. Feel free to comment about your experience extending the sfView.

To add a new shortcut to the template we need to extend the following method:

sfPHPView::getGlobalVars(). We will add a new shortcut smartly called my_view_data. with a dummy array inside. This will be our code:

protected function getGlobalVars()

{

  $context = $this->getContext();

   $shortcuts = array(

     'sf_context' => $context,

     'sf_params'  => $context->getRequest()->

getParameterHolder(),

     'sf_request' => $context->getRequest(),

     'sf_user'    => $context->getUser(),

     'sf_view'    => $this,

     'my_view_data' => array('foo' => 'this data came from firstExampleSuccessView')

  );

 if (sfConfig::get('sf_use_flash'))

 {

   $sf_flash = new sfParameterHolder();

   $sf_flash->add($context->getUser()->

  getAttributeHolder()->

  getAll('symfony/flash'));

     $shortcuts['sf_flash'] = $sf_flash;

   }

    return $shortcuts;

}

As you can see there is a new my_view_data key with a one element array.

To see this in action we add in the example/templates folder a file called firstExampleSuccess.php with the following content:

<h1>First Example View:</h1>

<?php var_dump($my_view_data); ?>

Clear the cache and point your browser to http://yourapp.com/example/firstExample

There you will see the output of our new shortcut.

As long as our action returns sfView::SUCCESS it will use our new custom view class. Who said that symfony had no custom views? :-)

Remember to follow the naming convention of: <actionName><viewName>View. In our example we had firstExampleSuccessView. firstExample is the action, Success is on of the possible values that our actions can return, View is the default suffix. 

Second Example

In this case we will create a class called secondExampleView inside a file secondExampleView.class.php located in the lib folder of our application. The contents of this class will be almost the same that four our first view.  We will change the class name to secondExampleView and the my_view_data entry will be declared like this:

'my_view_data' => array('foo' => 'this data came from secondExampleView')

Then we create a new action for our module with the following code:

public function executeSecondExample(){}

Then we add the template secondExampleSuccess.php with this code inside:

<h1>Second Example View:</h1>

<?php var_dump($my_view_data); ?>

Now, how do we use our new view with this action? In case we don’t have one, we add a module.yml file in the config folder of the example module. There we add the following content:

all:

  view_class: secondExample

This will tell symfony to use our custom view class for this module. As you can see here,  we can specify different views per environment :-) Yes,  symfony is configurable :-) 

If we point our browsers to the secondExample action we will see the contests of our shortcut.

Third Example:

For this example we will create a class called thirdExampleView inside the lib folder of our application. As we did with our secondExampleView we will have the same code, except for the class name and the my_view_data shortcut that will have inside the following: 

array('foo' => 'this data came from thirdExampleView')

We add a template called thirdExampleSuccess.php with this content:

<h1>First Example View:</h1>

<?php var_dump($my_view_data); ?>

and we create an action like this:

public function executeThirdExample()

{

    $module = $this->getRequestParameter('module');

    $action = $this->getRequestParameter('action');

    $this->getRequest()->setAttribute($module.'_'.$action.'_view_name', 'thirdExample', 'symfony/action/view');

}

What we do here is setting in the 'symfony/action/view' namespace of the sfRequest attribute holder a value with our view class without the View suffix. The key of the attribute should be composed by <module_name>_<action_name>_view_name  as you can see from the code above.

Then we can point our browsers to the thirdExample action to see the results.

With this three ways we can set up your own views and customize the rendering process of our applications. 

As final note I want to add how symfony knows which view class to pick.

• It checks inside the module/views folder to see if it can find our custom class as explained on the first example.
  
• If there is no user class there, it will check if we have set up one in the sfRequest as explained on example three.
  
• Then it will try to see if we defined a view in the module.yml file.
  
• As last resort it will load the default sfPHPView class.
  

Thanks for reading this far and I hope this will help you on your projects.