Skip to content

Commit

Permalink
[reference][form] Large update to the formatting of the field referen…
Browse files Browse the repository at this point in the history 
…ces so that things are more usable and readable
  • Loading branch information
@weaverryan
weaverryan committed Jul 14, 2011
1 parent 8f1e280 commit 906e345
Show file tree
Hide file tree
Showing 52 changed files with 815 additions and 564 deletions.
43 changes: 24 additions & 19 deletions reference/forms/types/birthday.rst
View file
Expand Up @@ -7,39 +7,44 @@ birthday Field Type
A :doc:`date</reference/forms/types/date>` field that specializes in handling
birthdate data.

Can be rendered as a single text box or three select boxes (month, day, and year)
Can be rendered as a single text box, three text boxes (month, day, and year),
or three select boxes.

This type is essentially the same as the ``date`` type, but with a more appropriate
default for the ``years`` option. The ``years`` option defaults to 120
years ago to the current year.
This type is essentially the same as the :doc:`date</reference/forms/types/date>`
type, but with a more appropriate default for the ``years`_ option. The ``years`_
option defaults to 120 years ago to the current year.
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Underlying Data Type | can be ``DateTime``, ``string``, ``timestamp``, or ``array`` (see the :ref:`input option <form-reference-date-input>`) |
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Rendered as | can be three select boxes or a text box, based on the ``widget`` option |
| Rendered as | can be three select boxes or 1 or 3 text boxes, based on the `widget`_ option |
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Options | - ``years`` |
| Options | - `years`_ |
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Inherited | - ``widget`` |
| options | - ``input`` |
| | - ``months`` |
| | - ``days`` |
| | - ``format`` |
| | - ``pattern`` |
| | - ``data_timezone`` |
| | - ``user_timezone`` |
| Inherited | - `widget`_ |
| options | - `input`_ |
| | - `months`_ |
| | - `days`_ |
| | - `format`_ |
| | - `pattern`_ |
| | - `data_timezone`_ |
| | - `user_timezone`_ |
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Parent type | :doc:`date</reference/forms/types/date>` |
+----------------------+------------------------------------------------------------------------------------------------------------------------+
| Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\BirthdayType` |
+----------------------+------------------------------------------------------------------------------------------------------------------------+

Options
-------
Field Options
-------------

* ``years`` [type: ``array``, default: 120 years ago to the current year ]
List of years available to the year field type. This option is only
relevant when the ``widget`` option is set to ``choice``.
years
~~~~~

**type**: ``array`` **default**: 120 years ago to the current year

List of years available to the year field type. This option is only
relevant when the ``widget`` option is set to ``choice``.

Inherited options
-----------------
Expand Down
24 changes: 14 additions & 10 deletions reference/forms/types/checkbox.rst
View file
Expand Up @@ -11,12 +11,12 @@ if the box is unchecked, the value will be set to false.
+-------------+------------------------------------------------------------------------+
| Rendered as | ``input`` ``text`` field |
+-------------+------------------------------------------------------------------------+
| Options | - ``value`` |
| Options | - `value`_ |
+-------------+------------------------------------------------------------------------+
| Inherited | - ``required`` |
| options | - ``label`` |
| | - ``read_only`` |
| | - ``error_bubbling`` |
| Inherited | - `required`_ |
| options | - `label`_ |
| | - `read_only`_ |
| | - `error_bubbling`_ |
+-------------+------------------------------------------------------------------------+
| Parent type | :doc:`field</reference/forms/types/field>` |
+-------------+------------------------------------------------------------------------+
Expand All @@ -33,12 +33,16 @@ Example Usage
'required' => false,
));
Options
-------
Field Options
-------------

value
~~~~~

**type**: ``mixed`` **default**: ``1``

* ``value`` [type: mixed, default: 1]
The value that's actually used as the value for the checkbox. This does
not affect the value that's set on your object.
The value that's actually used as the value for the checkbox. This does
not affect the value that's set on your object.

Inherited options
-----------------
Expand Down
66 changes: 36 additions & 30 deletions reference/forms/types/choice.rst
View file
Expand Up @@ -13,16 +13,16 @@ option.
+-------------+-----------------------------------------------------------------------------+
| Rendered as | can be various tags (see below) |
+-------------+-----------------------------------------------------------------------------+
| Options | - ``choices`` |
| | - ``choice_list`` |
| | - ``multiple`` |
| | - ``expanded`` |
| | - ``preferred_choices`` |
| | - ``error_bubbling`` |
| Options | - `choices`_ |
| | - `choice_list`_ |
| | - `multiple`_ |
| | - `expanded`_ |
| | - `preferred_choices`_ |
+-------------+-----------------------------------------------------------------------------+
| Inherited | - ``required`` |
| options | - ``label`` |
| | - ``read_only`` |
| Inherited | - `required`_ |
| options | - `label`_ |
| | - `read_only`_ |
| | - `error_bubbling`_ |
+-------------+-----------------------------------------------------------------------------+
| Parent type | :doc:`form</reference/forms/types/form>` (if expanded), ``field`` otherwise |
+-------------+-----------------------------------------------------------------------------+
Expand Down Expand Up @@ -68,34 +68,38 @@ specify the choices for your widget.

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

Options
-------

* ``choices`` [type: array]
This is the most basic way to specify the choices that should be used
by this field. The ``choices`` option is an array, where the array key
is the item value and the array value is the item's label:

.. code-block:: php
$builder->add('gender', 'choice', array(
'choices' => array('m' => 'Male', 'f' => 'Female')
));
* ``choice_list`` [type: ``Symfony\Component\Form\ChoiceList\ChoiceListInterface``]
This is one way of specifying the options to be used for this field.
The ``choice_list`` option must be an instance of the ``ChoiceListInterface``.
For more advanced cases, a custom class that implements the interface
can be created to supply the choices.
Field Options
-------------

choices
~~~~~~~

**type**: ``array`` **default**: ``array()``

This is the most basic way to specify the choices that should be used
by this field. The ``choices`` option is an array, where the array key
is the item value and the array value is the item's label::

$builder->add('gender', 'choice', array(
'choices' => array('m' => 'Male', 'f' => 'Female')
));

choice_list
~~~~~~~~~~~

**type**: ``Symfony\Component\Form\ChoiceList\ChoiceListInterface``

This is one way of specifying the options to be used for this field.
The ``choice_list`` option must be an instance of the ``ChoiceListInterface``.
For more advanced cases, a custom class that implements the interface
can be created to supply the choices.

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

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

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

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

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

Expand All @@ -106,3 +110,5 @@ These options inherit from the :doc:`field</reference/forms/types/field>` type:
.. include:: /reference/forms/types/options/label.rst.inc

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

.. include:: /reference/forms/types/options/error_bubbling.rst.inc
14 changes: 7 additions & 7 deletions reference/forms/types/country.rst
View file
Expand Up @@ -22,13 +22,13 @@ you should just use the ``choice`` type directly.
+-------------+-----------------------------------------------------------------------+
| Rendered as | can be various tags (see :ref:`forms-reference-choice-tags`) |
+-------------+-----------------------------------------------------------------------+
| Inherited | - ``multiple`` |
| options | - ``expanded`` |
| | - ``preferred_choices`` |
| | - ``error_bubbling`` |
| | - ``required`` |
| | - ``label`` |
| | - ``read_only`` |
| Inherited | - `multiple`_ |
| options | - `expanded`_ |
| | - `preferred_choices`_ |
| | - `error_bubbling`_ |
| | - `required`_ |
| | - `label`_ |
| | - `read_only`_ |
+-------------+-----------------------------------------------------------------------+
| Parent type | :doc:`choice</reference/forms/types/choice>` |
+-------------+-----------------------------------------------------------------------+
Expand Down
30 changes: 15 additions & 15 deletions reference/forms/types/date.rst
View file
Expand Up @@ -8,26 +8,26 @@ A field that allows the user to modify date information via a variety of
different HTML elements.

The underlying data used for this field type can be a ``DateTime`` object,
a string, a timestamp or an array. As long as the ``input`` option is set
correctly, the field will take care of all of the details (see the ``input`` option).
a string, a timestamp or an array. As long as the ``input`_ option is set
correctly, the field will take care of all of the details.
The field can be rendered as a single text box or three select boxes (month,
day, and year).
The field can be rendered as a single text box, three text boxes (month,
day, and year) or three select boxes (see the `widget_` option).
+----------------------+-----------------------------------------------------------------------------+
| Underlying Data Type | can be ``DateTime``, string, timestamp, or array (see the ``input`` option) |
+----------------------+-----------------------------------------------------------------------------+
| Rendered as | single text box or three select fields |
+----------------------+-----------------------------------------------------------------------------+
| Options | - ``widget`` |
| | - ``input`` |
| | - ``years`` |
| | - ``months`` |
| | - ``days`` |
| | - ``format`` |
| | - ``pattern`` |
| | - ``data_timezone`` |
| | - ``user_timezone`` |
| Options | - `widget`_ |
| | - `input`_ |
| | - `years`_ |
| | - `months`_ |
| | - `days`_ |
| | - `format`_ |
| | - `pattern`_ |
| | - `data_timezone`_ |
| | - `user_timezone`_ |
+----------------------+-----------------------------------------------------------------------------+
| Parent type | ``field`` (if text), ``form`` otherwise |
+----------------------+-----------------------------------------------------------------------------+
Expand Down Expand Up @@ -65,8 +65,8 @@ you'd need to set ``input`` to ``timestamp``:
The field also supports an ``array`` and ``string`` as valid ``input`` option
values.

Options
-------
Field Options
-------------

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

Expand Down

0 comments on commit 906e345

Please sign in to comment.