14.4. 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.4.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

class: sfPropelGenerator
param:
  model_class:           BlogArticle
  theme:                 admin
  non_verbose_templates: true
  with_show:             false
  singular:              ~
  plural:                ~
  route_prefix:          article
  with_propel_route:     1
  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.4.2. Creating a Custom Header and Footer

The list, new, 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
_form_header.php
_form_footer.php

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

Listing 14-39 - Example edit Header Partial, in modules/article/templates/_form_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.

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

14.4.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 sub-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_lib_dir/plugins/sfPropelPlugin/data/generator/sfPropelModule/admin/.

The theme files must be located in a project tree structure, in a data/generator/sfPropelModule/[theme_name]/ directory, and you can bootstrap a new theme by copying the files you want to override from the default theme (located in $sf_symfony_lib_dir/plugins/sfPropelPlugin/data/generator/sfPropelModule/admin/ directory):

// Partials, in [theme_name]/template/templates/
_assets.php
_filters.php
_filters_field.php
_flashes.php
_form.php
_form_actions.php
_form_field.php
_form_fieldset.php
_form_footer.php
_form_header.php
_list.php
_list_actions.php
_list_batch_actions.php
_list_field_boolean.php
_list_footer.php
_list_header.php
_list_td_actions.php
_list_td_batch_actions.php
_list_td_stacked.php
_list_td_tabular.php
_list_th_stacked.php
_list_th_tabular.php
_pagination.php
editSuccess.php
indexSuccess.php
newSuccess.php

// Actions, in [theme_name]/parts
actionsConfiguration.php
batchAction.php
configuration.php
createAction.php
deleteAction.php
editAction.php
fieldsConfiguration.php
filterAction.php
filtersAction.php
filtersConfiguration.php
indexAction.php
newAction.php
paginationAction.php
paginationConfiguration.php
processFormAction.php
sortingAction.php
sortingConfiguration.php
updateAction.php

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

<h1>[?php echo <?php echo $this->getI18NString('edit.title') ?> ?]</h1>

[?php include_partial('<?php echo $this->getModuleName() ?>/flashes') ?]

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:

<h1><?php echo __('List of all Articles') ?></h1>

<?php include_partial('article/flashes') ?>

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

-

$manager = new sfGeneratorManager();
$data = $manager->generate('sfPropelGenerator', $parameters);