minor #6553 EntityType: query_builder link to usage (weaverryan)

xabbuh · xabbuh · commit 53accc0bd58f · 2016-05-19T22:11:47.000+02:00
This PR was squashed before being merged into the 2.3 branch (closes #6553). Discussion ---------- EntityType: query_builder link to usage | Q | A | ------------- | --- | Doc fix? | yes-ish | New docs? | no | Applies to | 2.3+ | Fixed tickets | n/a I noticed that when you go to the query_builder option, we didn't link back up to the example where it's shown. Then, I made a few other changes, including adding more info in code blocks, and a little less in writing. Commits ------- 31abf2d EntityType: query_builder link to usage
diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
@@ -54,47 +54,56 @@ The ``entity`` type has just one required option: the entity which should
 be listed inside the choice field::
 
     $builder->add('users', 'entity', array(
-        'class' => 'AcmeHelloBundle:User',
+        // query choices from this entity
+        'class' => 'AppBundle:User',
+
+        // use the User.username property as the visible option string
         'property' => 'username',
+
+        // used to render a select box, check boxes or radios
+        // 'multiple' => true,
+        // 'expanded' => true,
     ));
 
-In this case, all ``User`` objects will be loaded from the database and
-rendered as either a ``select`` tag, a set or radio buttons or a series
-of checkboxes (this depends on the ``multiple`` and ``expanded`` values).
-If the entity object does not have a ``__toString()`` method the ``property``
-option is needed.
+This will build a ``select`` drop-down containing *all* of the ``User`` objects
+in the database. To render radio buttons or checkboxes instead, change the
+`multiple`_ and `expanded`_ options.
+
+.. _ref-form-entity-query-builder:
 
 Using a Custom Query for the Entities
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you need to specify a custom query to use when fetching the entities
+If you want to create a custom query to use when fetching the entities
 (e.g. you only want to return some entities, or need to order them), use
-the ``query_builder`` option. The easiest way to use the option is as follows::
+the `query_builder`_ option::
 
     use Doctrine\ORM\EntityRepository;
     // ...
 
     $builder->add('users', 'entity', array(
-        'class' => 'AcmeHelloBundle:User',
+        'class' => 'AppBundle:User',
         'query_builder' => function (EntityRepository $er) {
             return $er->createQueryBuilder('u')
                 ->orderBy('u.username', 'ASC');
         },
+        'property' => 'username',
     ));
 
 .. _reference-forms-entity-choices:
 
 Using Choices
 ~~~~~~~~~~~~~
 
-If you already have the exact collection of entities that you want included
-in the choice element, you can simply pass them via the ``choices`` key.
+If you already have the exact collection of entities that you want to include
+in the choice element, just pass them via the ``choices`` key.
+
 For example, if you have a ``$group`` variable (passed into your form perhaps
 as a form option) and ``getUsers`` returns a collection of ``User`` entities,
 then you can supply the ``choices`` option directly::
 
     $builder->add('users', 'entity', array(
-        'class' => 'AcmeHelloBundle:User',
+        'class' => 'AppBundle:User',
         'choices' => $group->getUsers(),
     ));
 
@@ -108,8 +117,8 @@ class
 
 **type**: ``string`` **required**
 
-The class of your entity (e.g. ``AcmeStoreBundle:Category``). This can be
-a fully-qualified class name (e.g. ``Acme\StoreBundle\Entity\Category``)
+The class of your entity (e.g. ``AppBundle:Category``). This can be
+a fully-qualified class name (e.g. ``AppBundle\Entity\Category``)
 or the short alias name (as shown prior).
 
 em
@@ -159,11 +168,12 @@ query_builder
 
 **type**: ``Doctrine\ORM\QueryBuilder`` or a Closure
 
-If specified, this is used to query the subset of options (and their
-order) that should be used for the field. The value of this option can
-either be a ``QueryBuilder`` object or a Closure. If using a Closure,
-it should take a single argument, which is the ``EntityRepository`` of
-the entity and return an instance of ``QueryBuilder``.
+Allows you to create a custom query for your choices. See
+:ref:`ref-form-entity-query-builder` for an example.
+
+The value of this option can either be a ``QueryBuilder`` object or a Closure.
+When using a Closure, you will be passed the ``EntityRepository`` of the entity
+as the only argument and should return a ``QueryBuilder``.
 
 Overridden Options
 ------------------
