Merge pull request #1898 from pulzarraider/select2_improve_configuration

Improve select2 configuration

Resources/doc/index.rst

@@ -24,6 +24,7 @@ Reference Guide
    reference/architecture
    reference/dashboard
    reference/search
+   reference/select2
    reference/routing
    reference/action_list
    reference/action_create_edit

Resources/doc/reference/configuration.rst

@@ -1,7 +1,7 @@
 Warning: this doc page is not up to date and will be removed soon.
 ==================================================================
 
-This page will be removed soon, as it's content is being improved and moved to 
+This page will be removed soon, as it's content is being improved and moved to
 other pages of the documentation. Please refer to each section's documentation for up-to-date
 information on SonataAdminBundle configuration options.
 
@@ -31,6 +31,7 @@ Full Configuration Options
             options:
                 html5_validate: false # does not use html5 validation
                 confirm_exit:   false # disable confirmation when quitting with unsaved changes
+                use_select2:    false # disable select2
                 pager_links:    5     # pager max links to display
 
             # set to true to persist filter settings per admin module in the user's session

Resources/doc/reference/select2.rst

@@ -0,0 +1,52 @@
+Select2
+=======
+
+The admin comes with `select2 <http://ivaynberg.github.io/select2/>` integration
+since version 2.2.6. Select2 is a jQuery based replacement for select boxes.
+It supports searching, remote data sets, and infinite scrolling of results.
+
+The select2 is enabled on all ``select`` form elements by default.
+
+Disable select2
+---------------
+
+If you don't want to use select2 in your admin, you can disable it in config.yml.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        sonata_admin:
+            options:
+                use_select2:    false # disable select2
+
+.. note::
+    If you disable select2, autocomplete form types will stop working.
+
+Disable select2 on some form elements
+-------------------------------------
+
+To disable select2 on some ``select`` form element, set data attribute ``data-sonata-select2="false"`` to this form element.
+
+.. code-block:: php
+
+    ->add('category', 'sonata_type_model',
+        array(
+            'attr'=>array('data-sonata-select2'=>'false')
+        )
+    )
+
+AllowClear
+----------
+
+Select2 parameter ``allowClear`` is handled automatically by admin. But if you want
+to overload the default functionality, you can set data attribute ``data-sonata-select2-allow-clear="true"``
+to enable ``allowClear`` or ``data-sonata-select2-allow-clear="false"`` to disable ``allowClear`` parameter.
+
+.. code-block:: php
+
+    ->add('category', 'sonata_type_model',
+        array(
+            'attr'=>array('data-sonata-select2-allow-clear'=>'false')
+        )
+    )

Resources/public/base.js

@@ -23,13 +23,25 @@ var Admin = {
 
     setup_select2: function(subject) {
         if (window.SONATA_CONFIG && window.SONATA_CONFIG.USE_SELECT2 && window.Select2) {
-            jQuery('select', subject).each(function() {
+            jQuery('select:not([data-sonata-select2="false"])', subject).each(function() {
                 var select = $(this);
 
+                var allowClearEnabled = false;
+
+                if (select.find('option[value=""]').length) {
+                    allowClearEnabled = true;
+                }
+
+                if (select.attr('data-sonata-select2-allow-clear')==='true') {
+                    allowClearEnabled = true;
+                } else if (select.attr('data-sonata-select2-allow-clear')==='false') {
+                    allowClearEnabled = false;
+                }
+
                 select.select2({
                     width: 'resolve',
                     minimumResultsForSearch: 10,
-                    allowClear: select.find('option[value=""]').length ? true : false
+                    allowClear: allowClearEnabled
                 });
 
                 var popover = select.data('popover');