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.
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/ _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.