14.3. Administration

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:

http://localhost/backend.php/article

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.

Figure 14.5 list 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.

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/
_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
editSuccess.php
listSuccess.php

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

generator:
  class:              sfPropelAdminGenerator
  param:
    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

generator:
  class:              sfPropelAdminGenerator
  param:
    model_class:      Article
    theme:            default

    fields:
      author_id:      { name: Article author }

    list:
      title:          List of all articles
      display:        [title, author_id, category_id]
      fields:
        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

    edit:
      title:          Editing article "%%title%%"
      display:
        "Post":       [title, category_id, content]
        "Workflow":   [author_id, is_published, created_on]
      fields:
        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.