14.5. Modifying the Presentation of Generated Modules

You can modify the presentation of the generated modules so that it matches any existing graphical charter, not only by applying your own style sheet, but also by overriding the default templates.

14.5.1. Using a Custom Style Sheet

Since the generated HTML is structured content, you can do pretty much anything you like with the presentation.

You can define an alternative CSS to be used for an administration module instead of a default one by adding a css parameter to the generator configuration, as in Listing 14-38.

Listing 14-38 - Using a Custom Style Sheet Instead of the Default One

generator:
  class:              sfPropelAdminGenerator
  param:
    model_class:      Comment
    theme:            default
    css:              mystylesheet

Alternatively, you can also use the mechanisms provided by the module view.yml to override the styles on a per-view basis.

14.5.2. Creating a Custom Header and Footer

The list and edit views systematically include a header and footer partial. There is no such partial by default in the templates/ directory of an administration module, but you just need to add one with one of the following names to have it included automatically:

_list_header.php
_list_footer.php
_edit_header.php
_edit_footer.php

For instance, if you want to add a custom header to the article/edit view, create a file called _edit_header.php as in Listing 14-39. It will work with no further configuration.

Listing 14-39 - Example edit Header Partial, in modules/articles/templates/_edit_header.php

<?php if ($article->getNbComments() > 0): ?>
  <h2>This article has <?php echo $article->getNbComments() ?> comments.</h2>
<?php endif; ?>

Notice that an edit partial always has access to the current object through a variable named after the class, and that a list partial always has access to the current pager through the $pager variable.

This article has <?php echo link_to($article->getNbComments().' comments', 'comment/list', array('query_string' => 'filter=filter&filters%5Barticle_id%5D='.$article->getId())) ?> comments.

'filter=filter&filters[article_id]='.$article->getId()

14.5.3. Customizing the Theme

There are other partials inherited from the framework that can be overridden in the module templates/ folder to match your custom requirements.

The generator templates are cut into small parts that can be overridden independently, and the actions can also be changed one by one.

However, if you want to override those for several modules in the same way, you should probably create a reusable theme. A theme is a complete set of templates and actions that can be used by an administration module if specified in the theme value at the beginning of generator.yml. With the default theme, symfony uses the files defined in $sf_symfony_data_dir/generator/sfPropelAdmin/default/.

The theme files must be located in a project tree structure, in a data/generator/sfPropelAdmin/[theme_name]/template/ directory, and you can bootstrap a new theme by copying the files from the default theme (located in $sf_symfony_data_dir/generator/sfPropelAdmin/default/template/ directory). This way, you are sure that all the files required for a theme will be present in your custom theme:

// Partials, in [theme_name]/template/templates/
_edit_actions.php
_edit_footer.php
_edit_form.php
_edit_header.php
_edit_messages.php
_filters.php
_list.php
_list_actions.php
_list_footer.php
_list_header.php
_list_messages.php
_list_td_actions.php
_list_td_stacked.php
_list_td_tabular.php
_list_th_stacked.php
_list_th_tabular.php

// Actions, in [theme_name]/template/actions/actions.class.php
processFilters()     // Process the request filters
addFiltersCriteria() // Adds a filter to the Criteria object
processSort()
addSortCriteria()

Be aware that the template files are actually templates of templates, that is, PHP files that will be parsed by a special utility to generate templates based on generator settings (this is called the compilation phase). The generated templates must still contain PHP code to be executed during actual browsing, so the templates of templates use an alternative syntax to keep PHP code unexecuted for the first pass. Listing 14-40 shows an extract of a default template of template.

Listing 14-40 - Syntax of Templates of Templates

<?php foreach ($this->getPrimaryKey() as $pk): ?>
[?php echo object_input_hidden_tag($<?php echo $this->getSingularName() ?>,'get<?php echo $pk->getPhpName() ?>') ?]
<?php endforeach; ?>

In this listing, the PHP code introduced by <? is executed immediately (at compilation), the one introduced by [? is only executed at execution, but the templating engine finally transforms the [? tags into <? tags so that the resulting template looks like this:

<?php echo object_input_hidden_tag($article, 'getId') ?>

Dealing with templates of templates is tricky, so the best advice if you want to create your own theme is to start from the default theme, modify it step by step, and test it extensively.

$generator_manager = new sfGeneratorManager();
 $data = $generator_manager->generate('sfPropelAdminGenerator', $parameters);