@spree/docs 0.1.0

package/dist/developer/admin/helper-methods.md

@@ -0,0 +1,531 @@
+---
+title: Admin Dashboard Helper Methods
+sidebarTitle: Helper Methods
+---
+
+Helper methods available in the Admin Dashboard for navigation, links, and utility functions.
+
+> **INFO:** For UI components that render HTML elements (Dropdowns, Dialogs, Icons, etc.), see the [Components](/developer/admin/components) documentation.
+
+## Navigation Helpers
+
+### `nav_item`
+
+Creates a navigation item with optional icon.
+
+```erb
+<%= nav_item 'Dashboard', spree.admin_dashboard_path %>
+<%= nav_item 'Products', spree.admin_products_path, icon: 'package' %>
+<%= nav_item 'Orders', spree.admin_orders_path, active: true %>
+```
+
+With a block for custom content:
+
+```erb
+<%= nav_item spree.admin_products_path do %>
+  Products <span class="badge badge-primary">New</span>
+<% end %>
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `label` | String | The text to display |
+| `url` | String | The URL for the link (required) |
+| `icon` | String | Icon name to prepend |
+| `active` | Boolean | Force active state |
+| `data` | Hash | Data attributes |
+
+### `link_to_with_icon`
+
+Creates a link with an icon.
+
+```erb
+<%= link_to_with_icon 'eye', "View Order", spree.admin_order_path(order), class: "btn btn-primary" %>
+<%= link_to_with_icon 'pencil', "Edit", edit_path, class: "dropdown-item" %>
+<%= link_to_with_icon 'trash', "Delete", delete_path, no_text: true, title: "Delete item" %>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `icon_name` | String | Icon name from [Tabler Icons](https://tabler.io/icons) |
+| `text` | String | Link text |
+| `url` | String | Link URL (use `spree.` routes for internal links) |
+| `no_text` | Boolean | Show only icon with text as tooltip |
+| `title` | String | Tooltip text |
+
+### `active_link_to_with_icon`
+
+Same as `link_to_with_icon`, but adds the `active` class if the current page matches the URL.
+
+```erb
+<%= active_link_to_with_icon 'package', "Products", spree.admin_products_path, class: "nav-link" %>
+```
+
+### `link_to_edit`
+
+Renders an edit button for a resource. Only renders if the user has `update` permission.
+
+```erb
+<%= link_to_edit(@product) %>
+<%= link_to_edit(@product, url: custom_edit_path(@product)) %>
+<%= link_to_edit(@order, class: 'btn btn-primary') %>
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | String | auto | Custom URL (defaults to `edit_object_url(resource)`) |
+| `class` | String | `btn btn-light btn-sm` | CSS classes |
+| `data` | Hash | `{action: 'edit'}` | Data attributes |
+
+### `link_to_delete`
+
+Renders a delete button with confirmation. Only renders if the user has `destroy` permission.
+
+```erb
+<%= link_to_delete(@product) %>
+<%= link_to_delete(@product, name: 'Remove') %>
+<%= link_to_delete(@product, no_text: true) %>
+<%= link_to_delete(@product, icon: 'x') %>
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | String | auto | Custom URL (defaults to `object_url(resource)`) |
+| `name` | String | "Delete" | Button text |
+| `icon` | String | `trash` | Custom icon |
+| `no_text` | Boolean | false | Show only icon |
+| `class` | String | `btn btn-danger btn-sm` | CSS classes |
+| `data` | Hash | confirm + method | Data attributes |
+
+### `button`
+
+Renders a submit button with optional icon and loading state.
+
+```erb
+<%= button(Spree.t('actions.save')) %>
+<%= button(Spree.t('actions.save'), 'device-floppy') %>
+<%= button('Submit', 'send', 'submit', class: 'btn-success') %>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text` | String | required | Button text |
+| `icon_name` | String | nil | Optional icon |
+| `button_type` | String | `submit` | Button type |
+| `class` | String | `btn-primary` | CSS classes |
+
+### `external_link_to`
+
+Renders an external link that opens in a new tab with an indicator icon.
+
+```erb
+<%= external_link_to 'Documentation', 'https://docs.spreecommerce.org' %>
+<%= external_link_to 'GitHub', 'https://github.com/spree/spree' %>
+```
+
+With a block:
+
+```erb
+<%= external_link_to 'https://example.com' do %>
+  <strong>Custom content</strong>
+<% end %>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `label` | String | Link text |
+| `url` | String | External URL |
+| `target` | Symbol | Default: `:blank` |
+| `rel` | Symbol | Default: `:nofollow` |
+
+### `external_page_preview_link`
+
+Renders a link to preview a resource on the storefront.
+
+```erb
+<%= external_page_preview_link(@product) %>
+<%= external_page_preview_link(@post) %>
+```
+
+### `page_header_back_button`
+
+Renders a back button for page headers with smart return URL handling.
+
+```erb
+<%= page_header_back_button(spree.admin_products_path) %>
+<%= page_header_back_button(spree.admin_products_path, @product) %>
+<%= page_header_back_button(spree.admin_orders_path, @order, 'Back to Orders') %>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `default_url` | String | Default URL to navigate back to |
+| `object` | Object | Optional object to check for stored return URL in session |
+| `label` | String | Optional label text |
+
+### `per_page_dropdown`
+
+Renders a dropdown for selecting items per page on index pages.
+
+```erb
+<%= per_page_dropdown %>
+```
+
+Automatically detects the resource type and provides appropriate options based on configuration.
+
+### `link_to_export_modal`
+
+Renders a button to open the export modal. Only renders if user can create exports.
+
+```erb
+<%= link_to_export_modal %>
+```
+
+## Store Helpers
+
+Helpers for store-specific options and unit systems.
+
+### `weight_units`
+
+Returns weight unit options based on the store's unit system.
+
+```erb
+<%= f.select :weight_unit, weight_units %>
+```
+
+**Returns:**
+- Metric: `[["Kilogram", "kg"], ["Gram", "g"]]`
+- Imperial: `[["Pound", "lb"], ["Ounce", "oz"]]`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `store` | Spree::Store | `current_store` | Store to check unit system |
+
+### `dimension_units`
+
+Returns dimension unit options based on the store's unit system.
+
+```erb
+<%= f.select :dimension_unit, dimension_units %>
+```
+
+**Returns:**
+- Metric: `[["Centimeter", "cm"], ["Millimeter", "mm"]]`
+- Imperial: `[["Inch", "in"], ["Foot", "ft"]]`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `store` | Spree::Store | `current_store` | Store to check unit system |
+
+### `unit_systems`
+
+Returns available unit system options.
+
+```erb
+<%= f.select :unit_system, unit_systems %>
+```
+
+**Returns:** `[["Metric System", "metric"], ["Imperial System", "imperial"]]`
+
+### `display_on_options`
+
+Returns display location options for calculators and payment/shipping methods.
+
+```erb
+<%= f.select :display_on, display_on_options %>
+```
+
+**Returns:** `[["Both", "both"], ["Backend", "back_end"], ["Frontend", "front_end"]]`
+
+## Turbo Helpers
+
+Helpers for Turbo Streams and Turbo-enhanced forms.
+
+### `turbo_close_dialog`
+
+Returns a Turbo Stream response that closes the main dialog.
+
+```erb
+<%# In a turbo_stream.erb response %>
+<%= turbo_close_dialog %>
+```
+
+### `turbo_render_alerts`
+
+Returns a Turbo Stream response that updates the alerts frame.
+
+```erb
+<%= turbo_render_alerts %>
+<%= turbo_render_alerts(:custom_alerts) %>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `frame_name` | Symbol | `:alerts` | Turbo frame to update |
+
+### `turbo_save_button_tag`
+
+Creates a save button with loading state for Turbo forms.
+
+```erb
+<%= turbo_save_button_tag %>
+<%= turbo_save_button_tag('Update Product') %>
+<%= turbo_save_button_tag('Save', class: 'btn btn-success') %>
+```
+
+**Features:**
+- Shows spinner during submission
+- Integrates with `turbo-submit-button` Stimulus controller
+- Prevents double submissions
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `label` | String | "Save" | Button label |
+| `class` | String | `btn btn-primary text-center` | CSS classes |
+
+## Context Helpers
+
+### `current_store`
+
+Returns the current store instance.
+
+<details>
+<summary>Properties</summary>
+
+- **`name`** (`string`) — Store name
+    Example: "My Store"
+
+  - **`url`** (`string`) — Store URL
+    Example: `https://mystore.com`
+
+  - **`code`** (`string`) — Unique store identifier
+    Example: `my-store`
+
+  - **`mail_from_address`** (`string`) — Email address used for sending emails
+    Example: `store@example.com`
+
+  - **`default_currency`** (`string`) — Default store currency
+    Example: `USD`
+
+  - **`supported_currencies`** (`string`) — List of supported currencies
+    Example: `USD,EUR,GBP`
+
+  - **`default_locale`** (`string`) — Default store locale
+    Example: `en`
+
+  - **`supported_locales`** (`string`) — List of supported locales
+    Example: `en,es,fr`
+
+  - **`default_country_id`** (`integer`) — Default country ID
+    Example: `1`
+
+  - **`default_country`** (`Spree::Country`) — Default country
+    <details>
+<summary>properties</summary>
+
+- **`id`** (`integer`) — Country ID
+    Example: 1
+
+  - **`name`** (`string`) — Country name
+    Example: `United States`
+
+  - **`iso3`** (`string`) — Country ISO3 code
+    Example: `USA`
+
+  - **`iso`** (`string`) — Country ISO code
+    Example: `US`
+
+  - **`iso_name`** (`string`) — Country ISO name
+    Example: `UNITED STATES`
+
+  - **`states_required`** (`boolean`) — Whether states are required for this country
+    Example: `true`
+
+  - **`zipcode_required`** (`boolean`) — Whether zipcodes are required for this country
+    Example: `true`
+
+</details>
+
+  - **`checkout_zone_id`** (`integer`) — Checkout zone ID
+    Example: `2`
+
+  - **`seo_title`** (`string`) — SEO title
+    Example: `My Amazing Store`
+
+  - **`meta_description`** (`string`) — Meta description for SEO
+    Example: `The best products at the best prices`
+
+</details>
+
+```erb
+<%= current_store.name %>
+<%= current_store.default_currency %>
+```
+
+### `current_currency`
+
+Returns the currently selected currency for the admin session.
+
+```erb
+<%= current_currency %> <%# => "USD" %>
+```
+
+### `current_vendor`
+
+> **INFO:** Available only in [Spree Enterprise Edition](https://spreecommerce.com/pricing).
+
+<details>
+<summary>Properties</summary>
+
+- **`id`** (`integer`) — Unique vendor identifier
+    Example: `1`
+
+  - **`name`** (`string`) — Vendor name
+    Example: "My Vendor"
+
+  - **`state`** (`string`) — Vendor state/status
+    Example: `active`
+
+</details>
+
+### `supported_currencies`
+
+Returns the list of supported currencies for the current store.
+
+```erb
+<%= supported_currencies %> <%# => ["USD", "EUR", "GBP"] %>
+```
+
+### `try_spree_current_user`
+
+Returns the current user object or `nil` if not signed in.
+
+```erb
+<%= try_spree_current_user&.email %>
+
+<% if try_spree_current_user.present? %>
+  Signed in as <%= try_spree_current_user.email %>
+<% end %>
+```
+
+### `available_countries_iso`
+
+Returns ISO codes for countries available for checkout in the current store.
+
+```erb
+<%= available_countries_iso %> <%# => ["US", "CA", "GB"] %>
+```
+
+## Utility Helpers
+
+### `flag_emoji`
+
+Returns the flag emoji for a country ISO code.
+
+```erb
+<%= flag_emoji('US') %> <%# => 🇺🇸 %>
+<%= flag_emoji('GB') %> <%# => 🇬🇧 %>
+<%= flag_emoji('JP') %> <%# => 🇯🇵 %>
+```
+
+### `required_span_tag`
+
+Renders a red asterisk indicator for required fields.
+
+```erb
+<%= label_tag :name %>
+<%= required_span_tag %>
+```
+
+**Renders:** `<span class="required font-weight-bold text-danger"> *</span>`
+
+### `error_message_on`
+
+Renders validation error messages for a form field.
+
+```erb
+<%= error_message_on(@product, :name) %>
+<%= error_message_on(@order, :email) %>
+```
+
+**Renders:** `<span class="formError">can't be blank</span>`
+
+### `settings_area?`
+
+Returns `true` if the current page is in the settings area.
+
+```erb
+<% if settings_area? %>
+  <%= render 'spree/admin/shared/settings_sidebar' %>
+<% end %>
+```
+
+### `enterprise_edition?`
+
+Returns `true` if Spree Enterprise Edition is installed.
+
+```erb
+<% if enterprise_edition? %>
+  <%= render 'spree/admin/vendors/selector' %>
+<% end %>
+```
+
+### `allowed_file_types_for_upload`
+
+Returns allowed file types for Active Storage uploads.
+
+```erb
+<%= allowed_file_types_for_upload %>
+<%# => ["image/png", "image/jpeg", "image/gif", "image/webp"] %>
+```
+
+### `render_admin_partials`
+
+Renders all registered partials for an injection point.
+
+```erb
+<%= render_admin_partials(:product_form, f: f, product: @product) %>
+<%= render_admin_partials(:order_page_sidebar, order: @order) %>
+```
+
+See [Extending UI](/developer/admin/extending-ui) for more information about injection points.
+
+## Preference Helpers
+
+Helpers for rendering preference fields in settings forms.
+
+### `preference_fields`
+
+Renders all preference fields for an object.
+
+```erb
+<%= preference_fields(@payment_method, f) %>
+<%= preference_fields(@calculator, f, i18n_scope: 'spree.calculator') %>
+```
+
+### `preference_field`
+
+Renders a single preference field.
+
+```erb
+<%= preference_field(@payment_method, f, :api_key) %>
+```
+
+### `preference_field_for`
+
+Renders a form field based on preference type.
+
+```erb
+<%= preference_field_for(f, :preferred_api_key, type: :string) %>
+<%= preference_field_for(f, :preferred_test_mode, type: :boolean) %>
+<%= preference_field_for(f, :preferred_amount, type: :decimal, step: 0.01) %>
+```
+
+| Type | Rendered Field |
+|------|----------------|
+| `:integer` | Number field |
+| `:decimal` | Number field with step |
+| `:boolean` | Checkbox |
+| `:string` | Text field |
+| `:password` | Password field |
+| `:text` | Text area |