Author: francois
Date: 2010-05-14 18:52:50 +0200 (Fri, 14 May 2010)
New Revision: 29475
Modified:
plugins/sfPropel15Plugin/trunk/README
plugins/sfPropel15Plugin/trunk/doc/form.txt
plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropel.class.php
plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropelCollection.class.php
Log:
[sfPropel15Plugin] bootstrapped the embedRelation() documentation
Modified: plugins/sfPropel15Plugin/trunk/README
===================================================================
--- plugins/sfPropel15Plugin/trunk/README 2010-05-14 16:40:20 UTC (rev
29474)
+++ plugins/sfPropel15Plugin/trunk/README 2010-05-14 16:52:50 UTC (rev
29475)
@@ -162,4 +162,17 @@
}
}
-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.
\ 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/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
Modified: plugins/sfPropel15Plugin/trunk/doc/form.txt
===================================================================
--- plugins/sfPropel15Plugin/trunk/doc/form.txt 2010-05-14 16:40:20 UTC (rev
29474)
+++ plugins/sfPropel15Plugin/trunk/doc/form.txt 2010-05-14 16:52:50 UTC (rev
29475)
@@ -150,4 +150,57 @@
edit:
fields:
created_at: { type: plain }
- updated_at: { type: plain }
\ No newline at end of file
+ updated_at: { type: plain }
+
+`sfFormPropelCollection`
+------------------------
+
+If you need to build a form based on a collection of objects rather than on a
single object, then the `sfFormPropelCollection` class will help you. To create
such a form, just pass a PropelObjectcollection instance to its constructor,
and you can use the form as a regular Propel object form:
+
+ [php]
+ $collection = new PropelObjectCollection();
+ $collection->setModel('Book');
+ $collection[]= new Book();
+ $collection[]= new Book();
+ $collection[]= new Book();
+ $form = new sfFormPropelCollection($collection);
+ echo $form; // displays a list of 3 BookForms, bound to each element in
the collection
+
+Embedding A Relation Form
+-------------------------
+
+Since one-to-many relationships return `PropelCollection` objects, the ability
to create a collection form, added to the ability to merge two forms together,
makes the edition of related objects very straightforward.
+
+`sfPropelForm` provides a method called `embedRelation($relationName)`, which
fetches a collection for a given relation, creates a `sfFormPropelCollection`
instance based on the collection, and embeds this form into the main form. This
allows,for instance, to edit an author together with all its books:
+
+ [php]
+ class ArticleForm extends BaseArticleForm
+ {
+ public function configure()
+ {
+ $this->embedRelation('Book');
+ }
+ }
+
+Now the Article form displays the list of related books for each author,
together with controls to add or remove Books for a given Author. No need to
add code to the form object, it just works.
+
+**Tip**: `sfPropelForm` also supports `mergeRelation()`, which merges the
individual forms from the colleciton form into the parent form. As for embedded
forms, merged relation forms support addition and removal of related objects.
+
+`embedRelation()` offers many options to customize the embedded relation form:
+
+* `title`: The title of the collection form once embedded. Defaults to the
relation name.
+* `embedded_form_class`: The class name of the forms to embed. Uses the model
name by default (a form based on a collection of Book objects embeds BookForm
objects).
+* `collection_form_class`: Class of the collection form to return. Defaults to
sfFormPropelCollection.
+* `hide_on_new`: If true, the relation form does not appear for new objects.
Defaults to false.
+* `add_empty`: Whether to allow the user to add new objects to the collection.
Defaults to true.
+* `add_delete`: Whether to add a delete widget for each object. Defaults to
true.
+* `remove_fields`: The list of fields to remove from the embedded object forms
+* `item_pattern`: The pattern used to name each embedded form. Defaults to
'%index%'.
+
+If `add_delete` is set to `true`, the following additional options are
available:
+
+* `delete_name`: Name of the delete widget. Defaults to 'delete'.
+* `delete_widget`: Optional delete widget object. If left null, uses a
`sfWidgetFormDelete` instance, which is a checkbox widget with a Javascript
confirmation.
+* `alert_text`: The text of the Javascript alert to show.
+* `hide_parent`: Whether to hide the deleted form when clicking the checkbox.
Defaults to true.
+* `parent_level`: The number of times parentNode must be called to reach the
parent to hide. As a widget doesn't know if it's merged or embedded, this
setting allows the JavaScript code used to hide the parent to find it.
Recommended values: 6 for embedded form (default), 7 for merged form.
\ No newline at end of file
Modified: plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropel.class.php
===================================================================
--- plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropel.class.php
2010-05-14 16:40:20 UTC (rev 29474)
+++ plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropel.class.php
2010-05-14 16:52:50 UTC (rev 29475)
@@ -547,7 +547,7 @@
/**
* Embed a Collection form based on a Relation into this form.
* Available options:
- * - title: The title of the colleciton form once embedded. Defaults to the
relation name.
+ * - title: The title of the collection form once embedded. Defaults to the
relation name.
* - decorator: The decorator for the sfWidgetFormSchemaDecorator
* - add_empty: Whether to allow the user to add new objects to the
collection. Defaults to true
* Additional options are passed to sfFromPropel::getRelationForm()
@@ -598,6 +598,7 @@
$options = array_merge(array(
'hide_on_new' => false,
'collection_form_class' => 'sfFormPropelCollection',
+ 'add_delete' => true,
), $options);
if ($this->getObject()->isNew() && $options['hide_on_new'])
Modified:
plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropelCollection.class.php
===================================================================
--- plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropelCollection.class.php
2010-05-14 16:40:20 UTC (rev 29474)
+++ plugins/sfPropel15Plugin/trunk/lib/form/sfFormPropelCollection.class.php
2010-05-14 16:52:50 UTC (rev 29475)
@@ -17,6 +17,8 @@
* Form constructor.
*
* Available options:
+ * - embedded_form_class: The class name of the forms to embed. Uses the
model name by default.
+ * (a form based on a collection of Book objects embeds
BookForm objects)
* - item_pattern: The pattern used to name each embedded form. Defaults to
'%index%'.
* - add_delete: Whether to add a delete widget for each object. Defaults
to true.
* - delete_name: Name of the delete widget. Defaults to 'delete'.
@@ -38,7 +40,7 @@
{
$options = array_merge(array(
'item_pattern' => '%index%',
- 'add_delete' => true,
+ 'add_delete' => false,
'delete_name' => 'delete',
'delete_widget' => null,
'remove_fields' => array(),
--
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.
