feature symfony#7219 Add documentation for CallbackChoiceLoader (sawmurai, javiereguiluz)

xabbuh · xabbuh · commit dc8c0f3d60b0 · 2017-03-03T08:24:03.000+01:00
This PR was merged into the 3.2 branch. Discussion ---------- Add documentation for CallbackChoiceLoader PR for symfony#7181 Commits ------- 5838635 Make lines shorter to comply with 80-char limit 731617f Clearify behaviour of CallbackChoiceLoader e5e9a5d Add documentation for CallbackChoiceLoader
diff --git a/reference/forms/types/choice.rst b/reference/forms/types/choice.rst
@@ -184,6 +184,27 @@ The ``choice_loader`` can be used to only partially load the choices in cases wh
 a fully-loaded list is not necessary. This is only needed in advanced cases and
 would replace the ``choices`` option.
 
+You can use an instance of :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\CallbackChoiceLoader` 
+if you want to take advantage of lazy loading::
+
+    use Symfony\Component\Form\ChoiceList\Loader\CallbackChoiceLoader;
+    use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
+    // ...
+
+    $builder->add('constants', ChoiceType::class, array(
+        'choice_loader' => new CallbackChoiceLoader(function() {
+            return StaticClass::getConstants();
+        },
+    ));
+
+This will cause the call of ``StaticClass::getConstants()`` to not happen if the
+request is redirected and if there is no pre set or submitted data. Otherwise
+the choice options would need to be resolved thus triggering the callback.
+
+.. versionadded:: 3.2
+    The ability to use an instance of :class:`Symfony\\Component\\Form\\ChoiceList\\Loader\\CallbackChoiceLoader` 
+    was introduced in Symfony 3.2
+
 .. include:: /reference/forms/types/options/choice_name.rst.inc
 
 .. include:: /reference/forms/types/options/choice_translation_domain.rst.inc
