From 31abf2d84ca5aea2864f5ca8cd265b1f50af01f9 Mon Sep 17 00:00:00 2001
From: Ryan Weaver <ryan@thatsquality.com>
Date: Sun, 8 May 2016 17:20:46 -0400
Subject: [PATCH] EntityType: query_builder link to usage

---
 reference/forms/types/entity.rst | 48 +++++++++++++++++++-------------
 1 file changed, 29 insertions(+), 19 deletions(-)

diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
index 5c1f68b8a2a..fa7bba98bde 100644
--- a/reference/forms/types/entity.rst
+++ b/reference/forms/types/entity.rst
@@ -54,32 +54,40 @@ 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:
@@ -87,14 +95,15 @@ the ``query_builder`` option. The easiest way to use the option is as follows::
 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
 ------------------