extensions.rst 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128
  1. Extensions
  2. ==========
  3. Admin extensions allow you to add or change features of one or more Admin instances. To create an extension your class
  4. must implement the interface ``Sonata\AdminBundle\Admin\AdminExtensionInterface`` and be registered as a service. The
  5. interface defines a number of functions which you can use to customize the edit form, list view, form validation,
  6. alter newly created objects and other admin features.
  7. .. code-block:: php
  8. use Sonata\AdminBundle\Admin\AbstractAdminExtension;
  9. use Sonata\AdminBundle\Form\FormMapper;
  10. class PublishStatusAdminExtension extends AbstractAdminExtension
  11. {
  12. public function configureFormFields(FormMapper $formMapper)
  13. {
  14. $formMapper
  15. ->add('status', 'choice', array(
  16. 'choices' => array(
  17. 'draft' => 'Draft',
  18. 'published' => 'Published',
  19. ),
  20. ))
  21. ;
  22. }
  23. }
  24. Configuration
  25. ~~~~~~~~~~~~~
  26. There are two ways to configure your extensions and connect them to an admin.
  27. You can include this information in the service definition of your extension.
  28. Add the tag *sonata.admin.extension* and use the *target* attribute to point to
  29. the admin you want to modify. Please note you can specify as many tags you want.
  30. Set the *global* attribute to *true* and the extension will be added to all admins.
  31. The *priority* attribute is *0* by default and can be a positive or negative integer.
  32. The higher the priority, the earlier it's executed.
  33. .. configuration-block::
  34. .. code-block:: yaml
  35. services:
  36. app.publish.extension:
  37. class: AppBundle\Admin\Extension\PublishStatusAdminExtension
  38. tags:
  39. - { name: sonata.admin.extension, target: app.admin.article }
  40. - { name: sonata.admin.extension, target: app.admin.blog }
  41. app.order.extension:
  42. class: AppBundle\Admin\Extension\OrderAdminExtension
  43. tags:
  44. - { name: sonata.admin.extension, global: true }
  45. app.important.extension:
  46. class: AppBundle\Admin\Extension\ImportantAdminExtension
  47. tags:
  48. - { name: sonata.admin.extension, priority: 5 }
  49. The second option is to add it to your config.yml file.
  50. .. configuration-block::
  51. .. code-block:: yaml
  52. # app/config/config.yml
  53. sonata_admin:
  54. extensions:
  55. app.publish.extension:
  56. admins:
  57. - app.admin.article
  58. Using the ``config.yml`` file has some advantages, it allows you to keep your configuration centralized and it provides some
  59. extra options you can use to wire your extensions in a more dynamic way. This means you can change the behaviour of all
  60. admins that manage a class of a specific type.
  61. admins:
  62. specify one or more admin service ids to which the Extension should be added
  63. excludes:
  64. specify one or more admin service ids to which the Extension should not be added (this will prevent it matching
  65. any of the other settings)
  66. extends:
  67. specify one or more classes. If the managed class of an admin extends one of the specified classes the extension
  68. will be added to that admin.
  69. implements:
  70. specify one or more interfaces. If the managed class of an admin implements one of the specified interfaces the
  71. extension will be added to that admin.
  72. instanceof:
  73. specify one or more classes. If the managed class of an admin extends one of the specified classes or is an instance
  74. of that class the extension will be added to that admin.
  75. uses:
  76. Requires PHP >= 5.4.0. Specify one or more traits. If the managed class of an admin uses one of the specified traits the extension will be
  77. added to that admin.
  78. priority:
  79. Can be a positive or negative integer. The higher the priority, the earlier it’s executed.
  80. .. configuration-block::
  81. .. code-block:: yaml
  82. # app/config/config.yml
  83. sonata_admin:
  84. extensions:
  85. app.publish.extension:
  86. admins:
  87. - app.admin.article
  88. implements:
  89. - AppBundle\Publish\PublishStatusInterface
  90. excludes:
  91. - app.admin.blog
  92. - app.admin.news
  93. extends:
  94. - AppBundle\Document\Blog
  95. instanceof:
  96. - AppBundle\Document\Page
  97. uses:
  98. - AppBundle\Trait\Timestampable