Author: francois
Date: 2010-04-22 13:58:42 +0200 (Thu, 22 Apr 2010)
New Revision: 29234
Added:
plugins/sfPropel15Plugin/trunk/doc/form.txt
Modified:
plugins/sfPropel15Plugin/trunk/README
Log:
[sfPropel15Plugin] Added complete documentation of the Propel widgets and
validators
Modified: plugins/sfPropel15Plugin/trunk/README
===================================================================
--- plugins/sfPropel15Plugin/trunk/README 2010-04-22 10:22:01 UTC (rev
29233)
+++ plugins/sfPropel15Plugin/trunk/README 2010-04-22 11:58:42 UTC (rev
29234)
@@ -157,4 +157,6 @@
$this->widgetSchema['section']->setOption('query_methods',
array('published'));
$this->validatorSchema['section']->setOption('query_methods',
array('published'));
}
- }
\ No newline at end of file
+ }
+
+The two widgets and the validator are fully documented in the
[`doc/form.txt`](http://trac.symfony-project.org/browser/plugins/sfPropel15Plugin/doc/form.txt)
file in this plugin source code.
\ No newline at end of file
Added: plugins/sfPropel15Plugin/trunk/doc/form.txt
===================================================================
--- plugins/sfPropel15Plugin/trunk/doc/form.txt (rev 0)
+++ plugins/sfPropel15Plugin/trunk/doc/form.txt 2010-04-22 11:58:42 UTC (rev
29234)
@@ -0,0 +1,121 @@
+Form Extensions
+===============
+
+The `sfPropel15Plugin` provides one widget and two validators, to help build
and validate forms bound to a Model object.
+
+`sfWidgetPropelChoice` and `sfValidatorPropelChoice`
+----------------------------------------------------
+
+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`.
+
+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]
+ abstract class BaseArticleForm extends BaseFormPropel
+ {
+ public function setup()
+ {
+ // ...
+
+ $this->setWidgets(array(
+ // ...
+ 'author_id' => new sfWidgetFormPropelChoice(array('model' =>
'Author', 'add_empty' => true)),
+ ));
+
+ $this->setValidators(array(
+ // ...
+ '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:
+
+ [php]
+ class ArticleForm extends BaseArticleForm
+ {
+ public function configure()
+ {
+ $this->widgetSchema['author_id']->setOption('query_methods',
array('active'));
+ }
+ }
+
+ class ArticleQuery extends BaseArticleQuery
+ {
+ public function active()
+ {
+ return $this->filterByIsActive(true);
+ }
+ }
+
+Alternatively, build the query yourself in the form, and pass it to the widget
in the `criteria` option:
+
+ [php]
+ class ArticleForm extends BaseArticleForm
+ {
+ public function configure()
+ {
+ $query = ArticleQuery::create()->filterByIsActive(true);
+ $this->widgetSchema['author_id']->setOption('criteria', $query);
+ }
+ }
+
+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 `sfWidgetFormPropelChoice` widget supports the following options:
+
+* `model`: The model class (required)
+* `add_empty`: Whether to add a first empty value or not (false by default).
If the option is not a Boolean, the value will be used as the text value
+* `method`: The method to use to display object values (__toString by default)
+* `key_method`: The method to use to display the object keys (getPrimaryKey by
default)
+* `order_by`: An array composed of two fields:
+ * The column to order by the results (must be in the PhpName format)
+ * asc or desc
+* `query_methods`: An array of method names listing the methods to execute on
the model's query object
+* `criteria`: A criteria to use when retrieving objects
+* `connection`: The Propel connection to use (null by default)
+* `multiple`: true if the select tag must allow multiple selections
+
+The `sfValidatorPropelChoice` validator accepts almost the same options:
+
+* `model`: The model class (required)
+* `query_methods`: An array of method names listing the methods to execute on
the model's query object
+* `criteria`: A criteria to use when retrieving objects
+* `column`: The column name (null by default which means we use the primary
key) must be in field name format
+* `connection`: The Propel connection to use (null by default)
+* `multiple`: true if the select tag must allow multiple selections
+* `min`: The minimum number of values that need to be selected (this option is
only active if multiple is true)
+* `max`: The maximum number of values that need to be selected (this option is
only active if multiple is true)
+
+
+`sfValidatorPropelUnique`
+-------------------------
+
+In a blog application, two articles can not have the same slug; to ensure this
constraint, the schema definition features a uniqueness constraint. This
constraint on the database level is reflected in the ArticleForm form using the
`sfValidatorPropelUnique` validator. This validator can check the uniqueness of
any form field. It is helpful among other things to check the uniqueness of an
email address of a login for instance. The next listing shows how to use it in
the ArticleForm form.
+
+ [php]
+ class ArticleForm extends BaseArticleForm
+ {
+ public function configure()
+ {
+ // ...
+
+ $this->validatorSchema->setPostValidator(
+ new sfValidatorPropelUnique(array('model' => 'Article', 'column' =>
array('slug')))
+ );
+ }
+ }
+
+The sfValidatorPropelUnique validator is a postValidator running on the whole
data after the individual validation of each field. In order to validate the
slug uniqueness, the validator must be able to access, not only the slug value,
but also the value of the primary key(s). Validation rules are indeed different
throughout the creation and the edition since the slug can stay the same during
the update of an article.
+
+This validator supports the following options:
+
+* `model`: The model class (required)
+* `column`: The unique column name in Propel field name format (required). If
the uniquess is for several columns, you can pass an array of fiel names
+* `query_methods`: An array of method names listing the methods to executeon
the model's query object
+* `field`: Field name used by the form, other than the column name
+* `primary_key`: The primary key column name in Propel field name format
(optional, will be introspected if not provided). You can also pass an array if
the table has several primary keys
+* `connection`: The Propel connection to use (null by default)
+* `throw_global_error`: Whether to throw a global error (false by default) or
an error tied to the first field related to the column option array
Property changes on: plugins/sfPropel15Plugin/trunk/doc/form.txt
___________________________________________________________________
Added: svn:executable
+ *
--
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.
