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 missing helper method documentation for LSP/LLMs (#12626)
Damian Legawiec2eaf5232c339
diff --git a/admin/app/helpers/spree/admin/base_helper.rb b/admin/app/helpers/spree/admin/base_helper.rbindex aee06bceaa..7e62421db8 100644--- a/admin/app/helpers/spree/admin/base_helper.rb+++ b/admin/app/helpers/spree/admin/base_helper.rb@@ -21,6 +21,9 @@ module Spree@spree_update_available ||= !Rails.env.test? && spree_updater.update_available?end+ # check if the current controller is a settings controller+ # this is used to display different sidebar navigation for settings pages+ # @return [Boolean]def settings_active?@settings_active || %w[stores zones shipping_methods oauth_applicationspayment_methods refund_reasons reimbursement_types@@ -30,10 +33,19 @@ module Spreedocuments stripe_tax_registrations members subscriptions stock_locations webhooks_subscribers].include?(controller_name)end+ # @return [Array<String>] the available countries for checkoutdef available_countries_iso@available_countries_iso ||= current_store.countries_available_for_checkout.pluck(:iso)end+ # render an avatar for a user+ # if user doesn't have an avatar, the user's initials will be displayed on a rounded background+ # @param user [Spree::User] the user to render the avatar for+ # @param options [Hash] the options for the avatar+ # @option options [Integer] :width the width of the avatar, default: 128+ # @option options [Integer] :height the height of the avatar, default: 128+ # @option options [String] :class the CSS class(es) of the avatar, default: 'avatar'+ # @return [String] the avatardef render_avatar(user, options = {})return unless user.present?@@ -54,12 +66,19 @@ module Spreeendend+ # returns the available display on options, eg backend, frontend, both+ # @return [Array<Array<String, String>>] the available display on optionsdef display_on_optionsSpree::DisplayOn::DISPLAY.map do |display_on|[Spree.t("admin.display_on_options.#{display_on}"), display_on]endend+ # render an error message for a form field+ # @param object [Spree::Model] the object to render the error message for+ # @param method [String] the method to render the error message for+ # @param options [Hash] the options for the error message+ # @return [String] the error messagedef error_message_on(object, method, _options = {})object = convert_to_model(object)obj = object.respond_to?(:errors) ? object : instance_variable_get("@#{object}")@@ -72,6 +91,10 @@ module Spreeendend+ # render an icon, using the tabler icons library+ # @param icon_name [String] the name of the icon, eg: 'pencil', see: https://tabler.io/icons+ # @param options [Hash] the options for the icon+ # @return [String] the icondef icon(icon_name, options = {})if icon_name.ends_with?('.svg')icon_name = File.basename(icon_name, File.extname(icon_name))@@ -91,42 +114,19 @@ module Spreecontent_tag :i, nil, class: "ti ti-#{icon_name} #{options[:class]}", style: stylesend+ # returns the flag emoji for a country+ # @param iso [String] the ISO code of the country+ # @return [String] the flag emojidef flag_emoji(iso)::Country.new(iso).emoji_flagend- def preference_field_tag(name, value, options)- if options[:key] == :currency- return select_tag(- name,- currency_options_for_select(- value,- current_store.supported_currencies.split(',')- ),- class: 'custom-select',- disabled: current_store.supported_currencies.split(',').count == 1- )- end-- case options[:type]- when :integer- number_field_tag(name, value, preference_field_options(options))- when :decimal- number_field_tag(name, value, preference_field_options(options))- when :boolean- hidden_field_tag(name, 0, id: "#{name}_hidden") +- check_box_tag(name, 1, value, preference_field_options(options))- when :string- text_field_tag(name, value, preference_field_options(options))- when :password- password_field_tag(name, value, preference_field_options(options))- when :text- text_area_tag(name, value, preference_field_options(options))- else- text_field_tag(name, value, preference_field_options(options))- end- end-+ # render a form field for a preference, according to the type of the preference (number, decimal, boolean, string, password, text)+ # see https://spreecommerce.org/docs/developer/customization/model-preferences+ # @param form [ActionView::Helpers::FormBuilder] the form builder+ # @param field [String] the name of the field+ # @param options [Hash] the options for the field+ # @return [String] the preference fielddef preference_field_for(form, field, options)case options[:type]when :integer@@ -146,6 +146,11 @@ module Spreeendend+ # returns the options for a preference field, according to the type of the preference (number, decimal, boolean, string, password, text)+ # @param options [Hash] the options for the field+ # @option options [Symbol] :type the type of the preference, eg. :integer, :decimal, :boolean, :string, :password, :text+ # @option options [Boolean] :disabled whether the field is disabled+ # @return [Hash] the options for the fielddef preference_field_options(options)field_options = case options[:type]when :integer@@ -191,6 +196,10 @@ module Spreesize: options[:size])end+ # renders all the preference fields for an object+ # @param object [Spree::TaxRate, Spree::Calculator, Spree::PaymentMethod, Spree::ShippingMethod, Spree::Store] the object to render the preference fields for+ # @param form [ActionView::Helpers::FormBuilder] the form builder+ # @return [String] the preference fieldsdef preference_fields(object, form)return unless object.respond_to?(:preferences)@@ -227,27 +236,14 @@ module Spreedom_id(record, 'spree')end+ # renders a red dot with a * to indicate that a field is required+ # @return [String] the required span tagdef required_span_tagcontent_tag(:span, ' *', class: 'required font-weight-bold text-danger')end- def external_page_preview_link(resource, options = {})- resource_name = options[:name] || resource.class.name.demodulize-- url = if [Spree::Product, Spree::Post].include?(resource.class)- spree_storefront_resource_url(resource, preview_id: resource.id)- else- spree_storefront_resource_url(resource)- end-- link_to_with_icon(- 'eye',- Spree.t('admin.utilities.preview', name: resource_name),- url,- class: 'text-left dropdown-item', id: "adminPreview#{resource_name}", target: :blank, data: { turbo: false }- )- end-+ # returns the allowed file types for upload, according to the active storage configuration+ # @return [Array<String>] the allowed file types for upload, eg. ['image/png', 'image/jpeg', 'image/gif', 'image/webp']def allowed_file_types_for_uploadRails.application.config.active_storage.web_image_content_typesenddiff --git a/admin/app/helpers/spree/admin/bulk_operations_helper.rb b/admin/app/helpers/spree/admin/bulk_operations_helper.rbindex c5d47a87dd..c12827ea79 100644--- a/admin/app/helpers/spree/admin/bulk_operations_helper.rb+++ b/admin/app/helpers/spree/admin/bulk_operations_helper.rb@@ -1,6 +1,8 @@module Spreemodule Adminmodule BulkOperationsHelper+ # render a checkbox to select all items for bulk operations+ # @return [String]def bulk_operations_select_all_checkboxcontent_tag :div, class: "custom-control custom-checkbox ml-1" docheck_box_tag(@@ -15,6 +17,9 @@ module Spreeendend+ # render a checkbox to select an item for bulk operations+ # @param object [Spree::Product, Spree::User, Spree::Order]+ # @return [String]def bulk_operations_checkbox(object)content_tag :div, class: "custom-control custom-checkbox ml-1" docheck_box_tag(@@ -29,6 +34,15 @@ module Spreeendend+ # render a link to perform a bulk action+ # @param text [String] the text of the link+ # @param path [String] the path of the link+ # @param options [Hash] the options of the link+ # @option options [String] :icon the icon of the link+ # @option options [String] :url the url to perform the bulk action to be set for the form in bulk modal+ # @option options [String] :class the class of the link+ # @option options [String] :data the data of the link+ # @return [String]def bulk_action_link(text, path, options = {})options[:data] ||= {}options[:data][:action] ||= 'click->bulk-operation#setBulkAction'@@ -45,19 +59,22 @@ module Spreeendend+ # render a close button for the bulk modaldef bulk_operations_close_buttonbutton_tag(- '',- type: 'button',- class: 'btn-close',- data: {- dismiss: 'modal',- aria_label: Spree.t(:close),- action: 'bulk-operation#cancel'+ '',+ type: 'button',+ class: 'btn-close',+ data: {+ dismiss: 'modal',+ aria_label: Spree.t(:close),+ action: 'bulk-operation#cancel'})end+ # render a counter for the bulk operations+ # @return [String]def bulk_operations_countercontent_tag(:span, class: 'bulk-operations-counter ml-1') docontent_tag(:strong, '', data: { bulk_operation_target: 'counter' }) +diff --git a/admin/app/helpers/spree/admin/modal_helper.rb b/admin/app/helpers/spree/admin/modal_helper.rbindex 2e5eeb2b1a..93a9a00ba7 100644--- a/admin/app/helpers/spree/admin/modal_helper.rb+++ b/admin/app/helpers/spree/admin/modal_helper.rb@@ -1,6 +1,9 @@module Spreemodule Adminmodule ModalHelper+ # render a header for the modal+ # @param title [String, Proc] the title of the modal+ # @return [String]def modal_header(title)title = capture(&title) if block_given?content_tag(:div, class: 'modal-header') do@@ -8,10 +11,14 @@ module Spreeend.html_safeend+ # render a close button for the modal+ # @return [String]def modal_close_buttonbutton_tag('', type: 'button', class: 'btn-close', data: { dismiss: 'modal', aria_label: Spree.t(:close) }).html_safeend+ # render a discard button for the modal+ # @return [String]def modal_discard_buttonbutton_tag(type: 'button', class: 'btn btn-light', data: { dismiss: 'modal' }) doSpree.t('actions.discard')diff --git a/admin/app/helpers/spree/admin/navigation_helper.rb b/admin/app/helpers/spree/admin/navigation_helper.rbindex 928e7db291..ff115fdc14 100644--- a/admin/app/helpers/spree/admin/navigation_helper.rb+++ b/admin/app/helpers/spree/admin/navigation_helper.rb@@ -16,6 +16,7 @@ module Spree# the per_page_dropdown is used on index pages like orders, products, promotions etc.# this method generates the select_tag+ # @return [String]def per_page_dropdownper_page_default = if @productsSpree::Admin::RuntimeConfig.admin_products_per_page@@ -48,6 +49,8 @@ module Spree# helper method to create proper url to apply per page ing# fixes https://github.com/spree/spree/issues/6888+ # @param per_page [Integer] the number of items per page+ # @return [Hash] the params to apply per pagedef per_page_dropdown_params(per_page)args = params.permit!.to_h.cloneargs.delete(:page)@@ -56,6 +59,12 @@ module Spreeargsend+ # render a button link to edit a resource+ # if the current user doesn't have permission to update the resource, the button will not be rendered+ # @param resource [Spree::Product, Spree::User, Spree::Order] the resource to edit+ # @param options [Hash] the options for the link+ # @option options [String] :url the url to edit the resource (optional)+ # @return [String] the link to edit the resourcedef link_to_edit(resource, options = {})url = options[:url] || edit_object_url(resource)options[:data] ||= {}@@ -64,6 +73,12 @@ module Spreelink_to_with_icon('pencil', Spree.t(:edit), url, options) if can?(:update, resource)end+ # render a button to delete a resource with a confirmation modal+ # if the current user doesn't have permission to destroy the resource, the button will not be rendered+ # @param resource [Spree::Product, Spree::User, Spree::Order] the resource to delete+ # @param options [Hash] the options for the link+ # @option options [String] :url the url to delete the resource (optional)+ # @return [String] the link to delete the resourcedef link_to_delete(resource, options = {})url = options[:url] || object_url(resource)name = options[:name] || Spree.t('actions.destroy')@@ -81,6 +96,12 @@ module Spreeendend+ # renders a link with an icon+ # @param icon_name [String] the name of the icon, eg: 'pencil', see: https://tabler.io/icons+ # @param text [String] the text of the link+ # @param url [String] the url of the link+ # @param options [Hash] the options for the link+ # @return [String] the link with the icondef link_to_with_icon(icon_name, text, url, options = {})options[:class] ||= (options[:class].to_s + " with-tip").stripoptions[:title] ||= text if options[:no_text]@@ -95,6 +116,12 @@ module Spreelink_to(text.html_safe, url, options)end+ # renders an active link with an icon, using the active_link_to method from https://github.com/comfy/active_link_to gem+ # @param icon_name [String] the name of the icon, eg: 'pencil', see: https://tabler.io/icons+ # @param text [String] the text of the link+ # @param url [String] the url of the link+ # @param options [Hash] the options for the link+ # @return [String] the active link with the icondef active_link_to_with_icon(icon_name, text, url, options = {})options[:class] = (options[:class].to_s + " with-tip").stripoptions[:title] = text if options[:no_text]@@ -109,7 +136,13 @@ module Spreeactive_link_to(text.html_safe, url, options)end+ # renders a button with an icon (optional)# Override: Add disable_with option to prevent multiple request on consecutive clicks+ # @param text [String] the text of the button+ # @param icon_name [String] the name of the icon, eg: 'pencil', see: https://tabler.io/icons+ # @param button_type [String] the type of the button, eg: 'submit', 'button'+ # @param options [Hash] the options for the button+ # @return [String] the button with the icondef button(text, icon_name = nil, button_type = 'submit', options = {})if icon_nametext = "#{icon(icon_name, class: "icon icon-#{icon_name}")} #{text}"@@ -151,6 +184,10 @@ module Spreeendend+ # renders a badge (active/inactive)+ # @param condition [Boolean] the condition to check+ # @param options [Hash] the options for the badge+ # @return [String] the badge with the icondef active_badge(condition, options = {})label = options[:label]label ||= condition ? Spree.t(:say_yes) : Spree.t(:say_no)@@ -163,6 +200,11 @@ module Spreeendend+ # renders a back button to the previous page+ # @param default_url [String] the default url to go back to+ # @param object [Spree::Product, Spree::User, Spree::Order] the object list to go back to+ # @param label [String] the label of the back button (optional)+ # @return [String] the back buttondef page_header_back_button(default_url, object = nil, label = nil)url = default_url@@ -177,6 +219,11 @@ module Spreeendend+ # renders an external link with an icon (eg. spree documentation website)+ # @param label [String] the label of the link+ # @param url [String] the url of the link+ # @param opts [Hash] the options for the link+ # @return [String] the external link with the icondef external_link_to(label, url, opts = {}, &block)opts[:target] ||= :blankopts[:rel] ||= :nofollow@@ -191,6 +238,32 @@ module Spreeendend+ # renders a link to preview a resource on the storefront using the spree_storefront_resource_url helper+ # @param resource [Spree::Product, Spree::Post] the resource to preview+ # @param options [Hash] the options for the link+ # @return [String] the link to preview the resource+ def external_page_preview_link(resource, options = {})+ resource_name = options[:name] || resource.class.name.demodulize++ url = if [Spree::Product, Spree::Post].include?(resource.class)+ spree_storefront_resource_url(resource, preview_id: resource.id)+ else+ spree_storefront_resource_url(resource)+ end++ link_to_with_icon(+ 'eye',+ Spree.t('admin.utilities.preview', name: resource_name),+ url,+ class: 'text-left dropdown-item', id: "adminPreview#{resource_name}", target: :blank, data: { turbo: false }+ )+ end++ # renders a help bubble with an icon+ # @param text [String] the text of the help bubble+ # @param placement [String] the placement of the help bubble+ # @param css [String] the css class of the help bubble+ # @return [String] the help bubble with the icondef help_bubble(text = '', placement = 'bottom', css: nil)css ||= 'text-muted'content_tag :small, icon('info-square-rounded', class: css), data: { placement: placement }, class: "with-tip #{css}", title: textdiff --git a/admin/spec/helpers/spree/admin/base_helper_spec.rb b/admin/spec/helpers/spree/admin/base_helper_spec.rbindex 3b0ac1875a..5a11a5f40e 100644--- a/admin/spec/helpers/spree/admin/base_helper_spec.rb+++ b/admin/spec/helpers/spree/admin/base_helper_spec.rb@@ -20,33 +20,4 @@ describe Spree::Admin::BaseHelper doendendend-- describe '#external_page_preview_link' do- let(:current_store) { create(:store) }- let(:product) { create(:product, stores: [current_store]) }-- def spree_storefront_resource_url(*_args); end- def button_link_to(*_args); end- def link_to_with_icon(*_args); end-- context 'for product' do- context 'when product is a draft' do- before { product.update(status: :draft) }-- it 'should call spree_storefront_resource_url with preview_id' do- expect(self).to receive(:spree_storefront_resource_url).with(product, preview_id: product.id)-- external_page_preview_link(product)- end- end-- context 'when product is not a draft' do- it 'should call spree_storefront_resource_url with preview_id' do- expect(self).to receive(:spree_storefront_resource_url).with(product, preview_id: product.id)-- external_page_preview_link(product)- end- end- end- endenddiff --git a/admin/spec/helpers/spree/admin/navigation_helper_spec.rb b/admin/spec/helpers/spree/admin/navigation_helper_spec.rbindex a1ce8031f4..e853ef5047 100644--- a/admin/spec/helpers/spree/admin/navigation_helper_spec.rb+++ b/admin/spec/helpers/spree/admin/navigation_helper_spec.rb@@ -88,4 +88,33 @@ describe Spree::Admin::NavigationHelper, type: :helper doexpect(helper.page_header_back_button('/default', object)).to include('/from_session')endend++ describe '#external_page_preview_link' do+ let(:current_store) { create(:store) }+ let(:product) { create(:product, stores: [current_store]) }++ def spree_storefront_resource_url(*_args); end+ def button_link_to(*_args); end+ def link_to_with_icon(*_args); end++ context 'for product' do+ context 'when product is a draft' do+ before { product.update(status: :draft) }++ it 'should call spree_storefront_resource_url with preview_id' do+ expect(self).to receive(:spree_storefront_resource_url).with(product, preview_id: product.id)++ external_page_preview_link(product)+ end+ end++ context 'when product is not a draft' do+ it 'should call spree_storefront_resource_url with preview_id' do+ expect(self).to receive(:spree_storefront_resource_url).with(product, preview_id: product.id)++ external_page_preview_link(product)+ end+ end+ end+ endenddiff --git a/core/app/helpers/spree/base_helper.rb b/core/app/helpers/spree/base_helper.rbindex 03b31afc0f..32e1a43ab0 100644--- a/core/app/helpers/spree/base_helper.rb+++ b/core/app/helpers/spree/base_helper.rb@@ -163,6 +163,15 @@ module SpreeSpree::Core::Engine.frontend_available?end+ # returns the URL of an object on the storefront+ # @param resource [Spree::Product, Spree::Post, Spree::Taxon, Spree::Page] the resource to get the URL for+ # @param options [Hash] the options for the URL+ # @option options [String] :locale the locale of the resource, defaults to I18n.locale+ # @option options [String] :store the store of the resource, defaults to current_store+ # @option options [String] :relative whether to use the relative URL, defaults to false+ # @option options [String] :preview_id the preview ID of the resource, usually the ID of the resource+ # @option options [String] :variant_id the variant ID of the resource, usually the ID of the variant (only used for products)+ # @return [String] the URL of the resourcedef spree_storefront_resource_url(resource, options = {})options.merge!(locale: locale_param) if defined?(locale_param) && locale_param.present?