Add allow empty option for @selectize/selectize (#2817)

goosys · web-flow · commit 4999befd259f · 2025-11-27T15:16:06.000Z
This does several things in one go, because they can't be done indepentantly: 1. Upgrades `@selectize/selectize` from v0.12 to v0.15, 2. Fixes #2545 (Selectize removes blank options from selects) 3. Closes #2790 (Add allow empty option) Updating Selectize improved the visibility of empty options without requiring custom CSS. However, due to compatibility issues between Selectize, Rails, and Stimulus/Turbo, this ended up being a larger change than expected. Right after upgrading to @selectize/selectize, forms started hanging. To address this, workaround is used. This issue is likely not limited to Selectize. It seems that every time we use a JS library, we’ll need to implement a teardown() function to avoid similar problems. Switching from disconnect() to teardown() also prevents a regression of #2811. To prevent unintended removal when using `include_blank: false`, we also introduce a workaround to prevent unintended deletions. Finally, when updating a form with include_blank and navigating back via Turbo, the placeholder would display only its first character. A full page reload would render it correctly. To workaround this problem, we use a placeholder of `---` instead of a meaningful string so that it doesn't look wrong. #2545 #2790 hotwired/stimulus#104 (comment) #2811 selectize/selectize.js#1498 Updated selectize from 0.12 to @selectize/selectize 0.15 Used teardown instead of disconnect to address reinitialization issues Refactor select for @selectize/selectize
diff --git a/app/assets/builds/administrate/application.css b/app/assets/builds/administrate/application.css
diff --git a/app/assets/builds/administrate/application.css.map b/app/assets/builds/administrate/application.css.map
diff --git a/app/assets/builds/administrate/application.js b/app/assets/builds/administrate/application.js
diff --git a/app/assets/builds/administrate/application.js.map b/app/assets/builds/administrate/application.js.map
diff --git a/app/assets/javascripts/administrate/application.js b/app/assets/javascripts/administrate/application.js
@@ -3,7 +3,7 @@ import "trix";
 import "@rails/actiontext";
 
 import "@hotwired/turbo-rails";
-import "selectize/dist/js/selectize.min.js";
+import "@selectize/selectize/dist/js/selectize.min.js";
 
 import "./controllers";
 import "./vendor/css-anchor-positioning";
diff --git a/app/assets/javascripts/administrate/controllers/application.js b/app/assets/javascripts/administrate/controllers/application.js
@@ -6,4 +6,14 @@ const application = Application.start();
 application.debug = false;
 window.Stimulus   = application;
 
+// Workaround for Stimulus controllers not being properly disconnected
+// https://github.com/hotwired/stimulus/issues/104#issuecomment-365393601
+document.addEventListener('turbo:before-cache', function() {
+  application.controllers.forEach(function(controller){
+    if(typeof controller.teardown === 'function') {
+      controller.teardown();
+    }
+  });
+});
+
 export { application };
diff --git a/app/assets/javascripts/administrate/controllers/select_controller.js b/app/assets/javascripts/administrate/controllers/select_controller.js
@@ -1,17 +1,29 @@
 import { Controller } from "@hotwired/stimulus";
 import $ from "jquery";
 
+const default_options = {
+  allowEmptyOption: true,
+  deselectBehavior: 'previous'
+}
+
 export default class extends Controller {
   connect() {
     if (!this.selectize) {
-      const options = this.selectizeOptions || {};
+      const options = this.selectizeOptions || default_options;
       const selectedValues = $(this.element).val();
       this.selectize = $(this.element).selectize(options)[0].selectize;
       this.selectize.setValue(selectedValues);
+      if (this.element.getAttribute('data-selectize-required') === 'true') {
+        this.selectize.on('change', (value) => {
+          if (value.length === 0) {
+            this.selectize.setValue(selectedValues);
+          }
+        });
+      }
     }
   }
 
-  disconnect() {
+  teardown() {
     if (this.selectize) {
       const selectedValues = this.selectize.getValue();
       if (!this.selectizeOptions) {
diff --git a/app/assets/stylesheets/administrate/application.scss b/app/assets/stylesheets/administrate/application.scss
@@ -3,8 +3,8 @@
 @import "reset/normalize";
 
 @import "trix/dist/trix";
-@import "selectize/dist/css/selectize";
-@import "selectize/dist/css/selectize.default";
+@import "@selectize/selectize/dist/css/selectize";
+@import "@selectize/selectize/dist/css/selectize.default";
 
 @import "library/clearfix";
 @import "library/data-label";
diff --git a/app/views/fields/belongs_to/_form.html.erb b/app/views/fields/belongs_to/_form.html.erb
@@ -22,6 +22,6 @@ that displays all possible records to associate with.
 <div class="field-unit__field">
   <%= f.select(field.permitted_attribute,
                options_for_select(field.associated_resource_options, field.selected_option),
-               {include_blank: field.include_blank_option},
-               data: {controller: field.html_controller}) %>
+               field.tag_options,
+               field.html_options) %>
 </div>
diff --git a/app/views/fields/select/_form.html.erb b/app/views/fields/select/_form.html.erb
@@ -26,8 +26,8 @@ to be displayed on a resource's edit form page.
         field.selectable_options,
         field.data,
       ),
-      {include_blank: field.include_blank_option},
-      data: {controller: field.html_controller}
+      field.tag_options,
+      field.html_options
     )
   %>
 </div>
diff --git a/lib/administrate/field/belongs_to.rb b/lib/administrate/field/belongs_to.rb
@@ -29,10 +29,45 @@ def selected_option
         data&.send(association_primary_key)
       end
 
+      def tag_options
+        {include_blank: selectize_include_blank}
+      end
+
+      def html_options
+        {
+          placeholder: selectize_placeholder,
+          data: {
+            controller: html_controller,
+            **selectize_required_options
+          }
+        }
+      end
+
       def include_blank_option
         options.fetch(:include_blank, true)
       end
 
+      def selectize_include_blank
+        if include_blank_option === true
+          # I18n.t(:"helpers.select.prompt")
+          "---" # Workaround for https://github.com/selectize/selectize.js/issues/1498
+        elsif include_blank_option.is_a?(::String)
+          include_blank_option
+        end
+      end
+
+      def selectize_placeholder
+        selectize_include_blank
+      end
+
+      def selectize_required_options
+        if include_blank_option === false
+          {"selectize-required": true}
+        else
+          {}
+        end
+      end
+
       private
 
       def candidate_resources
diff --git a/lib/administrate/field/select.rb b/lib/administrate/field/select.rb
@@ -24,10 +24,45 @@ def selectable_options
         values
       end
 
+      def tag_options
+        {include_blank: selectize_include_blank}
+      end
+
+      def html_options
+        {
+          placeholder: selectize_placeholder,
+          data: {
+            controller: html_controller,
+            **selectize_required_options
+          }
+        }
+      end
+
       def include_blank_option
         options.fetch(:include_blank, false)
       end
 
+      def selectize_include_blank
+        if include_blank_option === true
+          # I18n.t(:"helpers.select.prompt")
+          "---" # Workaround for https://github.com/selectize/selectize.js/issues/1498
+        elsif include_blank_option.is_a?(::String)
+          include_blank_option
+        end
+      end
+
+      def selectize_placeholder
+        selectize_include_blank
+      end
+
+      def selectize_required_options
+        if include_blank_option === false
+          {"selectize-required": true}
+        else
+          {}
+        end
+      end
+
       def active_record_enum?
         resource.class.defined_enums.key?(attribute.to_s)
       end
diff --git a/package.json b/package.json
@@ -8,10 +8,10 @@
     "@hotwired/stimulus": "^3.2.2",
     "@hotwired/turbo-rails": "^8.0.0",
     "@rails/actiontext": "^8.0.0",
+    "@selectize/selectize": "^0.15.2",
     "esbuild": "^0.25.0",
     "jquery": "^3.7.0",
     "sass": "^1.63.6",
-    "selectize": "^0.12.6",
     "trix": "^2.1.15"
   },
   "devDependencies": {
diff --git a/spec/administrate/views/fields/select/_edit_spec.rb b/spec/administrate/views/fields/select/_edit_spec.rb
@@ -9,8 +9,8 @@
       attribute: :email_subscriber,
       data: false,
       selectable_options: [true, false, nil],
-      include_blank_option: false,
-      html_controller: "select"
+      tag_options: {include_blank: false},
+      html_options: {data: {controller: "select"}}
     )
 
     fields model: customer do |f|
@@ -33,8 +33,8 @@
       attribute: :email_subscriber,
       data: "Yes",
       selectable_options: ["Yes", "No"],
-      include_blank_option: "Unknown",
-      html_controller: "select"
+      tag_options: {include_blank: "Unknown"},
+      html_options: {data: {controller: "select"}}
     )
 
     fields model: customer do |f|
diff --git a/spec/lib/fields/belongs_to_spec.rb b/spec/lib/fields/belongs_to_spec.rb
@@ -167,6 +167,72 @@
         expect(candidates).to eq([])
       end
     end
+
+    context "when given an include_blank option is true" do
+      it "returns include_blank and placeholder options with '---'" do
+        customer = create(:customer, territory: nil)
+        association = Administrate::Field::BelongsTo.with_options(
+          include_blank: true
+        )
+        field = association.new(
+          :territory,
+          [],
+          :edit,
+          resource: customer
+        )
+
+        tag_options = field.tag_options
+        html_options = field.html_options
+
+        expect(tag_options[:include_blank]).to eq("---")
+        expect(html_options[:placeholder]).to eq("---")
+        expect(html_options.dig(:data, :"selectize-required")).to be_nil
+      end
+    end
+
+    context "when given an include_blank option is a string" do
+      it "returns include_blank and placeholder options with the given string" do
+        customer = create(:customer, territory: nil)
+        association = Administrate::Field::BelongsTo.with_options(
+          include_blank: "Select an option"
+        )
+        field = association.new(
+          :territory,
+          [],
+          :edit,
+          resource: customer
+        )
+
+        tag_options = field.tag_options
+        html_options = field.html_options
+
+        expect(tag_options[:include_blank]).to eq("Select an option")
+        expect(html_options[:placeholder]).to eq("Select an option")
+        expect(html_options.dig(:data, :"selectize-required")).to be_nil
+      end
+    end
+
+    context "when given an include_blank option is false" do
+      it "returns include_blank and placeholder options with nil" do
+        customer = create(:customer, territory: nil)
+        association = Administrate::Field::BelongsTo.with_options(
+          include_blank: false
+        )
+        field = association.new(
+          :territory,
+          [],
+          :edit,
+          resource: customer
+        )
+
+        tag_options = field.tag_options
+        html_options = field.html_options
+
+        expect(tag_options[:include_blank]).to eq(nil)
+        expect(html_options[:placeholder]).to eq(nil)
+        expect(html_options.dig(:data, :"selectize-required")).to eq(true)
+      end
+    end
   end
 
   describe "#associated_resource_options" do
diff --git a/spec/lib/fields/select_spec.rb b/spec/lib/fields/select_spec.rb
@@ -140,4 +140,66 @@
       expect(field.selectable_options).to eq([])
     end
   end
+
+  describe ":include_blank option" do
+    context "when given an include_blank option is true" do
+      it "returns include_blank and placeholder options with '---'" do
+        customer = create(:customer)
+        field = described_class.new(
+          :email_subscriber,
+          "yes",
+          :_page_,
+          resource: customer,
+          include_blank: true
+        )
+
+        tag_options = field.tag_options
+        html_options = field.html_options
+
+        expect(tag_options[:include_blank]).to eq("---")
+        expect(html_options[:placeholder]).to eq("---")
+        expect(html_options.dig(:data, :"selectize-required")).to be_nil
+      end
+    end
+
+    context "when given an include_blank option is a string" do
+      it "returns include_blank and placeholder options with the given string" do
+        customer = create(:customer)
+        field = described_class.new(
+          :email_subscriber,
+          "yes",
+          :_page_,
+          resource: customer,
+          include_blank: "Select an option"
+        )
+
+        tag_options = field.tag_options
+        html_options = field.html_options
+
+        expect(tag_options[:include_blank]).to eq("Select an option")
+        expect(html_options[:placeholder]).to eq("Select an option")
+        expect(html_options.dig(:data, :"selectize-required")).to be_nil
+      end
+    end
+
+    context "when given an include_blank option is false" do
+      it "returns include_blank and placeholder options with nil" do
+        customer = create(:customer)
+        field = described_class.new(
+          :email_subscriber,
+          "yes",
+          :_page_,
+          resource: customer,
+          include_blank: false
+        )
+
+        tag_options = field.tag_options
+        html_options = field.html_options
+
+        expect(tag_options[:include_blank]).to be_nil
+        expect(html_options[:placeholder]).to be_nil
+        expect(html_options.dig(:data, :"selectize-required")).to eq(true)
+      end
+    end
+  end
 end
diff --git a/yarn.lock b/yarn.lock
