Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.rb
index 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_applications
payment_methods refund_reasons reimbursement_types
@@ -30,10 +33,19 @@ module Spree
documents stripe_tax_registrations members subscriptions stock_locations webhooks_subscribers].include?(controller_name)
end
+ # @return [Array<String>] the available countries for checkout
def 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 avatar
def render_avatar(user, options = {})
return unless user.present?
@@ -54,12 +66,19 @@ module Spree
end
end
+ # returns the available display on options, eg backend, frontend, both
+ # @return [Array<Array<String, String>>] the available display on options
def display_on_options
Spree::DisplayOn::DISPLAY.map do |display_on|
[Spree.t("admin.display_on_options.#{display_on}"), display_on]
end
end
+ # 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 message
def 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 Spree
end
end
+ # 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 icon
def 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 Spree
content_tag :i, nil, class: "ti ti-#{icon_name} #{options[:class]}", style: styles
end
+ # returns the flag emoji for a country
+ # @param iso [String] the ISO code of the country
+ # @return [String] the flag emoji
def flag_emoji(iso)
::Country.new(iso).emoji_flag
end
- 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 field
def preference_field_for(form, field, options)
case options[:type]
when :integer
@@ -146,6 +146,11 @@ module Spree
end
end
+ # 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 field
def preference_field_options(options)
field_options = case options[:type]
when :integer
@@ -191,6 +196,10 @@ module Spree
size: 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 fields
def preference_fields(object, form)
return unless object.respond_to?(:preferences)
@@ -227,27 +236,14 @@ module Spree
dom_id(record, 'spree')
end
+ # renders a red dot with a * to indicate that a field is required
+ # @return [String] the required span tag
def required_span_tag
content_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_upload
Rails.application.config.active_storage.web_image_content_types
end
diff --git a/admin/app/helpers/spree/admin/bulk_operations_helper.rb b/admin/app/helpers/spree/admin/bulk_operations_helper.rb
index 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 Spree
module Admin
module BulkOperationsHelper
+ # render a checkbox to select all items for bulk operations
+ # @return [String]
def bulk_operations_select_all_checkbox
content_tag :div, class: "custom-control custom-checkbox ml-1" do
check_box_tag(
@@ -15,6 +17,9 @@ module Spree
end
end
+ # 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" do
check_box_tag(
@@ -29,6 +34,15 @@ module Spree
end
end
+ # 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 Spree
end
end
+ # render a close button for the bulk modal
def bulk_operations_close_button
button_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_counter
content_tag(:span, class: 'bulk-operations-counter ml-1') do
content_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.rb
index 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 Spree
module Admin
module 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 Spree
end.html_safe
end
+ # render a close button for the modal
+ # @return [String]
def modal_close_button
button_tag('', type: 'button', class: 'btn-close', data: { dismiss: 'modal', aria_label: Spree.t(:close) }).html_safe
end
+ # render a discard button for the modal
+ # @return [String]
def modal_discard_button
button_tag(type: 'button', class: 'btn btn-light', data: { dismiss: 'modal' }) do
Spree.t('actions.discard')
diff --git a/admin/app/helpers/spree/admin/navigation_helper.rb b/admin/app/helpers/spree/admin/navigation_helper.rb
index 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_dropdown
per_page_default = if @products
Spree::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 page
def per_page_dropdown_params(per_page)
args = params.permit!.to_h.clone
args.delete(:page)
@@ -56,6 +59,12 @@ module Spree
args
end
+ # 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 resource
def link_to_edit(resource, options = {})
url = options[:url] || edit_object_url(resource)
options[:data] ||= {}
@@ -64,6 +73,12 @@ module Spree
link_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 resource
def link_to_delete(resource, options = {})
url = options[:url] || object_url(resource)
name = options[:name] || Spree.t('actions.destroy')
@@ -81,6 +96,12 @@ module Spree
end
end
+ # 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 icon
def link_to_with_icon(icon_name, text, url, options = {})
options[:class] ||= (options[:class].to_s + " with-tip").strip
options[:title] ||= text if options[:no_text]
@@ -95,6 +116,12 @@ module Spree
link_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 icon
def active_link_to_with_icon(icon_name, text, url, options = {})
options[:class] = (options[:class].to_s + " with-tip").strip
options[:title] = text if options[:no_text]
@@ -109,7 +136,13 @@ module Spree
active_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 icon
def button(text, icon_name = nil, button_type = 'submit', options = {})
if icon_name
text = "#{icon(icon_name, class: "icon icon-#{icon_name}")} #{text}"
@@ -151,6 +184,10 @@ module Spree
end
end
+ # 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 icon
def active_badge(condition, options = {})
label = options[:label]
label ||= condition ? Spree.t(:say_yes) : Spree.t(:say_no)
@@ -163,6 +200,11 @@ module Spree
end
end
+ # 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 button
def page_header_back_button(default_url, object = nil, label = nil)
url = default_url
@@ -177,6 +219,11 @@ module Spree
end
end
+ # 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 icon
def external_link_to(label, url, opts = {}, &block)
opts[:target] ||= :blank
opts[:rel] ||= :nofollow
@@ -191,6 +238,32 @@ module Spree
end
end
+ # 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 icon
def 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: text
diff --git a/admin/spec/helpers/spree/admin/base_helper_spec.rb b/admin/spec/helpers/spree/admin/base_helper_spec.rb
index 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 do
end
end
end
-
- 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
- end
end
diff --git a/admin/spec/helpers/spree/admin/navigation_helper_spec.rb b/admin/spec/helpers/spree/admin/navigation_helper_spec.rb
index 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 do
expect(helper.page_header_back_button('/default', object)).to include('/from_session')
end
end
+
+ 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
+ end
end
diff --git a/core/app/helpers/spree/base_helper.rb b/core/app/helpers/spree/base_helper.rb
index 03b31afc0f..32e1a43ab0 100644
--- a/core/app/helpers/spree/base_helper.rb
+++ b/core/app/helpers/spree/base_helper.rb
@@ -163,6 +163,15 @@ module Spree
Spree::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 resource
def spree_storefront_resource_url(resource, options = {})
options.merge!(locale: locale_param) if defined?(locale_param) && locale_param.present?