Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add documentation to autocomplete JS
Matthew Kennedy717b01cae0d7
diff --git a/backend/app/assets/javascripts/spree/backend/global/select2_autocomplete.es6 b/backend/app/assets/javascripts/spree/backend/global/select2_autocomplete.es6index 20026ddddf..db137c4f54 100644--- a/backend/app/assets/javascripts/spree/backend/global/select2_autocomplete.es6+++ b/backend/app/assets/javascripts/spree/backend/global/select2_autocomplete.es6@@ -1,16 +1,33 @@-// Allows you to use one autocomplete for several use cases with sensible defaults.+// SELECT2 AUTOCOMPLETE JS+// This JavaScript file allows Spree developers to set up Select2 autocomplete search+// using the API v2 by simply adding data attributes to the <select> DOM element.// REQUIRED ATTRIBUTES-// data-autocomplete-url-value="products_api_v2" <- gets appended to const url - Example: (taxons_api_v2).+// You must provide a URL for the API V2, use the format shown below.+// See the backend.js file for other API V2 URL's.+//+// data-autocomplete-url-value="products_api_v2"// OPTIONAL ATTRIBUTES-// data-autocomplete-clear-value="boolean" <- true or false allows select2 clear.-// data-autocomplete-multiple-value="boolean" <- true or false set multiple or single select-// data-autocomplete-return-attr-value="pretty_name" <- example shown returns taxon pretty_name-// data-autocomplete-min-input-value="4" <- set a minimum input for search, default is 3.-// data-autocomplete-search-query-value="name_or_master_sku_cont" <- custom search query.--// can also be called directly as javastript.+// These attributes have sensible defaults, you many not need to use them in many cases,+// but they do provide a powerful toolkit to refine your search when needed.+//+// data-autocomplete-placeholder-value="Seach Pages" <- Sets the placeholder | DEFAULT is: 'Search'+// data-autocomplete-clear-value="boolean" <- Allow select2 to be cleared | DEFAULT is: false (no clear button)+// data-autocomplete-multiple-value="boolean" <- Multiple or Single select | DEFAULT is: false (single)+// data-autocomplete-return-attr-value="pretty_name" <- Return Attribute. | DEFAULT is: 'name'+// data-autocomplete-min-input-value="4" <- Minimum input for search | DEFAULT is: 3+// data-autocomplete-search-query-value="title_i_cont" <- Custom search query | DEFAULT is: 'name_i_cont'+// data-autocomplete-custom-return-id-value="permalink" <- Return a custom attribute rather than the ID | DEFAULT: returns id+//+// SECOND HARD CODED FILTER - (OPTIONAL)+// Use a second hard coded search filter param and term if you require a little more curation+// than just all results returning, an example of this in use can be seen in the menu_item search for Pages,+// here we only want to retuen Pages that have linkable slugs, not homepages, and so we filter those using the+// data attributes shown below.+//+// data-autocomplete-additional-query-value="type_not_eq" <- Pass a second hard coded filter query value | DEFAULT: null (not used)+// data-autocomplete-additional-term-value="Spree::Cms::Pages::Homepage" <- Pass a second hard coded term | DEFAULT: null (not used)document.addEventListener('DOMContentLoaded', function() {const select2Autocompletes = document.querySelectorAll('select.select2autocomplete')@@ -29,16 +46,18 @@ function buildParamsFromDataAttrs (element) {return_attribute: element.dataset.autocompleteReturnAttrValue,minimum_input: element.dataset.autocompleteMinInputValue,search_query: element.dataset.autocompleteSearchQueryValue,+ custom_return_id: element.dataset.autocompleteCustomReturnIdValue,- // hard coded additional filter for those edge cases.+ // Hard coded additional filter for those edge cases.additional_query: element.dataset.autocompleteAdditionalQueryValue,additional_term: element.dataset.autocompleteAdditionalTermValue})}+// Can also be called directly as javastript.$.fn.select2Autocomplete = function(params) {// Required params- const apiUrl = params.apiUrl+ const apiUrl = params.apiUrl || null// Optional paramsconst select2placeHolder = params.placeholder || Spree.translations.search@@ -47,17 +66,26 @@ $.fn.select2Autocomplete = function(params) {const returnAttribute = params.return_attribute || 'name'const minimumInput = params.minimum_input || 3const searchQuery = params.search_query || 'name_i_cont'-+ const customReturnId = params.custom_return_id || nullconst additionalQuery = params.additional_query || nullconst additionalTerm = params.additional_term || nullfunction formatList(values) {- return values.map(function (obj) {- return {- id: obj.id,- text: obj.attributes[returnAttribute]- }- })+ if (customReturnId) {+ return values.map(function (obj) {+ return {+ id: obj.attributes[customReturnId],+ text: obj.attributes[returnAttribute]+ }+ })+ } else {+ return values.map(function (obj) {+ return {+ id: obj.id,+ text: obj.attributes[returnAttribute]+ }+ })+ }}this.select2({diff --git a/backend/app/views/spree/admin/cms_sections/types/_category_banner_square.html.erb b/backend/app/views/spree/admin/cms_sections/types/_category_banner_square.html.erbdeleted file mode 100644index 99e45b77b5..0000000000--- a/backend/app/views/spree/admin/cms_sections/types/_category_banner_square.html.erb+++ /dev/null@@ -1,53 +0,0 @@-<div class="row">- <div class="col-12 col-md-6">- <%= f.field_container :title, class: ['form-group'] do %>- <%= f.label :title, Spree.t(:title) %>- <%= f.text_field :title, class: 'form-control' %>- <%= f.error_message_on :title %>- <% end %>-- <%= f.field_container :upper_image, class: ['form-group'] do %>- <% if @cms_section.upper_image.attached? && @cms_section.upper_image.variable? %>- <%= image_tag main_app.url_for(@cms_section.upper_image.variant(resize: '244x104>')) %>- <% elsif @cms_section.upper_image.attached? && @cms_section.upper_image.image? %>- <%= image_tag main_app.url_for(@cms_section.upper_image) %>- <% end %>- <%= f.field_container :upper_image, class: ['form-group'] do %>- <%= f.label :upper_image, Spree.t(:upper_image) %><br>- <%= f.file_field :upper_image %>- <%= f.error_message_on :upper_image %>- <% end %>- <% end %>- </div>- <div class="col-12 col-md-6">- <%= f.field_container :subtitle, class: ['form-group'] do %>- <%= f.label :subtitle, Spree.t(:title) %>- <%= f.text_field :subtitle, class: 'form-control' %>- <%= f.error_message_on :subtitle %>- <% end %>-- <%= f.field_container :lower_image, class: ['form-group'] do %>- <% if @cms_section.lower_image.attached? && @cms_section.lower_image.variable? %>- <%= image_tag main_app.url_for(@cms_section.lower_image.variant(resize: '244x104>')) %>- <% elsif @cms_section.lower_image.attached? && @cms_section.lower_image.image? %>- <%= image_tag main_app.url_for(@cms_section.lower_image) %>- <% end %>- <%= f.field_container :lower_image, class: ['form-group'] do %>- <%= f.label :lower_image, Spree.t(:lower_image) %><br>- <%= f.file_field :lower_image %>- <%= f.error_message_on :lower_image %>- <% end %>- <% end %>- </div>- <div class="col-12"><hr></div>- <div class="col-12 col-md-6">- <%= f.field_container :linked_resource_type, class: ['form-group'] do %>- <%= f.label :linked_resource_type, Spree.t('admin.navigation.link_to') %>- <%= f.select(:linked_resource_type, @cms_section.links_to, {include_blank: false}, class: 'link_switcher') %>- <%= f.error_message_on :linked_resource_type %>- <% end %>- </div>- <div class="col-12 col-md-6">- <%= render "spree/admin/shared/link_fields", resource: @cms_section, f: f %>- </div>-</div>diff --git a/backend/app/views/spree/admin/cms_sections/types/_menu_category.html.erb b/backend/app/views/spree/admin/cms_sections/types/_menu_category.html.erbnew file mode 100644index 0000000000..c6b3810064--- /dev/null+++ b/backend/app/views/spree/admin/cms_sections/types/_menu_category.html.erb@@ -0,0 +1,52 @@+<div class="row">+ <div class="col-12 col-md-6">+ <%= f.field_container :title, class: ['form-group'] do %>+ <%= f.label :title, Spree.t(:title) %>+ <%= f.select :title,+ options_from_collection_for_select([@cms_section],+ :title, :title, @cms_section.title || nil),+ { include_blank: true },+ class: 'select2autocomplete',+ data: { autocomplete_placeholder_value: Spree.t('admin.navigation.seach_for_a_taxon'),+ autocomplete_clear_value: true,+ autocomplete_url_value: 'taxons_api_v2',+ autocomplete_return_attr_value: 'permalink',+ autocomplete_custom_return_id_value: 'permalink' } %>+ <%= f.error_message_on :title %>+ <% end %>+ </div>++ <div class="col-12 col-md-6">+ <%= f.field_container :subtitle, class: ['form-group'] do %>+ <%= f.label :subtitle, Spree.t(:subtitle) %>+ <%= f.select :subtitle,+ options_from_collection_for_select([@cms_section],+ :subtitle, :subtitle, @cms_section.subtitle || nil),+ { include_blank: true },+ class: 'select2autocomplete',+ data: { autocomplete_placeholder_value: Spree.t('admin.navigation.seach_for_a_taxon'),+ autocomplete_clear_value: true,+ autocomplete_url_value: 'taxons_api_v2',+ autocomplete_return_attr_value: 'permalink',+ autocomplete_custom_return_id_value: 'permalink' } %>+ <%= f.error_message_on :subtitle %>+ <% end %>+ </div>++ <div class="col-12 col-md-6">+ <%= f.field_container :button_text, class: ['form-group'] do %>+ <%= f.label :button_text, Spree.t(:button_text) %>+ <%= f.select :button_text,+ options_from_collection_for_select([@cms_section],+ :button_text, :button_text, @cms_section.button_text || nil),+ { include_blank: true },+ class: 'select2autocomplete',+ data: { autocomplete_placeholder_value: Spree.t('admin.navigation.seach_for_a_taxon'),+ autocomplete_clear_value: true,+ autocomplete_url_value: 'taxons_api_v2',+ autocomplete_return_attr_value: 'permalink',+ autocomplete_custom_return_id_value: 'permalink' } %>+ <%= f.error_message_on :button_text %>+ <% end %>+ </div>+</div>diff --git a/core/app/models/spree/cms/sections/category_banner_square.rb b/core/app/models/spree/cms/sections/category_banner_square.rbdeleted file mode 100644index 15ef1ad09b..0000000000--- a/core/app/models/spree/cms/sections/category_banner_square.rb+++ /dev/null@@ -1,23 +0,0 @@-module Spree::Cms::Sections- class CategoryBannerSquare < Spree::CmsSection- after_initialize :default_values-- has_one_attached :upper_image- has_one_attached :lower_image-- def links_to- ['Spree::Taxon', 'Spree::Product']- end-- def widths- ['Half']- end-- private-- def default_values- self.width ||= 'Half'- self.linked_resource_type ||= 'Spree::Taxon'- end- end-enddiff --git a/core/app/models/spree/cms/sections/menu_category.rb b/core/app/models/spree/cms/sections/menu_category.rbnew file mode 100644index 0000000000..2279832ae2--- /dev/null+++ b/core/app/models/spree/cms/sections/menu_category.rb@@ -0,0 +1,15 @@+module Spree::Cms::Sections+ class MenuCategory < Spree::CmsSection+ after_initialize :default_values++ def widths+ ['Full']+ end++ private++ def default_values+ self.width ||= 'Full'+ end+ end+enddiff --git a/core/app/models/spree/cms_section.rb b/core/app/models/spree/cms_section.rbindex 6a23af6bd0..1bb337c2e1 100644--- a/core/app/models/spree/cms_section.rb+++ b/core/app/models/spree/cms_section.rb@@ -13,8 +13,7 @@ module Spree'Spree::Cms::Sections::Promo','Spree::Cms::Sections::FeaturedArticle','Spree::Cms::Sections::Carousel',- 'Spree::Cms::Sections::CategoryBannerSquare',- 'Spree::Cms::Sections::CategoryBannerTall']+ 'Spree::Cms::Sections::MenuCategory']# Overide this per section typedef links_todiff --git a/frontend/app/controllers/spree/home_controller.rb b/frontend/app/controllers/spree/home_controller.rbindex 4f0a25bd3a..4050b60814 100644--- a/frontend/app/controllers/spree/home_controller.rb+++ b/frontend/app/controllers/spree/home_controller.rb@@ -13,6 +13,10 @@ module Spree@homepage = @cms_home_page@edit_mode = trueend++ if http_cache_enabled?+ fresh_when etag: store_etag, last_modified: store_last_modified, public: true+ endendprivatediff --git a/frontend/app/views/spree/shared/cms/sections/_category_banner_square.html.erb b/frontend/app/views/spree/shared/cms/sections/_category_banner_square.html.erbdeleted file mode 100644index 6b778fb69d..0000000000--- a/frontend/app/views/spree/shared/cms/sections/_category_banner_square.html.erb+++ /dev/null@@ -1 +0,0 @@-_spree_cms_sections_categorybannersquare.html.erbdiff --git a/frontend/app/views/spree/shared/cms/sections/_menu_category.html.erb b/frontend/app/views/spree/shared/cms/sections/_menu_category.html.erbnew file mode 100644index 0000000000..a541714115--- /dev/null+++ b/frontend/app/views/spree/shared/cms/sections/_menu_category.html.erb@@ -0,0 +1,35 @@+<div class="col-6">+ <%= link_to spree.nested_taxons_path(section.title), class: "homepage-taxon-box mb-3" do %>+ <img class="w-100 lazyload"+ data-src="<%= asset_path('homepage/category_banner_upper.jpg') %>"+ data-srcset="<%= image_source_set('homepage/category_banner_upper') %>"+ alt="<%= section.title %>">++ <div class="homepage-taxon-box-text">+ <h3><%= section.title %></h3>+ </div>+ <% end %>+ <%= link_to spree.nested_taxons_path(section.subtitle), class: "homepage-taxon-box" do %>+ <img class="w-100 lazyload"+ data-src="<%= asset_path('homepage/category_banner_lower.jpg') %>"+ data-srcset="<%= image_source_set('homepage/category_banner_lower') %>"+ alt="<%= section.subtitle %>">++ <div class="homepage-taxon-box-text" role="img" aria-label="Sportswear">+ <h3><%= section.subtitle %></h3>+ </div>+ <% end %>+</div>++<div class="col-6 d-flex flex-column">+ <%= link_to spree.nested_taxons_path(section.button_text), class: "homepage-taxon-box flex-grow-1" do %>+ <img class="w-100 lazyload"+ data-src="<%= asset_path('homepage/big_category_banner.jpg') %>"+ data-srcset="<%= image_source_set('homepage/big_category_banner') %>"+ alt="<%= section.button_text %>">++ <div class="homepage-taxon-box-text">+ <h3><%= section.button_text %></h3>+ </div>+ <% end %>+</div>