Skip to content

[Reference][Forms] add an introductory table containing all options of the basic form type #3611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 19, 2014
Merged

[Reference][Forms] add an introductory table containing all options of the basic form type #3611

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
911cc70
add an introductory table containing all options of the basic form type
xabbuh Feb 26, 2014
2ca0306
document the options inherited from the BaseType class
xabbuh Mar 8, 2014
58170fe
document the auto_initialize option for the form type, refs #3410
xabbuh Mar 8, 2014
b3ca94c
removed the description of the auto_initialize option from the button…
xabbuh Mar 9, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions reference/forms/types/button.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,24 @@ A simple, non-responsive button.
+----------------------+----------------------------------------------------------------------+
| Rendered as | ``button`` tag |
+----------------------+----------------------------------------------------------------------+
| Options | - `attr`_ |
| | - `disabled`_ |
| Inherited | - `attr`_ |
| options | - `disabled`_ |
| | - `label`_ |
| | - `translation_domain`_ |
+----------------------+----------------------------------------------------------------------+
| Overridden options | - `auto_initialize`_ |
+----------------------+----------------------------------------------------------------------+
| Parent type | none |
+----------------------+----------------------------------------------------------------------+
| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ButtonType` |
+----------------------+----------------------------------------------------------------------+

Options
-------
Inherited options
-----------------

The following options are defined in the
:class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\BaseType` class.
The ``BaseType`` class is the parent class for both the ``button`` type and
the :doc:`form type </reference/forms/types/form>`, but it is not part of
the form type tree (i.e. it can not be used as a form type on its own).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if I want this level of detail here - I don't think it matters very much what the parent type is when it's "form", and I especially don't think it's very important to say exactly which class you can find the code in. Thoughts?


.. include:: /reference/forms/types/options/button_attr.rst.inc

Expand All @@ -34,8 +38,3 @@ Options
.. include:: /reference/forms/types/options/button_label.rst.inc

.. include:: /reference/forms/types/options/button_translation_domain.rst.inc

Overridden Options
------------------

.. include:: /reference/forms/types/options/button_auto_initialize.rst.inc
78 changes: 65 additions & 13 deletions reference/forms/types/form.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,47 @@
form Field Type
===============

See :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType`.

The ``form`` type predefines a couple of options that are then available
on all fields.
on all types for which ``form`` is the parent type.

+-----------+--------------------------------------------------------------------+
| Options | - `compound`_ |
| | - `data`_ |
| | - `data_class`_ |
| | - `empty_data`_ |
| | - `required`_ |
| | - `label_attr`_ |
| | - `constraints`_ |
| | - `cascade_validation`_ |
| | - `read_only`_ |
| | - `trim`_ |
| | - `mapped`_ |
| | - `property_path`_ |
| | - `max_length`_ |
| | - `by_reference`_ |
| | - `error_bubbling`_ |
| | - `inherit_data`_ |
| | - `error_mapping`_ |
| | - `invalid_message`_ |
| | - `invalid_message_parameters`_ |
| | - `extra_fields_message`_ |
| | - `post_max_size_message`_ |
| | - `pattern`_ |
+-----------+--------------------------------------------------------------------+
| Inherited | - `block_name`_ |
| options | - `disabled`_ |
| | - `label`_ |
| | - `attr`_ |
| | - `translation_domain`_ |
| | - `auto_initialize`_ |
+-----------+--------------------------------------------------------------------+
| Parent | none |
+-----------+--------------------------------------------------------------------+
| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\FormType` |
+-----------+--------------------------------------------------------------------+

Options
-------

.. include:: /reference/forms/types/options/data.rst.inc

Expand All @@ -25,8 +62,6 @@ on all fields.

.. include:: /reference/forms/types/options/required.rst.inc

.. include:: /reference/forms/types/options/label.rst.inc

.. include:: /reference/forms/types/options/label_attr.rst.inc

.. include:: /reference/forms/types/options/constraints.rst.inc
Expand All @@ -35,20 +70,12 @@ on all fields.

.. include:: /reference/forms/types/options/read_only.rst.inc

.. include:: /reference/forms/types/options/disabled.rst.inc

.. include:: /reference/forms/types/options/trim.rst.inc

.. include:: /reference/forms/types/options/mapped.rst.inc

.. include:: /reference/forms/types/options/property_path.rst.inc

.. include:: /reference/forms/types/options/attr.rst.inc

.. include:: /reference/forms/types/options/translation_domain.rst.inc

.. include:: /reference/forms/types/options/block_name.rst.inc

.. _reference-form-option-max_length:

.. include:: /reference/forms/types/options/max_length.rst.inc
Expand All @@ -72,3 +99,28 @@ on all fields.
.. _reference-form-option-pattern:

.. include:: /reference/forms/types/options/pattern.rst.inc

.. include:: /reference/forms/types/options/action.rst.inc

.. include:: /reference/forms/types/options/method.rst.inc

Inherited options
-----------------

The following options are defined in the
:class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\BaseType` class.
The ``BaseType`` class is the parent class for both the ``form`` type and
the :doc:`button type </reference/forms/types/button>`, but it is not part
of the form type tree (i.e. it can not be used as a form type on its own).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I am kind of ok with the note here :), I think because if you're looking at this type, you're already in a more "abstract" and advanced place (since you don't actually, knowingly use "form" directly).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure either. But we should be consistent. If we remove this note, we should also remove the "Overriden option" label for the auto_initialize option as you suggested. Otherwise it may confuse people.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, I'm cool with removing auto_initialize from "Overridden Options" as I mentioned below. Besides, I'm not sure if there is a real use case at all for even knowing this option exists, so we should give it as little attention as possible.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with this. Thus, I removed its description.


.. include:: /reference/forms/types/options/block_name.rst.inc

.. include:: /reference/forms/types/options/disabled.rst.inc

.. include:: /reference/forms/types/options/label.rst.inc

.. include:: /reference/forms/types/options/attr.rst.inc

.. include:: /reference/forms/types/options/translation_domain.rst.inc

.. include:: /reference/forms/types/options/auto_initialize.rst.inc
8 changes: 8 additions & 0 deletions reference/forms/types/options/auto_initialize.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
auto_initialize
~~~~~~~~~~~~~~~

**type**: ``boolean`` **default**: ``true``

An internal option: sets whether the form should be initialized automatically.
For all fields, this option should only be ``true`` for root forms. You won't
need to change this option and probably won't need to worry about it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that we already have button_auto_initialize.rst.inc. I know that technically, how this is set to false is different between a button and other fields, but is there a practical difference? If not, we should delete the button_auto_initialize.rst.inc and include this one.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, and if I'm thinking about this correctly, then there's really no purpose of having auto_initialize as an "Overridden option" on the button docs. Yes, technically it is overridden, but it seems in practice it's not (it's false on all non-root forms, which strangely, I think is done on Form::add, not inside a form type).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, the default value is different for both types. Of course, we can consolidate both by creating a general file where we put a sentence like "default value is false for the button type, true for all other types". But I'm not sure if that is as clear as the solution we already have.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But practically, it's false for everything except for the parent form (it's just that this is done inside the Form::add method, and not in a form type). So in practice, I would argue that this option should appear only on the "form" type and shouldn't appear anywhere else as an overridden option.

9 changes: 0 additions & 9 deletions reference/forms/types/options/button_auto_initialize.rst.inc
View file
Open in desktop

This file was deleted.