Author: francois Date: 2010-05-17 15:26:14 +0200 (Mon, 17 May 2010) New Revision: 29492
Modified: plugins/sfPropel15Plugin/trunk/README plugins/sfPropel15Plugin/trunk/doc/form.txt Log: [sfPropel15Plugin] Updated Documentation Modified: plugins/sfPropel15Plugin/trunk/README =================================================================== --- plugins/sfPropel15Plugin/trunk/README 2010-05-17 13:10:55 UTC (rev 29491) +++ plugins/sfPropel15Plugin/trunk/README 2010-05-17 13:26:14 UTC (rev 29492) @@ -107,72 +107,30 @@ ### Filter and Edit forms enhancement - **YAML widget customization**: The `generator.yml` format was extended to allow widget and validator customization directly in YAML, without the need to edit a form object. You can also safely omit a field from a `display` list in a form definition, without any risk to loose data. -- **Plain text widget**: If you want to display some data in a form without allowing the user to edit it, use the `type: plain` attribute, just like in the old days of symfony 1.2. This is very useful for columns managed by the model, like `created_at` and `updated_at` columns. +- **Plain text field**: If you want to display some data in a form without allowing the user to edit it, use the `type: plain` attribute, just like in the old days of symfony 1.2. This is very useful for columns managed by the model, like `created_at` and `updated_at` columns. The new options for the `admin15` generator theme are fully documented, and illustrated by real life examples, in the [`doc/admin_generator.txt`](http://trac.symfony-project.org/browser/plugins/sfPropel15Plugin/trunk/doc/admin_generator.txt) file in this plugin source code. Form Subframework Modifications ------------------------------- -### Updated `sfWidgetFormPropelChoice` widget +- **Updated `sfWidgetFormPropelChoice` widget**: The widget now uses the new Query API. You can customize the list of choices more easily by executing custom query methods, using the new `query_methods` option. +- **Updated Propel validators**: Both the `sfValidatorPropelChoice` and the `sfValidatorPropelUnique` were updated to use the new PropelQuery objects, and to accept a `query_methods` option similar to the one of `sfWidgetFormPropelChoice`. +- **Plain text widget and validator**: This new widget allows a field to be displayed in a form, without letting the use change it. +- **Easy Relation Embed**: Editing related objects together with the main objects (e.g., editing `Comments` in a `Post` form) is a piece of cake. The new `sfFormPropel::embedRelation()` method does all the work to fetch related objects, build the forms for each of them, and embed the related object forms into the main form. Embdeded relation forms allow to **edit**, **add**, and **delete** a related objects with no additional code. -The `sfWidgetFormPropelChoice` widget now uses the new Query API. You can customize the list of choices more easily by executing custom query methods, using the new `query_methods` option. For instance, if the `Section` model uses the `nested_set` behavior, you probably want to display a section selection widget in hierarchical order. This is easily achived by execiting the `orderByBranch()` query method, and you can register it as follows: - [php] - class ContentForm extends BaseContentForm + class ArticleForm extends BaseArticleForm { public function configure() { - $this->widgetSchema['section'] = new sfWidgetFormPropelChoice(array( - 'model' => 'Section', - 'query_methods' => array('orderByBranch') - 'add_empty' => true, - )); + $this->embedRelation('Book'); } } -In practice, you won't need to build a custom Criteria object to achieve a custom list choice - but it still works: +The Propel widgets, validators, and form classes are fully documented in the [`doc/form.txt`](http://trac.symfony-project.org/browser/plugins/sfPropel15Plugin/trunk/doc/form.txt) file in this plugin source code. - [php] - class ContentForm extends BaseContentForm - { - public function configure() - { - $query = SectionQuery::create() - ->filterByIsVisible(true); - $this->widgetSchema['section'] = new sfWidgetFormPropelChoice(array( - 'model' => 'Section', - 'criteria' => $query, - 'add_empty' => true, - )); - } - } +Routing Modifications +--------------------- -### Updated Propel validators - -Both the `sfValidatorPropelChoice` and the `sfValidatorPropelUnique` were updated to use the new PropelQuery objects, and to accept a `query_methods` option similat to the one of `sfWidgetFormPropelChoice`. So if you display a selection of items using a query method, you can validate this selection, too: - - [php] - class ContentForm extends BaseContentForm - { - public function configure() - { - $this->widgetSchema['section']->setOption('query_methods', array('published')); - $this->validatorSchema['section']->setOption('query_methods', array('published')); - } - } - -The two widgets and the validator are fully documented in the [`doc/form.txt`](http://trac.symfony-project.org/browser/plugins/sfPropel15Plugin/trunk/doc/form.txt) file in this plugin source code. - -### Easy Relation Embed - -Editing related objects together with the main objects (e.g., editing Comments in a Post form) is a piece of cake. The new `sfFormPropel::embedRelation()` method does all the work to fetch related objects, build the forms for each of them, and embed the related object forms into the main form. Embdeded relation forms allow to **edit**, **add**, and **delete** a related objects with no additional code. - - [php] - class ArticleForm extends BaseArticleForm - { - public function configure() - { - $this->embedRelation('Book'); - } - } \ No newline at end of file +The plugin offer two new routing classes, `sfPropel15Route` and `sfPropel15RouteCollection`. These classes are used by default in the models build with the propel admin generator. They behave just like the previous `sfPropelRoute` class. \ No newline at end of file Modified: plugins/sfPropel15Plugin/trunk/doc/form.txt =================================================================== --- plugins/sfPropel15Plugin/trunk/doc/form.txt 2010-05-17 13:10:55 UTC (rev 29491) +++ plugins/sfPropel15Plugin/trunk/doc/form.txt 2010-05-17 13:26:14 UTC (rev 29492) @@ -8,6 +8,8 @@ Editing a foreign key columns is often a matter of choosing the related object to relate. For instance, editing the `author_id` field of an `Article` model means choosing an element in the list of existing Authors. `sfPropel15Plugin` provides an extension of the `sfWidgetFormChoice` class that takes care of populating the list of options based on a related table. It is called `sfWidgetPropelChoice`, and is associated witha validator called `sfValidatorPropelChoice`. +### Generated Configuration + Most of the time, the configuration of this widget and validator is already done in the generated forms and filter forms. Using the previous example model, Propel would generate the following Base form: [php] @@ -19,21 +21,46 @@ $this->setWidgets(array( // ... - 'author_id' => new sfWidgetFormPropelChoice(array('model' => 'Author', 'add_empty' => true)), + 'author_id' => new sfWidgetFormPropelChoice(array( + 'model' => 'Author', + 'add_empty' => true) + ), )); $this->setValidators(array( // ... - 'author_id' => new sfValidatorPropelChoice(array('model' => 'Author', 'column' => 'id', 'required' => false)), + 'author_id' => new sfValidatorPropelChoice(array( + 'model' => 'Author', + 'column' => 'id', + 'required' => false) + ), )); } } Based on the `model` setting, the plugin generates the list of possible choices for the widget and the validator. -You can filter the list of authors using any of the methods available in the `AuthorQuery` class. If you need to display only the list of active authors, customize the form as follows: +### Additional Query Methods +You can set the widget to execute additional query methods on the related Model Query object. For instance, if a `Section` model uses the `nested_set` behavior, you probably want to display a section selection widget in hierarchical order. This is easily achived by executing the `SectionQuery::orderByBranch()` query method, and you can register it as follows: + [php] + class ContentForm extends BaseContentForm + { + public function configure() + { + $this->widgetSchema['section'] = new sfWidgetFormPropelChoice(array( + 'model' => 'Section', + 'query_methods' => array('orderByBranch') + 'add_empty' => true, + )); + } + } + + +You can also enable the `query_method` option on an existing widget. For instance, to display only the list of active authors, customize the form as follows: + + [php] class ArticleForm extends BaseArticleForm { public function configure() @@ -50,6 +77,22 @@ } } +Of course, to allow the validation of the user's choice, the `query_methods` option is also available in the `sfValidatorPropelChoice` validator. Always remember to apply the same filters in the validator as in the widget. + +So if you display a selection of items using a query method, you can validate this selection, too: + + [php] + class ContentForm extends BaseContentForm + { + public function configure() + { + $this->widgetSchema['section']->setOption('query_methods', array('published')); + $this->validatorSchema['section']->setOption('query_methods', array('published')); + } + } + +### Using A Custom Query Object + Alternatively, build the query yourself in the form, and pass it to the widget in the `criteria` option: [php] @@ -62,8 +105,10 @@ } } -Of course, to allow the validation of the user's choice, both the `query_methods` and `criteria` options are also available in the `sfValidatorPropelChoice`. Always remember to apply the same filters in the validator as inthe widget. +The `criteria` option is also available in `sfValidatorPropelChoice`. +### Full Options List + The `sfWidgetFormPropelChoice` widget supports the following options: * `model`: The model class (required) @@ -102,7 +147,9 @@ // ... $this->validatorSchema->setPostValidator( - new sfValidatorPropelUnique(array('model' => 'Article', 'column' => array('slug'))) + new sfValidatorPropelUnique(array( + 'model' => 'Article', + 'column' => array('slug'))) ); } } -- You received this message because you are subscribed to the Google Groups "symfony SVN" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/symfony-svn?hl=en.
