@spree/docs 0.1.0

package/dist/developer/admin/extending-ui.md

@@ -0,0 +1,1964 @@
+---
+title: Extending Admin Dashboard UI
+sidebarTitle: Extending UI
+---
+
+Spree Admin Dashboard allows you easily extend existing pages and screens with your own code, without any need to modify the core codebase. This allows you to easily inject your custom UI elements without compromising the integrity of the core codebase. Which in effect allows you to safely update your Spree installation to the latest version.
+
+## How it works
+
+The entire system works on the basis of injection points which are declared throughout the admin dashboard and allows you to push your own code there. Each injection point is identified by a key, eg. `body_end`.
+
+Let's say you want to add a new footer to the admin dashboard. You'll need to generate a template in your application:
+
+1. Ensure you have the proper directory to store your templates:
+
+    ```bash
+    mkdir -p app/views/spree/admin/shared
+    ```
+
+2. Create a new partial template file (partial templates file names start with underscore)
+
+    ```bash
+    touch app/views/spree/admin/shared/_additional_footer.html.erb
+    ```
+
+3. Add your own code to the partial
+
+    ```erb
+    <div class="mx-auto bg-light p-3 rounded-lg text-center w-10">
+      Copyright <%= current_store.name %> <%= Time.current.year %>
+    </div>
+    ```
+
+4. Register your partial in `config/initializers/spree.rb`
+
+    **Spree 5.2+:**
+
+```ruby config/initializers/spree.rb
+        Rails.application.config.after_initialize do
+          Spree.admin.partials.body_end << 'spree/admin/shared/additional_footer'
+        end
+        ```
+
+      **Spree 5.1 and below:**
+
+```ruby config/initializers/spree.rb
+        Rails.application.config.spree_admin.body_end << 'spree/admin/shared/additional_footer_partials'
+        ```
+
+        > **WARNING:** For older versions of Spree you need to add `_partials` suffix for all injection points, 
+>           eg. `body_end_partials` instead of `body_end`.
+
+
+    > **INFO:** The key is the name of the injection point, eg. `body_end`.
+
+    > **INFO:** Remember to use the correct path to your template file and skip the `_` prefix.
+
+5. Restart your web server and you should see your new footer.
+
+    <img src="/images/developer/admin/partial_injecting_example.png" />
+
+    > **INFO:** Making further changes to the partial template will not require you to restart the web server. They will be picked up automatically.
+
+> **HINT:** To summarize, we're injecting our code into the `body_end` array. This is a list of partials that will be rendered at the end of the body tag (before the closing `</body>` tag). The order of the partials in the array is the order in which they will be rendered.
+
+## Partials API
+
+The `Spree.admin.partials` object provides a clean API for registering partials to injection points. This API is available in Spree 5.2 and later.
+
+### Accessing Available Injection Points
+
+You can list all available injection points programmatically:
+
+```ruby
+# In Rails console or initializer
+Spree.admin.partials.keys
+# => ["head", "body_start", "body_end", "dashboard_analytics", "product_form", ...]
+```
+
+### Registering Partials
+
+Each injection point is an array that you can append to:
+
+```ruby config/initializers/spree.rb
+
+# Add a single partial
+Spree.admin.partials.product_form << 'spree/admin/products/erp_section'
+
+# Add multiple partials
+Spree.admin.partials.dashboard_sidebar << 'spree/admin/dashboard/analytics_widget'
+Spree.admin.partials.dashboard_sidebar << 'spree/admin/dashboard/inventory_widget'
+```
+
+### Viewing Registered Partials
+
+To see which partials are registered for a specific injection point:
+
+```ruby
+Spree.admin.partials.product_form
+# => ["spree/admin/products/erp_section"]
+```
+
+### Replacing All Partials
+
+You can also replace all partials for an injection point:
+
+```ruby
+Spree.admin.partials.product_form = ['my/custom/partial']
+```
+
+> **WARNING:** Replacing all partials will remove any partials registered by other extensions. Use this with caution.
+
+## List of all injection points
+
+Here's a list of all places you can inject your custom code:
+
+### Layout
+
+<details>
+<summary><head></summary>
+
+`head`
+
+    Injects code into the `<head>` tag
+
+</details>
+
+
+  <details>
+<summary><body></summary>
+
+`body_start`
+
+    Injects code into the `<body>` tag, before the main content
+
+</details>
+
+
+  <details>
+<summary></body></summary>
+
+`body_end`
+
+    Injects code into the `<body>` tag, after the main content
+
+</details>
+
+
+### Dashboard
+
+<details>
+<summary>Analytics</summary>
+
+`dashboard_analytics`
+
+    <img src="/images/developer/admin/dashboard_analytics_partials.png" />
+
+    Injects code into the dashboard analytics section, eg.
+
+    ```erb
+    <div class="card">
+      <div class="card-body">
+        <h5 class="card-title">Top ERP products</h5>
+      </div>
+      <div class="card-footer">
+        <%# ... my custom content ... %>
+      </div>
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Sidebar</summary>
+
+`dashboard_sidebar`
+
+    <img src="/images/developer/admin/dashboard_sidebar_partials.png" />
+
+    Injects code into the dashboard sidebar, eg.
+
+    ```erb
+    <div class="card">
+      <div class="card-body">
+        <h5 class="card-title">Latest ERP syncs</h5>
+      </div>
+      <div class="card-footer">
+        <%# ... my custom content ... %>
+      </div>
+    </div>
+    ```
+
+</details>
+
+
+### Orders
+
+<details>
+<summary>Orders Actions</summary>
+
+`orders_actions`
+
+    Injects code into the page actions area (top right of the page) for the orders list page. This is useful for adding custom buttons, export options, or other actions.
+
+    ```erb
+    <%= link_to "Export to ERP", export_orders_to_erp_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Orders Header</summary>
+
+`orders_header`
+
+    Injects code between the page header and the main content area for the orders list page. This is useful for adding notifications, alerts, or additional information.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Processing:</strong> Orders are automatically processed and shipped within 24 hours.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Orders Filters</summary>
+
+`orders_filters`
+
+    <img src="/images/developer/admin/orders_filters_partials.png" />
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the orders list filters, to add custom filters.
+    This partial has access to the `f` variable, which is the form builder for the filters, eg.
+
+    ```erb
+    <%= f.spree_text_field :q_number_cont, data: { filters_target: :input } %>
+    ```
+
+    > **TIP:** * `q_number_cont` - The name of the filter field. For filtering we're using [ransack](/developer/core-concepts/search-filtering) gem, so the name of the filter field is the name of the attribute we're filtering by.
+>     * `data: { filters_target: :input }` - Needed for the [Stimulus Filters controller](https://github.com/spree/spree/blob/main/admin/app/javascript/spree/admin/controllers/filters_controller.js) to work.
+
+</details>
+
+
+  <details>
+<summary>Order Page Dropdown</summary>
+
+`order_page_dropdown`
+
+    <img src="/images/developer/admin/order_page_dropdown_partials.png" />
+
+    #### Variables
+
+    - **`order`** (`Spree::Order`) — The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+
+    Injects code into the order page dropdown. This partial has access to the `order` variable.
+
+    To add an additional dropdown item, you can use the following code:
+
+    ```erb
+    <%= link_to "View Order in ERP", "https://erp.com/orders/#{order.number}", class: "dropdown-item", target: "_blank" %>
+    ```
+
+    > **TIP:** * `dropdown-item` is a CSS class for styling the dropdown item
+>     * `target: "_blank"` is used to open the link in a new tab
+
+</details>
+
+
+  <details>
+<summary>Order Page Header</summary>
+
+`order_page_header`
+
+    <img src="/images/developer/admin/order_page_header_partials.png" />
+
+    #### Variables
+
+    - **`order`** (`Spree::Order`) — The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+
+    Injects code into the order page header.
+
+    To add an additional action button near the `...` button, you can use the following code:
+
+    <img src="/images/developer/admin/order_page_header_partials.png" />
+
+    Injects code into the order page header.
+
+    To add an additional action button near the `...` button, you can use the following code:
+
+    ```erb
+    <%= content_for :page_actions do %>
+      <%= link_to "Send to ERP", "#", class: "btn btn-primary" %>
+    <% end %>
+    ```
+
+    To add an inline alert to the order page, you can use the following code:
+
+    ```erb
+    <%= content_for :page_alerts do %>
+      <% if order.sent_to_erp_at.blank? %>
+        <div class="alert alert-success">Order sent to ERP at <%= local_time(order.sent_to_erp_at) %></div>
+      <% else %>
+        <div class="alert alert-danger">Order not sent to ERP</div>
+      <% end %>
+    <% end %>
+    ```
+
+    > **TIP:** `local_time` is a helper for displaying the time in the user's timezone in a human readable **format** (based on the browser's timezone).
+
+</details>
+
+
+  <details>
+<summary>Order Page Body</summary>
+
+`order_page_body`
+
+    <img src="/images/developer/admin/order_page_body_partials.png" />
+
+    #### Variables
+
+    - **`order`** (`Spree::Order`) — The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+
+    Injects code into the order page body. This partial has access to the `order` variable.
+
+    To add a new section to the order page, you can use the following code:
+
+    ```erb
+    <div class="card mb-6">
+      <div class="card-header">
+        <h5 class="card-title">ERP Integration</h5>
+      </div>
+      <div class="card-body">
+        <% if order.sent_to_erp_at.blank? %>
+          <p class="text-muted text-center">Order not sent to ERP</p>
+        <% else %>
+          <ul class="list-group list-group-flush">
+            <li class="list-group-item">
+              <strong>ERP Order ID:</strong> <%= order.erp_order_id %>
+            </li>
+            <li class="list-group-item">
+              <strong>Sent to ERP at:</strong> <%= local_time(order.sent_to_erp_at) %>
+            </li>
+          </ul>
+        <% end %>
+      </div>
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Order Page Sidebar</summary>
+
+`order_page_sidebar`
+
+    <img src="/images/developer/admin/order_page_sidebar_partials.png" />
+
+    #### Variables
+
+    - **`order`** (`Spree::Order`) — The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+
+    Injects code into the order page sidebar. This partial has access to the `order` variable.
+
+</details>
+
+
+### Customers
+
+<details>
+<summary>Customers Actions</summary>
+
+`users_actions`
+
+    Injects code into the page actions area (top right of the page) for the customers list page. This is useful for adding custom buttons, export options, or other actions.
+
+    ```erb
+    <%= link_to "Sync with CRM", sync_customers_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Customers Header</summary>
+
+`users_header`
+
+    Injects code between the page header and the main content area for the customers list page. This is useful for adding notifications, alerts, or additional information.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Note:</strong> Customer data is synced with CRM every hour.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Customers Filters</summary>
+
+`users_filters`
+
+    #### Variables
+
+    - **`f`** (`ActionView::Helpers::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the customers list filters. This partial has access to the `f` variable, which is the form builder for the filters.
+
+    ```erb
+    <%= f.spree_select :custom_field_eq, [["VIP", "vip"], ["Regular", "regular"]], { include_blank: true }, { data: { filters_target: :input } } %>
+    ```
+
+    > **TIP:** * Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names
+>     * Include `data: { filters_target: :input }` for proper integration with the Stimulus Filters controller
+
+</details>
+
+
+### Stock Items
+
+<details>
+<summary>Stock Items Actions</summary>
+
+`stock_items_actions`
+
+    Injects code into the page actions area for the stock items list page.
+
+    ```erb
+    <%= link_to "Export to WMS", export_stock_to_wms_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Stock Items Header</summary>
+
+`stock_items_header`
+
+    Injects code between the page header and the main content area for the stock items list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Warning:</strong> Low stock items require attention.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Stock Items Filters</summary>
+
+`stock_items_filters`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the stock items list filters.
+
+    ```erb
+    <%= f.spree_number_field :count_on_hand_lt,
+        label: "Stock Below",
+        data: { filters_target: :input } %>
+    ```
+
+    > **TIP:** Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names (e.g., `_lt` for "less than").
+
+</details>
+
+
+### Admin Users
+
+<details>
+<summary>Admin Users Actions</summary>
+
+`admin_users_actions`
+
+    Injects code into the page actions area for the admin users list page.
+
+    ```erb
+    <%= link_to "Export Users", export_admin_users_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Admin Users Header</summary>
+
+`admin_users_header`
+
+    Injects code between the page header and the main content area for the admin users list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Security:</strong> Review admin access regularly.
+    </div>
+    ```
+
+</details>
+
+
+### Classifications
+
+<details>
+<summary>Classifications Actions</summary>
+
+`classifications_actions`
+
+    Injects code into the page actions area for the classifications list page.
+
+    ```erb
+    <%= link_to "Bulk Update", bulk_update_classifications_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Classifications Header</summary>
+
+`classifications_header`
+
+    Injects code between the page header and the main content area for the classifications list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Tip:</strong> Use drag and drop to reorder classifications.
+    </div>
+    ```
+
+</details>
+
+
+### Coupon Codes
+
+<details>
+<summary>Coupon Codes Actions</summary>
+
+`coupon_codes_actions`
+
+    Injects code into the page actions area for the coupon codes list page.
+
+    ```erb
+    <%= link_to "Generate Bulk Codes", bulk_generate_coupons_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Coupon Codes Header</summary>
+
+`coupon_codes_header`
+
+    Injects code between the page header and the main content area for the coupon codes list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Notice:</strong> Expired codes will be automatically cleaned up.
+    </div>
+    ```
+
+</details>
+
+
+### Custom Domains
+
+<details>
+<summary>Custom Domains Actions</summary>
+
+`custom_domains_actions`
+
+    Injects code into the page actions area for the custom domains list page.
+
+    ```erb
+    <%= link_to "Verify All Domains", verify_all_domains_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Custom Domains Header</summary>
+
+`custom_domains_header`
+
+    Injects code between the page header and the main content area for the custom domains list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>SSL:</strong> SSL certificates are automatically managed.
+    </div>
+    ```
+
+</details>
+
+
+### Customer Returns
+
+<details>
+<summary>Customer Returns Actions</summary>
+
+`customer_returns_actions`
+
+    Injects code into the page actions area for the customer returns list page.
+
+    ```erb
+    <%= link_to "Export Returns Report", export_returns_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Customer Returns Header</summary>
+
+`customer_returns_header`
+
+    Injects code between the page header and the main content area for the customer returns list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Processing:</strong> Returns are processed within 3-5 business days.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Customer Returns Filters</summary>
+
+`customer_returns_filters`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the customer returns list filters.
+
+    ```erb
+    <%= f.spree_select :reason_eq,
+        [["Damaged", "damaged"], ["Wrong Item", "wrong_item"]],
+        { include_blank: true, label: "Return Reason" },
+        { data: { filters_target: :input } } %>
+    ```
+
+    > **TIP:** Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names (e.g., `_eq` for "equals").
+
+</details>
+
+
+### Digital Assets
+
+<details>
+<summary>Digital Assets Actions</summary>
+
+`digital_assets_actions`
+
+    Injects code into the page actions area for the digital assets list page.
+
+    ```erb
+    <%= link_to "Bulk Upload", bulk_upload_assets_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Digital Assets Header</summary>
+
+`digital_assets_header`
+
+    Injects code between the page header and the main content area for the digital assets list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Storage:</strong> Assets are stored in cloud storage with CDN.
+    </div>
+    ```
+
+</details>
+
+
+### Exports
+
+<details>
+<summary>Exports Actions</summary>
+
+`exports_actions`
+
+    Injects code into the page actions area for the exports list page.
+
+    ```erb
+    <%= link_to "Schedule Export", new_scheduled_export_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Exports Header</summary>
+
+`exports_header`
+
+    Injects code between the page header and the main content area for the exports list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Retention:</strong> Export files are kept for 30 days.
+    </div>
+    ```
+
+</details>
+
+
+### Gift Cards
+
+<details>
+<summary>Gift Cards Actions</summary>
+
+`gift_cards_actions`
+
+    Injects code into the page actions area for the gift cards list page.
+
+    ```erb
+    <%= link_to "Bulk Generate", bulk_generate_gift_cards_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Gift Cards Header</summary>
+
+`gift_cards_header`
+
+    Injects code between the page header and the main content area for the gift cards list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Security:</strong> Gift card codes are encrypted at rest.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Gift Cards Filters</summary>
+
+`gift_cards_filters`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the gift cards list filters.
+
+    ```erb
+    <%= f.spree_number_field :balance_gt,
+        label: "Balance Greater Than",
+        step: 0.01,
+        data: { filters_target: :input } %>
+    ```
+
+    > **TIP:** Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names (e.g., `_gt` for "greater than").
+
+</details>
+
+
+### Integrations
+
+<details>
+<summary>Integrations Actions</summary>
+
+`integrations_actions`
+
+    Injects code into the page actions area for the integrations list page.
+
+    ```erb
+    <%= link_to "Test All Connections", test_integrations_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Integrations Header</summary>
+
+`integrations_header`
+
+    Injects code between the page header and the main content area for the integrations list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Status:</strong> Check integration health regularly.
+    </div>
+    ```
+
+</details>
+
+
+### Invitations
+
+<details>
+<summary>Invitations Actions</summary>
+
+`invitations_actions`
+
+    Injects code into the page actions area for the invitations list page.
+
+    ```erb
+    <%= link_to "Resend All Pending", resend_pending_invitations_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Invitations Header</summary>
+
+`invitations_header`
+
+    Injects code between the page header and the main content area for the invitations list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Expiry:</strong> Invitations expire after 7 days.
+    </div>
+    ```
+
+</details>
+
+
+### Option Types
+
+<details>
+<summary>Option Types Actions</summary>
+
+`option_types_actions`
+
+    Injects code into the page actions area for the option types list page.
+
+    ```erb
+    <%= link_to "Import Options", import_option_types_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Option Types Header</summary>
+
+`option_types_header`
+
+    Injects code between the page header and the main content area for the option types list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Variants:</strong> Option types are used to create product variants.
+    </div>
+    ```
+
+</details>
+
+
+### Pages
+
+<details>
+<summary>Pages Actions</summary>
+
+`pages_actions`
+
+    Injects code into the page actions area for the pages list page.
+
+    ```erb
+    <%= link_to "Export Content", export_pages_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Pages Header</summary>
+
+`pages_header`
+
+    Injects code between the page header and the main content area for the pages list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>SEO:</strong> Remember to optimize page content for search engines.
+    </div>
+    ```
+
+</details>
+
+
+### Payment Methods
+
+<details>
+<summary>Payment Methods Actions</summary>
+
+`payment_methods_actions`
+
+    Injects code into the page actions area for the payment methods list page.
+
+    ```erb
+    <%= link_to "Test All Gateways", test_payment_gateways_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Payment Methods Header</summary>
+
+`payment_methods_header`
+
+    Injects code between the page header and the main content area for the payment methods list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Configuration:</strong> Ensure all payment methods are properly configured.
+    </div>
+    ```
+
+</details>
+
+
+### Post Categories
+
+<details>
+<summary>Post Categories Actions</summary>
+
+`post_categories_actions`
+
+    Injects code into the page actions area for the post categories list page.
+
+    ```erb
+    <%= link_to "Reorder Categories", reorder_post_categories_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Post Categories Header</summary>
+
+`post_categories_header`
+
+    Injects code between the page header and the main content area for the post categories list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Organization:</strong> Use categories to organize your blog posts.
+    </div>
+    ```
+
+</details>
+
+
+### Posts
+
+<details>
+<summary>Posts Actions</summary>
+
+`posts_actions`
+
+    Injects code into the page actions area for the posts list page.
+
+    ```erb
+    <%= link_to "Schedule Posts", schedule_posts_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Posts Header</summary>
+
+`posts_header`
+
+    Injects code between the page header and the main content area for the posts list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Publishing:</strong> Posts can be scheduled for future publication.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Posts Filters</summary>
+
+`posts_filters`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the posts list filters.
+
+    ```erb
+    <%= f.spree_select :published_eq,
+        [["Published", true], ["Draft", false]],
+        { include_blank: true, label: "Publication Status" },
+        { data: { filters_target: :input } } %>
+    ```
+
+    > **TIP:** Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names.
+
+</details>
+
+
+### Promotions
+
+<details>
+<summary>Promotions Actions</summary>
+
+`promotions_actions`
+
+    Injects code into the page actions area for the promotions list page.
+
+    ```erb
+    <%= link_to "Clone Selected", clone_promotions_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Promotions Header</summary>
+
+`promotions_header`
+
+    Injects code between the page header and the main content area for the promotions list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Scheduling:</strong> Promotions can be scheduled to start and end automatically.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Promotions Filters</summary>
+
+`promotions_filters`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the promotions list filters.
+
+    ```erb
+    <%= f.spree_select :active_eq,
+        [["Active", true], ["Inactive", false]],
+        { include_blank: true, label: "Active Status" },
+        { data: { filters_target: :input } } %>
+    ```
+
+    > **TIP:** Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names.
+
+</details>
+
+
+### Properties
+
+<details>
+<summary>Properties Actions</summary>
+
+`properties_actions`
+
+    Injects code into the page actions area for the properties list page.
+
+    ```erb
+    <%= link_to "Import Properties", import_properties_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Properties Header</summary>
+
+`properties_header`
+
+    Injects code between the page header and the main content area for the properties list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Usage:</strong> Properties are used to add custom attributes to products.
+    </div>
+    ```
+
+</details>
+
+
+### Refund Reasons
+
+<details>
+<summary>Refund Reasons Actions</summary>
+
+`refund_reasons_actions`
+
+    Injects code into the page actions area for the refund reasons list page.
+
+    ```erb
+    <%= link_to "Export Reasons", export_refund_reasons_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Refund Reasons Header</summary>
+
+`refund_reasons_header`
+
+    Injects code between the page header and the main content area for the refund reasons list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Analytics:</strong> Track refund reasons to identify common issues.
+    </div>
+    ```
+
+</details>
+
+
+### Reimbursement Types
+
+<details>
+<summary>Reimbursement Types Actions</summary>
+
+`reimbursement_types_actions`
+
+    Injects code into the page actions area for the reimbursement types list page.
+
+    ```erb
+    <%= link_to "Configure Defaults", configure_reimbursement_defaults_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Reimbursement Types Header</summary>
+
+`reimbursement_types_header`
+
+    Injects code between the page header and the main content area for the reimbursement types list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Processing:</strong> Define how customers are reimbursed for returns.
+    </div>
+    ```
+
+</details>
+
+
+### Reports
+
+<details>
+<summary>Reports Actions</summary>
+
+`reports_actions`
+
+    Injects code into the page actions area for the reports list page.
+
+    ```erb
+    <%= link_to "Schedule Report", schedule_report_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Reports Header</summary>
+
+`reports_header`
+
+    Injects code between the page header and the main content area for the reports list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Automation:</strong> Reports can be scheduled to run automatically.
+    </div>
+    ```
+
+</details>
+
+
+### Return Authorization Reasons
+
+<details>
+<summary>Return Authorization Reasons Actions</summary>
+
+`return_authorization_reasons_actions`
+
+    Injects code into the page actions area for the return authorization reasons list page.
+
+    ```erb
+    <%= link_to "Export Reasons", export_return_reasons_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Return Authorization Reasons Header</summary>
+
+`return_authorization_reasons_header`
+
+    Injects code between the page header and the main content area for the return authorization reasons list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Policy:</strong> Define clear return reasons to streamline the process.
+    </div>
+    ```
+
+</details>
+
+
+### Return Authorizations
+
+<details>
+<summary>Return Authorizations Actions</summary>
+
+`return_authorizations_actions`
+
+    Injects code into the page actions area for the return authorizations list page.
+
+    ```erb
+    <%= link_to "Bulk Process", bulk_process_returns_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Return Authorizations Header</summary>
+
+`return_authorizations_header`
+
+    Injects code between the page header and the main content area for the return authorizations list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Processing:</strong> Returns are processed in order of submission.
+    </div>
+    ```
+
+</details>
+
+
+### Roles
+
+<details>
+<summary>Roles Actions</summary>
+
+`roles_actions`
+
+    Injects code into the page actions area for the roles list page.
+
+    ```erb
+    <%= link_to "Export Permissions", export_role_permissions_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Roles Header</summary>
+
+`roles_header`
+
+    Injects code between the page header and the main content area for the roles list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Security:</strong> Review role permissions regularly for security.
+    </div>
+    ```
+
+</details>
+
+
+### Shipping Categories
+
+<details>
+<summary>Shipping Categories Actions</summary>
+
+`shipping_categories_actions`
+
+    Injects code into the page actions area for the shipping categories list page.
+
+    ```erb
+    <%= link_to "Calculate Rates", calculate_shipping_rates_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Shipping Categories Header</summary>
+
+`shipping_categories_header`
+
+    Injects code between the page header and the main content area for the shipping categories list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Organization:</strong> Use categories to group products with similar shipping requirements.
+    </div>
+    ```
+
+</details>
+
+
+### Shipping Methods
+
+<details>
+<summary>Shipping Methods Actions</summary>
+
+`shipping_methods_actions`
+
+    Injects code into the page actions area for the shipping methods list page.
+
+    ```erb
+    <%= link_to "Test Integrations", test_shipping_integrations_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Shipping Methods Header</summary>
+
+`shipping_methods_header`
+
+    Injects code between the page header and the main content area for the shipping methods list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Configuration:</strong> Ensure shipping methods are properly configured for all zones.
+    </div>
+    ```
+
+</details>
+
+
+### Stock Locations
+
+<details>
+<summary>Stock Locations Actions</summary>
+
+`stock_locations_actions`
+
+    Injects code into the page actions area for the stock locations list page.
+
+    ```erb
+    <%= link_to "Sync Inventory", sync_all_locations_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Stock Locations Header</summary>
+
+`stock_locations_header`
+
+    Injects code between the page header and the main content area for the stock locations list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Management:</strong> Stock locations help manage inventory across multiple warehouses.
+    </div>
+    ```
+
+</details>
+
+
+### Stock Transfers
+
+<details>
+<summary>Stock Transfers Actions</summary>
+
+`stock_transfers_actions`
+
+    Injects code into the page actions area for the stock transfers list page.
+
+    ```erb
+    <%= link_to "Bulk Transfer", bulk_stock_transfer_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Stock Transfers Header</summary>
+
+`stock_transfers_header`
+
+    Injects code between the page header and the main content area for the stock transfers list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Tracking:</strong> All stock transfers are logged for audit purposes.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Stock Transfers Filters</summary>
+
+`stock_transfers_filters`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the stock transfers list filters.
+
+    ```erb
+    <%= f.spree_select :status_eq,
+        [["Pending", "pending"], ["Completed", "completed"]],
+        { include_blank: true, label: "Transfer Status" },
+        { data: { filters_target: :input } } %>
+    ```
+
+    > **TIP:** Use [ransack](/developer/core-concepts/search-filtering) search syntax for filter field names.
+
+</details>
+
+
+### Store Credit Categories
+
+<details>
+<summary>Store Credit Categories Actions</summary>
+
+`store_credit_categories_actions`
+
+    Injects code into the page actions area for the store credit categories list page.
+
+    ```erb
+    <%= link_to "Set Default Category", set_default_credit_category_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Store Credit Categories Header</summary>
+
+`store_credit_categories_header`
+
+    Injects code between the page header and the main content area for the store credit categories list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Organization:</strong> Use categories to organize different types of store credits.
+    </div>
+    ```
+
+</details>
+
+
+### Store Credits
+
+<details>
+<summary>Store Credits Actions</summary>
+
+`store_credits_actions`
+
+    Injects code into the page actions area for the store credits list page.
+
+    ```erb
+    <%= link_to "Bulk Issue Credits", bulk_issue_credits_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Store Credits Header</summary>
+
+`store_credits_header`
+
+    Injects code between the page header and the main content area for the store credits list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Management:</strong> Store credits can be issued for returns, promotions, or customer service.
+    </div>
+    ```
+
+</details>
+
+
+### Tax Categories
+
+<details>
+<summary>Tax Categories Actions</summary>
+
+`tax_categories_actions`
+
+    Injects code into the page actions area for the tax categories list page.
+
+    ```erb
+    <%= link_to "Update Tax Rates", update_all_tax_rates_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Tax Categories Header</summary>
+
+`tax_categories_header`
+
+    Injects code between the page header and the main content area for the tax categories list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Compliance:</strong> Ensure tax categories comply with local regulations.
+    </div>
+    ```
+
+</details>
+
+
+### Tax Rates
+
+<details>
+<summary>Tax Rates Actions</summary>
+
+`tax_rates_actions`
+
+    Injects code into the page actions area for the tax rates list page.
+
+    ```erb
+    <%= link_to "Import Tax Updates", import_tax_updates_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Tax Rates Header</summary>
+
+`tax_rates_header`
+
+    Injects code between the page header and the main content area for the tax rates list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Updates:</strong> Tax rates should be reviewed and updated regularly.
+    </div>
+    ```
+
+</details>
+
+
+### Taxonomies
+
+<details>
+<summary>Taxonomies Actions</summary>
+
+`taxonomies_actions`
+
+    Injects code into the page actions area for the taxonomies list page.
+
+    ```erb
+    <%= link_to "Rebuild Tree", rebuild_taxonomy_tree_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Taxonomies Header</summary>
+
+`taxonomies_header`
+
+    Injects code between the page header and the main content area for the taxonomies list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Navigation:</strong> Taxonomies are used to create product category navigation.
+    </div>
+    ```
+
+</details>
+
+
+### Themes
+
+<details>
+<summary>Themes Actions</summary>
+
+`themes_actions`
+
+    Injects code into the page actions area for the themes list page.
+
+    ```erb
+    <%= link_to "Preview All", preview_all_themes_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Themes Header</summary>
+
+`themes_header`
+
+    Injects code between the page header and the main content area for the themes list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Customization:</strong> Themes control the visual appearance of your storefront.
+    </div>
+    ```
+
+</details>
+
+
+### Webhooks Subscribers
+
+<details>
+<summary>Webhooks Subscribers Actions</summary>
+
+`webhooks_subscribers_actions`
+
+    Injects code into the page actions area for the webhooks subscribers list page.
+
+    ```erb
+    <%= link_to "Test All Webhooks", test_all_webhooks_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Webhooks Subscribers Header</summary>
+
+`webhooks_subscribers_header`
+
+    Injects code between the page header and the main content area for the webhooks subscribers list page.
+
+    ```erb
+    <div class="alert alert-warning">
+      <strong>Monitoring:</strong> Monitor webhook delivery status and failures.
+    </div>
+    ```
+
+</details>
+
+
+### Zones
+
+<details>
+<summary>Zones Actions</summary>
+
+`zones_actions`
+
+    Injects code into the page actions area for the zones list page.
+
+    ```erb
+    <%= link_to "Import Zones", import_zones_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Zones Header</summary>
+
+`zones_header`
+
+    Injects code between the page header and the main content area for the zones list page.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Geography:</strong> Zones define geographic regions for shipping and taxation.
+    </div>
+    ```
+
+</details>
+
+
+### Products
+
+<details>
+<summary>Products Actions</summary>
+
+`products_actions`
+
+    Injects code into the page actions area (top right of the page) for the products list page. This is useful for adding custom buttons, export options, or other actions.
+
+    ```erb
+    <%= link_to "Sync with PIM", sync_products_path, class: "btn btn-secondary" %>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Products Header</summary>
+
+`products_header`
+
+    Injects code between the page header and the main content area for the products list page. This is useful for adding notifications, alerts, or additional information.
+
+    ```erb
+    <div class="alert alert-info">
+      <strong>Inventory:</strong> Product inventory is synced with warehouse systems every 15 minutes.
+    </div>
+    ```
+
+</details>
+
+
+  <details>
+<summary>Products Filters</summary>
+
+`products_filters`
+
+    <img src="/images/developer/admin/products_filters.png" />
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    Injects code into the products list filters. This partial has access to the `f` variable, which is the form builder for the filters.
+
+    To add a new filter field, you can use the following code:
+
+    ```erb
+    <%= f.spree_text_field :q_name_cont, data: { filters_target: :input } %>
+    ```
+
+    > **TIP:** * `q_name_cont` is the name of the filter field. For filtering we're using [ransack](/developer/core-concepts/search-filtering) gem, so the name of the filter field is the name of the attribute we're filtering by.
+>     * `data: { filters_target: :input }` is needed for the [Stimulus Filters controller](https://github.com/spree/spree/blob/main/admin/app/javascript/spree/admin/controllers/filters_controller.js) to work.
+
+</details>
+
+
+  <details>
+<summary>Products Page Dropdown</summary>
+
+`product_dropdown`
+
+    <img src="/images/developer/admin/product_dropdown.png" />
+
+    Injects code into the products page dropdown. This partial has access to the `product` variable.
+
+    To add an additional dropdown item, you can use the following code:
+
+    ```erb
+    <%= link_to "View Product in WMS", "https://wms.com/products/#{product.id}", class: "dropdown-item", target: "_blank" %>
+    ```
+
+    > **INFO:** Your code will be placed before the dropdown divider.
+
+</details>
+
+
+  <details>
+<summary>Products Page Form</summary>
+
+`product_form`
+
+    <img src="/images/developer/admin/product_form.png" />
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    - **`product`** (`Spree::Product`) — The [Spree::Product](https://github.com/spree/spree/blob/main/core/app/models/spree/product.rb) object.
+
+    Injects code into the product form. This partial has access to the `f` variable, which is the form builder for the product form, and the `product` variable.
+
+    To add a new section to the product form, you can use the following code:
+
+    ```erb
+    <div class="card mb-6">
+      <div class="card-header">
+        <h5 class="card-title">ERP Integration</h5>
+      </div>
+      <div class="card-body">
+        <%= f.spree_text_field :erp_product_id %>
+      </div>
+    </div>
+    ```
+
+    > **INFO:** The partial will be displayed for both new product form and edit product form.
+
+    > **TIP:** If you want to display the partial only on the edit product form, you can use the following code:
+> 
+>       ```erb
+      <% if product.persisted? %>
+        <%# ... your code ... %>
+      <% end %>
+      ```
+> 
+>       And similarly for the new product form.
+> 
+>       ```erb
+      <% if product.new_record? %>
+        <%# ... your code ... %>
+      <% end %>
+      ```
+
+</details>
+
+
+  <details>
+<summary>Products Page Sidebar</summary>
+
+`product_form_sidebar`
+
+    <img src="/images/developer/admin/product_form_sidebar.png" />
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    - **`product`** (`Spree::Product`) — The [Spree::Product](https://github.com/spree/spree/blob/main/core/app/models/spree/product.rb) object.
+
+    Injects code into the product form sidebar. This partial has access to the `f` variable, which is the form builder for the product form, and the `product` variable.
+
+    To add a new section to the product form sidebar, you can use the following code:
+
+    ```erb
+    <div class="card mb-6">
+      <div class="card-header">
+        <h5 class="card-title">ERP Integration</h5>
+      </div>
+      <div class="card-body">
+        <%= f.spree_text_field :erp_product_id %>
+      </div>
+    </div>
+    ```
+
+    > **INFO:** The partial will be displayed for both new product form and edit product form.
+
+    > **TIP:** If you want to display the partial only on the edit product form, you can use the following code:
+> 
+>       ```erb
+      <% if product.persisted? %>
+        <%# ... your code ... %>
+      <% end %>
+      ```
+> 
+>       And similarly for the new product form.
+> 
+>       ```erb
+      <% if product.new_record? %>
+        <%# ... your code ... %>
+      <% end %>
+      ```
+
+</details>
+
+
+### Shipping Methods
+
+<details>
+<summary>Shipping Methods Form</summary>
+
+`shipping_method_form`
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    - **`shipping_method`** (`Spree::ShippingMethod`) — The [Spree::ShippingMethod](https://github.com/spree/spree/blob/main/core/app/models/spree/shipping_method.rb) object.
+
+    Injects code into the shipping method form. This partial has access to the `f` variable, which is the form builder for the shipping method form, and the `shipping_method` variable.
+
+    To add a new section to the shipping method form, you can use the following code:
+
+    ```erb
+    <div class="card mb-6">
+      <div class="card-header">
+        <h5 class="card-title">ERP Integration</h5>
+      </div>
+      <div class="card-body">
+        <%= f.spree_text_field :erp_shipping_method_id %>
+      </div>
+    </div>
+    ```
+
+</details>
+
+
+### Store Settings
+
+<details>
+<summary>Store Settings Form</summary>
+
+`store_form`
+
+    <img src="/images/developer/admin/store_form.png" />
+
+    #### Variables
+
+    - **`f`** (`Spree::Admin::FormBuilder`) — The [Spree::Admin::FormBuilder](/developer/admin/form-builder) object.
+
+    - **`store`** (`Spree::Store`) — The [Spree::Store](https://github.com/spree/spree/blob/main/core/app/models/spree/store.rb) object.
+
+    Injects code into the store settings form. This partial has access to the `f` variable, which is the form builder for the store form, and the `store` variable.
+
+    To add a new section to the store form, you can use the following code:
+
+    ```erb
+    <div class="card mb-6">
+      <div class="card-header">
+        <h5 class="card-title">ERP Integration</h5>
+      </div>
+      <div class="card-body">
+        <%= f.spree_text_field :erp_store_id %>
+      </div>
+    </div>
+    ```
+
+</details>
+
+
+## Related Documentation
+
+- [Admin Navigation](/developer/admin/navigation) - Add custom menu items to the admin
+- [Admin Tables](/developer/admin/tables) - Customize admin list views
+- [Form Builder](/developer/admin/form-builder) - Build admin forms with Spree's form helpers
+- [Customization Quickstart](/developer/customization/quickstart) - Overview of all customization options