Symfony can generate more advanced modules, still based on model class definitions from the schema.yml file, for the back-end of your applications. You can create an entire site administration with only generated administration modules. The examples of this section will describe administration modules added to a backend application. If your project doesn't have a backend application, create its skeleton now by calling the init-app task:

> symfony init-app backend

Administration modules interpret the model by way of a special configuration file called generator.yml, which can be altered to extend all the generated components and the module look and feel. Such modules benefit from the usual module mechanisms described in previous chapters (layout, validation, routing, custom configuration, autoloading, and so on). You can also override the generated action or templates, in order to integrate your own features into the generated administration, but generator.yml should take care of the most common requirements and restrict the use of PHP code only to the very specific.

14.3.1. Initiating an Administration Module

With symfony, you build an administration on a per-module basis. A module is generated based on a Propel object using the propel-init-admin task, which uses syntax similar to that used to initiate a scaffolding:

> symfony propel-init-admin backend article Article

This call is enough to create an article module in the backend application based on the Article class definition, and is accessible by the following:


The look and feel of a generated module, illustrated in Figures 14-5 and 14-6, is sophisticated enough to make it usable out of the box for a commercial application.

list view of the article module in the backend application

Figure 14.5 list view of the article module in the backend application

edit view of the article module in the backend application

Figure 14.6 edit view of the article module in the backend application

The difference between the interface of the scaffolding and the one of the administration may not look significant now, but the configurability of the administration will allow you to enhance the basic layout with many additional features without a line of PHP.

Note Administration modules can only be initiated (not generated).

14.3.2. A Look at the Generated Code

The code of the Article administration module, in the apps/backend/modules/article/ directory, is empty because it is only initiated. The best way to review the generated code of this module is to interact with it using the browser, and then check the contents of the cache/ folder. Listing 14-4 lists the generated actions and the templates found in the cache.

Listing 14-4 - Generated Administration Elements, in cache/backend/ENV/modules/article/

// In actions/actions.class.php
create           // Forwards to edit
delete 	          // Deletes a record
edit             // Displays a form to modify the fields of a record
                 // And handles the form submission
index            // Forwards to list
list             // Displays the list of all the records of the table
save             // Forwards to edit

// In templates/

This shows that a generated administration module is composed mainly of two views, edit and list. If you have a look at the code, you will find it to be very modular, readable, and extensible.

14.3.3. Introducing the generator.yml Configuration File

The main difference between scaffoldings and administrations (apart from the fact that administration-generated modules don't have a show action) is that an administration relies on parameters found in the generator.yml YAML configuration file. To see the default configuration of a newly created administration module, open the generator.yml file, located in the backend/modules/article/config/generator.yml directory and reproduced in Listing 14-5.

Listing 14-5 - Default Generator Configuration, in backend/modules/article/config/generator.yml

  class:              sfPropelAdminGenerator
    model_class:      Article
    theme:            default

This configuration is enough to generate the basic administration. Any customization is added under the param key, after the theme line (which means that all lines added at the bottom of the generator.yml file must at least start with four blank spaces to be properly indented). Listing 14-6 shows a typical customized generator.yml.

Listing 14-6 - Typical Complete Generator Configuration

  class:              sfPropelAdminGenerator
    model_class:      Article
    theme:            default

      author_id:      { name: Article author }

      title:          List of all articles
      display:        [title, author_id, category_id]
        published_on: { params: date_format='dd/MM/yy' }
      layout:         stacked
      params:         |
        %%is_published%%<strong>%%=title%%</strong><br /><em>by %%author%%
        in %%category%% (%%published_on%%)</em><p>%%content_summary%%</p>
      filters:        [title, category_id, author_id, is_published]
      max_per_page:   2

      title:          Editing article "%%title%%"
        "Post":       [title, category_id, content]
        "Workflow":   [author_id, is_published, created_on]
        category_id:  { params: disabled=true }
        is_published: { type: plain}
        created_on:   { type: plain, params: date_format='dd/MM/yy' }
        author_id:    { params: size=5 include_custom=>> Choose an author << }
        published_on: { credentials:  }
        content:      { params: rich=true tinymce_options=height:150 }

The following sections explain in detail all the parameters that can be used in this configuration file.