====== Symfony YAML Configuration Reference ====== =====The generator.yml configuration file===== In this article we assume that you are familiar with [[http://www.symfony-project.org/reference/1_4/en/02-YAML|The YAML Format]] and [[http://www.symfony-project.org/reference/1_4/en/03-Configuration-Files-Principles|Configuration File Principles]]. The admin generator of symfony allows the creation of a backend interface for your model classes. It works whether you use Propel or Doctrine as your ORM. Admin generator modules are created by the //propel:generate-admin// or //doctrine:generate-admin// tasks: php symfony doctrine:generate-admin backend Project --module=project php symfony propel:generate-admin backend Project --module=project The above command creates a //project// admin generator module for the //Project// model class. And the configuration of such a module can be done in the //apps/backend/modules/project/config/generator.yml// file. generator: class: param: model_class: model_class_name theme: theme_name non_verbose_templates: with_show: singular: ~ plural: ~ with_doctrine_route: route_prefix: route_prefix_name actions_base_class: class_name css: config: actions: action_name: label: action_label action: action_name credentials: action_credentials params: html_attribute: value absolute: query_string: query_string_value anchor: anchor_value confirm: confirmation_message popup: post: method: fields: field_name: label: field_label help: help_text attributes: { attribute1: value1, attribute2: value2, ... } credentials: field_credentials renderer: renderer_name renderer_arguments: [argument1, argument2, ...] type: type_of_column date_format: format_string is_link: is_real: is_partial: is_component: list: title: view_title display: [=fieldname1, fieldname2, ...] hide: [fieldname1, fieldname2, ...] layout: params: params_string sort: [fieldname, ] max_per_page: pager_class: class_name fields: field_list batch_actions: action_list object_actions: action_list actions: action_list table_method: method_name peer_method: method_name table_count_method: method_name peer_count_method: method_name filter: display: [fieldname1, fieldname2, ...] class: fields: field_list form: display: [fieldname1, fieldname2, ...] class: class_name fields: field_list actions: action_list edit: display: [fieldname1, fieldname2, ...] title: view_title fields: field_list actions: action_list new: display: [fieldname1, fieldname2, ...] title: view_title fields: field_list actions: action_list =====Generator configuration options===== ====generator==== The //generator.yml// file must start with an //generator// key under which the whole configuration is done. ====generator > class==== Specifies generator class name. Default: //sfDoctrineGenerator (for Doctrine), sfPropelGenerator (for Propel)// ====generator > param==== Specifies an array of configuration options for the generated module. ====generator > param > model_class==== Defines the model class bound to generated module. ====generator > param > theme==== Defines the default theme to use. Default: //admin// ====generator > param > non_verbose_templates==== It seems, that this option do not have any effect whether it is set to //true// or //false//; Possible values: //// Default: //true// ====generator > param > with_show==== Defines whether the generated action class implements a show action. In the standard Symfony distribution this option is not implemented. The //with_show// option is implemented only by the third party admin generator themes (eg. ahAdminGeneratorThemesPlugin). Possible values: //// Default: //false// ====generator > param > singular==== ====generator > param > plural==== ====generator > param > with_doctrine_route==== Possible values: //// Default: //true// ====generator > param > route_prefix==== Defines a route name to use for links in generated templates. This route must be added to //routing.yml// file and must be of class //sfDoctrineRouteCollection// (for Doctrine orm) or //sfPropelRouteCollection// (for Propel orm). ====generator > param > actions_base_class==== Defines a name of a class which is extended by the generated action class. Default: //sfActions// ====generator > param > css==== Specifies the stylesheet to use in the generated module. If you want to use the default admin generator style, do not define this option. To deactivate the default admin generator theme, set //css// option to //false//. =====Main generator configuration===== ====generator > param > config==== Specifies an array of options where the main generator configuration is done. The //config// entry is organized into seven sections which by default are defined as empty, as the admin generator defines sensible defaults for all possible options: generator: param: config: actions: ~ fields: ~ list: ~ filter: ~ form: ~ edit: ~ new: ~ Some of the options below can take model object placeholders. A placeholder is a string which follows the pattern: //%%NAME%%//. The //NAME// string can be anything that can be converted to a valid object getter method (//get// suffixed by the camel-cased version of the //NAME// string). For instance, //%%title%%// will be replaced by the value of //$article->getTitle()//. Placeholder values are dynamically replaced at runtime according to the object associated with the current context. When a model has a foreign key to another model, Propel and Doctrine define a getter for the related object. As for any other getter, it can be used as a placeholder if you define a meaningful //__toString()// method that converts the object to a string. The admin generator configuration is based on a configuration cascade principle. The inheritance rules are the following: * //new// and //edit// inherit from //form// which inherits from //fields//; * //list// inherits from //fields//; * //filter// inherits from //fields//. ====Default configuration for the actions==== ====generator > param > config > actions==== Defines a default configuration for the actions found on the list and on the forms. ====generator > param > config > actions > action_name==== Defines the action name to execute without the //execute// prefix. The framework defines several built-in actions. They are all prefixed by an underscore (eg.: //_edit//, //_new//, //_delete//, etc.). Each action can be customized with the options described in this section. The same options can be used when defining an action in the //list//, //edit//, or //new// entries. ====generator > param > config > actions > action_name > label==== Defines the label to use for the action. Default: //The action_name key// ====generator > param > config > actions > action_name > action==== Defines the action name to execute without the //execute// prefix. Default: //The action_name key// ====generator > param > config > actions > action_name > credentials==== Defines credentials the user must have for the action to be displayed. The credentials are to be defined with the same rules as in the //security.yml// configuration file. The credential management in the admin generator only takes care of the display. However, even if the link or button does not appear, the actions must still be properly secured from illicit access. ====generator > param > config > actions > action_name > params==== Defines an array of HTML parameters which are added to the action link (). You can also specify any of the options available for the //link_to()// helper. ====generator > param > config > actions > action_name > params > html_attribute==== Specifies a HTML attribute and its value which is added to the action link (//Action//). ====generator > param > config > actions > action_name > params > absolute==== If set to //true//, the generator renders an absolute URL for the action link. Possible values: //// ====generator > param > config > actions > action_name > params > query_string==== Specifies a query string to append (starting by ?) to the action URL. ====generator > param > config > actions > action_name > params > anchor==== Specifies an anchor to append (starting by #) to the action URL. ====generator > param > config > actions > action_name > params > confirm==== Displays a javascript confirmation alert when the action link is clicked. ====generator > param > config > actions > action_name > params > popup==== If set to //true//, the action link opens a new browser window. Possible values: //// ====generator > param > config > actions > action_name > params > post==== If set to //true//, the link submits a //POST// request instead of //GET//. Possible values: //// ====generator > param > config > actions > action_name > params > method==== If set to //POST//, //DELETE//, or //PUT//, the action link submits a request with the given HTTP method instead of //GET//. ====Default configuration for the fields==== ====generator > param > config > fields==== Defines the default configuration for each field. This configuration is defined for all pages and can be overridden on a page per page basis (//list//, //filter//, //form//, //edit//, and //new//). Based on the context, the admin generator is smart enough to know how to render fields. To customize the rendering, you can create a partial or a component. By convention, partials are prefixed with an underscore (_), and components by a tilde (~): display: [_title, ~content] In the above example, the title field will be rendered by the title partial, and the content field by the content component. The admin generator passes some parameters to partials and components. For the //New// and //Edit// page: * //form//: The form associated with the current model object; * //attributes//: An array of HTML attributes to be applied to the widget. For the //List// page: * //type//: list; * //MODEL_NAME//: The current object instance, where MODEL_NAME is the singular name set in the generator options. If no explicit value is defined, singular name will default to the underscored version of the model class name (i.e. CamelCase becomes camel_case). ====generator > param > config > fields > field_name==== Specifies a field name. A field can be a real column name, or a virtual one. In both cases, a getter must be defined in the model class (//get// suffixed by the camel-cased field name). ====generator > param > config > fields > field_name > label==== Defines the label to use for the field. Default: //The humanized column name// ====generator > param > config > fields > field_name > help==== Defines the help text to display for the field. ====generator > param > config > fields > field_name > attributes==== Defines the HTML attributes to pass to the widget, eg.: config: fields: slug: attributes: class: foo disabled: true ====generator > param > config > fields > field_name > credentials==== Defines credentials the user must have for the field to be displayed. The credentials are only enforced for the object list. The credential are to be defined with the same rules as in the security.yml configuration file, eg.: config: fields: slug: credentials: [[admin, moderator]] ====generator > param > config > fields > field_name > renderer==== Defines a PHP callback to call to render the field. If defined, it overrides any other flag like the partial or component ones. The callback is called with two parameters: the value of the field and the array of arguments defined by the //renderer_arguments// option. Below is an example of how to render field text using //rendertext// function: config: fields: name: renderer: rendertext You can also use static methods in any class for a callback function: config: fields: name: renderer: [MyClass, rendertext] In previous example //MyClass::rendertext// method will be called to render field text. ====generator > param > config > fields > field_name > renderer_arguments==== Defines an array of arguments to pass to the //renderer// PHP callback when rendering the field. It is only used if the //renderer// option is defined. Default: //array()// ====generator > param > config > fields > field_name > type==== Defines the type of the column. By default, symfony uses the type defined in your model definition, but if you create a virtual column, you can override the default //Text// type by one of the valid types: * //ForeignKey// * //Boolean// * //Date// * //Time// * //Text// * //Enum// (only available for Doctrine) ====generator > param > config > fields > field_name > date_format==== Defines the format to use when displaying dates. It can be any format recognized by the //sfDateFormat// class. This option is not used when the field type is //Date//. The following tokens can be used for the format: * //G//: Era * //y//: year * //M//: mon * //d//: mday * //h//: Hour12 * //H//: hours * //m//: minutes * //s//: seconds * //E//: wday * //D//: yday * //F//: DayInMonth * //w//: WeekInYear * //W//: WeekInMonth * //a//: AMPM * //k//: HourInDay * //K//: HourInAMPM * //z//: TimeZone For more information visit: http://trac.symfony-project.org/wiki/formatDateHowTo Default: //f// ====generator > param > config > fields > field_name > is_link==== Specifies whether or not to convert the field value to a link that goes to the Edit page of the current object. This option is equivalent to the equal sign (=) in the //display// option. Possible values: //// Default: //false// ====generator > param > config > fields > field_name > is_real==== Specifies whether or not to display the sort link in the list view header. If you customize the list view to include columns that displays data from a foreign table or from virtual columns, the generator will not automatically create sort links for them. You must set //is_true// option to //true// and modify your action and model classes to include sorting logic for those columns. You can find the full story here. Possible values: //// Default: //true (for root table colums), false (for virtual or foreign columns)// ====generator > param > config > fields > field_name > is_partial==== If set to //true//, Symfony tries to include the partial, which name equals to //field_name// and which must display fields value. Possible values: //// Default: //false// ====generator > param > config > fields > field_name > is_component==== If set to //true//, Symfony tries to include the component, which name equals to //field_name// and which must display fields value. If specified both //is_component// and //is_partial//, //is_component// takes precedence. Possible values: //// Default: //false// ====List page configuration==== ====generator > param > config > list==== Defines a configuration for the list. ====generator > param > config > list > title==== Defines the title of the list page. Default: //The humanized model class name suffixed with "List"// ====generator > param > config > list > display==== Defines an array of ordered columns to display in the list. An equal sign (=) before a column is a convention to convert the string to a link that goes to the //Edit// page of the current object: config: list: display: [=name, slug] Default: //All model columns, in the order of their definition in the schema file// ====generator > param > config > list > hide==== Defines the columns to hide from the list. It is opposite to the //display[/i option. Instead of specifying the columns to be displayed with the [i]display// option, it is sometimes faster to hide some columns: config: list: hide: [created_at, updated_at] If both the //display// and the //hide// options are provided, the //hide// option is ignored. ====generator > param > config > list > layout==== Defines what layout to use to display the list. With the //tabular// layout, each column value is in its own table column. With the //stacked// layout, each object is represented by a single string, which is defined by the //params// option (see below). The //display// option is still needed when using the //stacked// layout as it defines the columns that will be sortable by the user. Possible values: //// Default: //tabular// ====generator > param > config > list > params==== This option is used to define the HTML string pattern to use when using a //stacked// layout. This string can contain model object placeholders: config: list: params: | %%=title%% written by %%author%% and published on %%published_at%%. An equal sign (=) before a column is a convention to convert the string to a link that goes to the //Edit// page of the current object. ====generator > param > config > list > sort==== Defines the default sort column. It is an array composed of two components: the column name and the sort order: //asc// or //desc//: config: list: sort: [published_at, desc] ====generator > param > config > list > max_per_page==== Defines the maximum number of objects to display on one page. To completely remove the pagination feature, set the //max_per_page// to //false//. Default: //20// ====generator > param > config > list > pager_class==== Defines the pager class to use when displaying the list. Default: //sfPropelPager (for Propel), sfDoctrinePager (for Doctrine)// ====generator > param > config > list > fields==== Defines a configuration for the fields available in List page. You can configure every field using the same options as defined in "Default configuration for the fields" section. ====generator > param > config > list > batch_actions==== Defines the list of actions that can be executed for a selection of objects in the list. If you don't define an //action// parameter, the admin generator will look for a method named after the camel-cased name prefixed by //executeBatch//. The executed method receives the primary keys of the selected objects via the //ids// request parameter. The batch actions feature can be disabled by setting the option to an empty array: {} Default: //{ _delete: ~ }// ==== generator > param > config > list > object_actions ==== Defines the list of actions that can be executed on each object of the list, eg.: object_actions: moveUp: { label: "move up", action: "moveUp" } moveDown: { label: "move down" } _edit: ~ _delete: ~ If you don't define an //action// parameter, the admin generator will look for a method named after the camel-cased name prefixed by //executeList//. The object actions feature can be disabled by setting the option to an empty array: {} Default: //{ _edit: ~, _delete: ~ }// ==== generator > param > config > list > actions ==== Defines actions that take no object, like the creation of a new object. If you don't define an //action// parameter, the admin generator will look for a method named after the camel-cased name prefixed by //executeList//. The actions feature can be disabled by setting the option to an empty array: {}. Default: //{ _new: ~ }// ==== generator > param > config > list > table_method ==== Defines the method to call to retrieve the objects to display in the list. This method must be created in the model table class and takes //Doctrine_Query// object as a parameter, which you can modify further, eg.: class ObjectTable extends Doctrine_Table { public function retrieveObjectList(Doctrine_Query $q) { $rootAlias = $q->getRootAlias(); $q->leftJoin($rootAlias . '.ObjectCategory c'); return $q; } } This option only exists for Doctrine. For Propel, use the //peer_method// option. Default: //doSelect// ====generator > param > config > list > peer_method==== Defines the method to call to retrieve the objects to display in the list. This option only exists for Propel. For Doctrine, use the //table_method// option. Default: //doSelect// ====generator > param > config > list > table_count_method==== Defines the method to call to compute the number of objects for the current filter. This option only exists for Doctrine. For Propel, use the //peer_count_method// option. Default: //doCount// ====generator > param > config > list > peer_count_method==== Defines the method to call to compute the number of objects for the current filter. This option only exists for Propel. For Doctrine, use the //table_count_method// option. Default: //doCount// ====Filters configuration==== ====generator > param > config > filter==== Defines the configuration for the filtering form displayed on the List page. ====generator > param > config > filter > display==== Defines the ordered list of fields to display in the filter form. Note that as filter fields are always optional, there is no need to override the filter form class to configure the fields to be displayed. Default: //All fields defined in the filter form class, in the order of their definition// ====generator > param > config > filter > class==== Defines the form class to use for the filter form. To completely remove the filtering feature, set the //class// to //false//. Default: //The model class name suffixed by FormFilter// ====generator > param > config > filter > fields==== Defines a configuration for the fields available in filter form. You can configure every field using the same options as defined in "Default configuration for the fields" section. ====Default forms configuration==== ====generator > param > config > form==== Defines configuration for the New and Edit pages.The //form// section only exists as a fallback for the //edit// and //new// sections (//edit// and //new// sections inherits all options from the //form// section). ====generator > param > config > form > display==== Defines the ordered list of fields to display in Edit and New pages. This option can also be used to arrange fields into groups: config: form: display: NONE: [id] Content: [title, body, author] Admin: [is_published, expires_at] The above configuration defines two groups (//NONE//, //Content// and //Admin//), each containing a subset of the form fields. Groups with label "//NONE//" have no label. Default: //All fields defined in the form class, in the order of their definition// ====generator > param > config > form > class==== Specifies the form class to use in Edit and New pages. ====generator > param > config > form > fields==== Defines a default configuration for the fields found on the Edit and New forms. You can configure every field using the same options as defined in "Default configuration for the fields" section. ====generator > param > config > form > actions==== Defines a default configuration for the actions found on the Edit and New pages. You can configure every action using the same options as defined in "Default configuration for the actions" section. Default: //{ _delete: ~, _list: ~, _save: ~, _save_and_add: ~ }// ====Edit page configuration==== ====generator > param > config > edit==== Defines a specific configuration for the Edit page. ====generator > param > config > edit > display==== Defines the ordered list of fields to display in the Edit page. This option can also be used to arrange fields into groups (example is provided in the //"Default forms configuration"// section). If not defined, this option inherits value from the //display// option in the //form// section. Default: //All fields defined in the form class, in the order of their definition// ====generator > param > config > edit > title==== Defines the title heading of the Edit page. It can contain model object placeholders. Default: //"Edit " suffixed by the humanized model class name// ====generator > param > config > edit > fields==== Defines a configuration for the fields available in Edit form. You can configure every field using the same options as defined in "Default configuration for the fields" section. ====generator > param > config > edit > actions==== Defines actions available in Edit page. You can configure every action using the same options as defined in "Default configuration for the actions" section. Default: //{ _delete: ~, _list: ~, _save: ~ }// ====New page configuration==== ====generator > param > config > new==== Defines a specific configuration for the New page. ====generator > param > config > new > display==== Defines the ordered list of fields to display in the New page. This option can also be used to arrange fields into groups (example is provided in the //"Default forms configuration"// section). If not defined, this option inherits value from the //display// option in the //form// section. Default: //All fields defined in the form class, in the order of their definition// ====generator > param > config > new > title==== Defines the title of the New page. It can contain model object placeholders. Default: //"New " suffixed by the humanized model class name// ====generator > param > config > new > fields==== Defines a configuration for the fields available in New form. You can configure every field using the same options as defined in "Default configuration for the fields" section. ====generator > param > config > new > actions==== Defines actions available in New page. You can configure every action using the same options as defined in "Default configuration for the actions" section. Default: //{ _delete: ~, _list: ~, _save: ~, _save_and_add: ~ }//