action_create_edit.rst 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209
  1. Creating and Editing objects
  2. ============================
  3. .. note::
  4. This document is a stub representing a new work in progress. If you're reading
  5. this you can help contribute, **no matter what your experience level with Sonata
  6. is**. Check out the `issues on Github`_ for more information about how to get involved.
  7. This document will cover the Create and Edit actions. It will cover configuration
  8. of the fields and forms available in these views and any other relevant settings.
  9. Basic configuration
  10. -------------------
  11. SonataAdmin Options that may affect the create or edit view:
  12. .. code-block:: yaml
  13. sonata_admin:
  14. options:
  15. html5_validate: true # enable or disable html5 form validation
  16. confirm_exit: true # enable or disable a confirmation before navigating away
  17. use_select2: true # enable or disable usage of the Select2 jQuery library
  18. use_icheck: true # enable or disable usage of the iCheck library
  19. use_bootlint: false # enable or disable usage of Bootlint
  20. use_stickyforms: true # enable or disable the floating buttons
  21. form_type: standard # can also be 'horizontal'
  22. templates:
  23. edit: SonataAdminBundle:CRUD:edit.html.twig
  24. tab_menu_template: SonataAdminBundle:Core:tab_menu_template.html.twig
  25. For more information about optional libraries:
  26. - Select2: https://github.com/select2/select2
  27. - iCheck: http://icheck.fronteed.com/
  28. - Bootlint: https://github.com/twbs/bootlint#in-the-browser
  29. .. note::
  30. **TODO**:
  31. * options available when adding fields, inc custom templates
  32. Routes
  33. ~~~~~~
  34. You can disable creating or editing entities by removing the corresponding routes in your Admin.
  35. For more detailed information about routes, see :doc:`routing`.
  36. .. code-block:: php
  37. <?php
  38. // src/AppBundle/Admin/PersonAdmin.php
  39. class PersonAdmin extends AbstractAdmin
  40. {
  41. // ...
  42. protected function configureRoutes(RouteCollection $collection): void
  43. {
  44. /* Removing the edit route will disable editing entities. It will also
  45. * use the 'show' view as default link on the identifier columns in the list view.
  46. */
  47. $collection->remove('edit');
  48. /* Removing the create route will disable creating new entities. It will also
  49. * remove the 'Add new' button in the list view.
  50. */
  51. $collection->remove('create');
  52. }
  53. // ...
  54. }
  55. Adding form fields
  56. ------------------
  57. Within the configureFormFields method you can define which fields should
  58. be shown when editing or creating entities.
  59. Each field has to be added to a specific form group. And form groups can
  60. optionally be added to a tab. See `FormGroup options`_ for additional
  61. information about configuring form groups.
  62. Using the FormMapper add method, you can add form fields. The add method
  63. has 4 parameters:
  64. - ``name``: The name of your entity.
  65. - ``type``: The type of field to show; by defaults this is ``null`` to let
  66. Sonata decide which type to use. See :doc:`Field Types <field_types>`
  67. for more information on available types.
  68. - ``options``: The form options to be used for the field. These may differ
  69. per type. See :doc:`Field Types <field_types>` for more information on
  70. available options.
  71. - ``fieldDescriptionOptions``: The field description options. Options here
  72. are passed through to the field template. See :ref:`Form Types, FieldDescription
  73. options <form_types_fielddescription_options>` for more information.
  74. .. note::
  75. The property entered in ``name`` should be available in your Entity
  76. through getters/setters or public access.
  77. .. code-block:: php
  78. <?php
  79. // src/AppBundle/Admin/PersonAdmin.php
  80. class PersonAdmin extends AbstractAdmin
  81. {
  82. // ...
  83. protected function configureFormFields(FormMapper $formMapper): void
  84. {
  85. $formMapper
  86. ->tab('General') // The tab call is optional
  87. ->with('Addresses')
  88. ->add('title') // Add a field and let Sonata decide which type to use
  89. ->add('streetname', TextType::class) // Add a textfield
  90. ->add('housenumber', NumberType::class) // Add a number field
  91. ->add('housenumberAddition', TextType::class, ['required' => false]) // Add a non-required text field
  92. ->end() // End form group
  93. ->end() // End tab
  94. ;
  95. }
  96. // ...
  97. }
  98. FormGroup options
  99. ~~~~~~~~~~~~~~~~~
  100. When adding a form group to your edit/create form, you may specify some
  101. options for the group itself.
  102. - ``collapsed``: unused at the moment
  103. - ``class``: The class for your form group in the admin; by default, the
  104. value is set to ``col-md-12``.
  105. - ``fields``: The fields in your form group (you should NOT override this
  106. unless you know what you're doing).
  107. - ``box_class``: The class for your form group box in the admin; by default,
  108. the value is set to ``box box-primary``.
  109. - ``description``: A text shown at the top of the form group.
  110. - ``translation_domain``: The translation domain for the form group title
  111. (the Admin translation domain is used by default).
  112. To specify options, do as follows:
  113. .. code-block:: php
  114. <?php
  115. // src/AppBundle/Admin/PersonAdmin.php
  116. class PersonAdmin extends AbstractAdmin
  117. {
  118. // ...
  119. public function configureFormFields(FormMapper $formMapper): void
  120. {
  121. $formMapper
  122. ->tab('General') // the tab call is optional
  123. ->with('Addresses', [
  124. 'class' => 'col-md-8',
  125. 'box_class' => 'box box-solid box-danger',
  126. 'description' => 'Lorem ipsum',
  127. // ...
  128. ])
  129. ->add('title')
  130. // ...
  131. ->end()
  132. ->end()
  133. ;
  134. }
  135. // ...
  136. }
  137. Here is an example of what you can do with customizing the box_class on
  138. a group:
  139. .. figure:: ../images/box_class.png
  140. :align: center
  141. :alt: Box Class
  142. :width: 500
  143. Embedding other Admins
  144. ----------------------
  145. .. note::
  146. **TODO**:
  147. * how to embed one Admin in another (1:1, 1:M, M:M)
  148. * how to access the right object(s) from the embedded Admin's code
  149. Customizing just one of the actions
  150. -----------------------------------
  151. .. note::
  152. **TODO**:
  153. * how to create settings/fields that appear on just one of the create/edit views
  154. * and any controller changes needed to manage them
  155. .. _`issues on GitHub`: https://github.com/sonata-project/SonataAdminBundle/issues/1519