From 051a23f141798d84e2cc9040803c6cff9697a85b Mon Sep 17 00:00:00 2001 From: daFish Date: Thu, 29 Nov 2012 16:25:30 +0100 Subject: [PATCH 1/2] document how to render custom collection prototypes --- cookbook/form/form_collections.rst | 70 ++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 866a1d1b024..8511844e855 100644 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -729,5 +729,75 @@ the relationship between the removed ``Tag`` and ``Task`` object. updated (whether you're adding new tags or removing existing tags) on each Tag object itself. +.. _cookbook-form-collections-custom-prototype: + +Rendering a Custom Prototype +---------------------------- + +Most of the time the provided prototype will be sufficient for your needs +and does not need to be changed. But if you are in the situation were you +need to have a complete custom prototype, you can render it yourself. + +The Form component automatically looks for a block whose name follows a certain +schema to decide how to render each entry of the form type collection. For +example, if your form field is named ``tasks``, you will be able to change +the widget for each task as follows: + +.. configuration-block:: + + .. code-block:: html+jinja + + {% form_theme form _self %} + + {% block _tasks_entry_widget %} + + {{ form_widget(task.task) }} + {{ form_widget(task.dueDate) }} + + {% endblock %} + + .. code-block:: html+php + + + + widget($form->task) ?> + widget($form->dueDate) ?> + + +Not only can you override the rendered widget, but you can also change the +complete form row or the label as well. For the ``tasks`` field given above, +the block names would be the following: + +================ ======================= +Part of the Form Block Name +================ ======================= +``label`` ``_tasks_entry_label`` +``widget`` ``_tasks_entry_widget`` +``row`` ``_tasks_entry_row`` +================ ======================= + +Then, you only have to ensure to render the collection type's ``data-prototype`` +property with the proper prototype so that new entries will be rendered the +same way as existing ones: + +.. configuration-block:: + + .. code-block:: html+jinja + + {% form_theme form _self %} + + {% block _tasks_widget %} + {% set attr = attr|merge({ 'data-prototype': form_row(prototype) }) %} + + {% for child in form %} + {{ form_row(child) }} + {% endfor %} +
+ {% endblock %} + + .. code-block:: html+php + + + .. _`Owning Side and Inverse Side`: http://docs.doctrine-project.org/en/latest/reference/unitofwork-associations.html .. _`JSFiddle`: http://jsfiddle.net/847Kf/4/ From ce8110c6a864f65336db8ccbf4bdb71cf0677326 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Thu, 20 Aug 2015 13:11:46 +0200 Subject: [PATCH 2/2] Improve docs on customizing prototype rendering --- cookbook/form/form_collections.rst | 77 +++------------------------- cookbook/form/form_customization.rst | 43 ++++++++++++++++ 2 files changed, 49 insertions(+), 71 deletions(-) diff --git a/cookbook/form/form_collections.rst b/cookbook/form/form_collections.rst index 8511844e855..a02853ea97e 100644 --- a/cookbook/form/form_collections.rst +++ b/cookbook/form/form_collections.rst @@ -262,7 +262,7 @@ great, your user can't actually add any new tags yet. .. _cookbook-form-collections-new-prototype: Allowing "new" Tags with the "Prototype" ------------------------------------------ +---------------------------------------- Allowing the user to dynamically add new tags means that you'll need to use some JavaScript. Previously you added two tags to your form in the controller. @@ -417,6 +417,11 @@ into new ``Tag`` objects and added to the ``tags`` property of the ``Task`` obje You can find a working example in this `JSFiddle`_. +.. seealso:: + + If you want to customize the HTML code in the prototype, read + :ref:`cookbook-form-custom-prototype`. + To make handling these new tags easier, add an "adder" and a "remover" method for the tags in the ``Task`` class:: @@ -729,75 +734,5 @@ the relationship between the removed ``Tag`` and ``Task`` object. updated (whether you're adding new tags or removing existing tags) on each Tag object itself. -.. _cookbook-form-collections-custom-prototype: - -Rendering a Custom Prototype ----------------------------- - -Most of the time the provided prototype will be sufficient for your needs -and does not need to be changed. But if you are in the situation were you -need to have a complete custom prototype, you can render it yourself. - -The Form component automatically looks for a block whose name follows a certain -schema to decide how to render each entry of the form type collection. For -example, if your form field is named ``tasks``, you will be able to change -the widget for each task as follows: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% form_theme form _self %} - - {% block _tasks_entry_widget %} - - {{ form_widget(task.task) }} - {{ form_widget(task.dueDate) }} - - {% endblock %} - - .. code-block:: html+php - - - - widget($form->task) ?> - widget($form->dueDate) ?> - - -Not only can you override the rendered widget, but you can also change the -complete form row or the label as well. For the ``tasks`` field given above, -the block names would be the following: - -================ ======================= -Part of the Form Block Name -================ ======================= -``label`` ``_tasks_entry_label`` -``widget`` ``_tasks_entry_widget`` -``row`` ``_tasks_entry_row`` -================ ======================= - -Then, you only have to ensure to render the collection type's ``data-prototype`` -property with the proper prototype so that new entries will be rendered the -same way as existing ones: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% form_theme form _self %} - - {% block _tasks_widget %} - {% set attr = attr|merge({ 'data-prototype': form_row(prototype) }) %} - - {% for child in form %} - {{ form_row(child) }} - {% endfor %} -
- {% endblock %} - - .. code-block:: html+php - - - .. _`Owning Side and Inverse Side`: http://docs.doctrine-project.org/en/latest/reference/unitofwork-associations.html .. _`JSFiddle`: http://jsfiddle.net/847Kf/4/ diff --git a/cookbook/form/form_customization.rst b/cookbook/form/form_customization.rst index 21a34f1b346..c6265a7528a 100644 --- a/cookbook/form/form_customization.rst +++ b/cookbook/form/form_customization.rst @@ -734,6 +734,49 @@ You can also override the markup for an entire field row using the same method: widget($form) ?> +.. _cookbook-form-custom-prototype: + +How to Customize a Collection Prototype +--------------------------------------- + +When using a :doc:`collection of forms `, +the prototype can be overridden with a completely custom prototype by +overriding a block. For example, if your form field is named ``tasks``, you +will be able to change the widget for each task as follows: + +.. configuration-block:: + + .. code-block:: html+jinja + + {% form_theme form _self %} + + {% block _tasks_entry_widget %} + + {{ form_widget(task.task) }} + {{ form_widget(task.dueDate) }} + + {% endblock %} + + .. code-block:: html+php + + + + widget($form->task) ?> + widget($form->dueDate) ?> + + +Not only can you override the rendered widget, but you can also change the +complete form row or the label as well. For the ``tasks`` field given above, +the block names would be the following: + +================ ======================= +Part of the Form Block Name +================ ======================= +``label`` ``_tasks_entry_label`` +``widget`` ``_tasks_entry_widget`` +``row`` ``_tasks_entry_row`` +================ ======================= + Other common Customizations ---------------------------