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 the attribute-end-to-end recipe

Damian Legawiec23d7433a82ee
diff --git a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
new file mode 100644
index 0000000000..758399f90e
--- /dev/null
+++ b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx
@@ -0,0 +1,208 @@
+---
+title: "A product attribute, end to end: form, table, filters, sort"
+sidebarTitle: Attribute end-to-end
+description: Take one custom product attribute all the way — editable on the product form, visible as a table column, filterable and sortable in the products list.
+---
+
+This recipe adds a **supplier lead time** (`lead_time_days`, an integer) to products and wires it through every surface the dashboard has:
+
+- edited on the product form, saved by the form's own Save button
+- a column in the products table
+- a filter ("lead time > 7 days") and a sort ("slowest first") in the list toolbar
+
+It's the full version of the [custom form field recipe](/developer/dashboard/recipes/custom-form-field) — read that one first if you only need the form.
+
+## First: should this be a custom field instead?
+
+**Default to a [custom field definition](/developer/dashboard/recipes/custom-form-field#path-a-custom-field-definition--no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.
+
+Graduate to a real database column only when the attribute needs **list operations or database guarantees**:
+
+| You need… | Custom field | Real column |
+|---|---|---|
+| Editing on the product form | ✅ zero code | ✅ this recipe |
+| Filtering / sorting the products list | ❌ | ✅ via Ransack |
+| A database index, Rails validations, queries in Ruby | ❌ | ✅ |
+| Merchants defining the field themselves at runtime | ✅ | ❌ |
+
+Lead time is a column because its whole point is the query: *"show me everything that ships slow, slowest first."*
+
+## 1. Backend
+
+Four small pieces — each one unlocks a specific frontend capability. In a host app these live in `backend/` (or `api/`); in a distributed plugin, in the Rails engine half.
+
+**The column** (with an index — you're adding it *because* it will be queried):
+
+```ruby
+class AddLeadTimeDaysToSpreeProducts < ActiveRecord::Migration[7.2]
+ def change
+ add_column :spree_products, :lead_time_days, :integer
+ add_index :spree_products, :lead_time_days
+ end
+end
+```
+
+**The serializer** — makes the attribute *readable* (hydrates the form, renders the table cell):
+
+```ruby
+# app/serializers/my_plugin/product_serializer.rb
+module MyPlugin
+ class ProductSerializer < Spree::Api::V3::Admin::ProductSerializer
+ typelize lead_time_days: 'number | null'
+ attributes :lead_time_days
+ end
+end
+
+# config/initializers/spree.rb
+Spree.api.admin_product_serializer = 'MyPlugin::ProductSerializer'
+```
+
+**The permitted param** — makes it *writable* (the form's Save ships it in the same PATCH as core fields). The read and write names must match:
+
+```ruby
+# app/controllers/my_plugin/products_controller_decorator.rb
+module MyPlugin
+ module ProductsControllerDecorator
+ def permitted_params
+ super.merge(params.permit(:lead_time_days))
+ end
+ end
+end
+Spree::Api::V3::Admin::ProductsController.prepend(MyPlugin::ProductsControllerDecorator)
+```
+
+**The Ransack allowlist** — makes it *filterable and sortable*. Both the list's sort param and every filter predicate go through Ransack, and Ransack refuses attributes that aren't allowlisted:
+
+```ruby
+# config/initializers/spree.rb
+Spree::Product.whitelisted_ransackable_attributes |= %w[lead_time_days]
+```
+
+Add a Rails validation while you're here (`validates :lead_time_days, numericality: { greater_than_or_equal_to: 0, allow_nil: true }`) — it's the authoritative validation, and the dashboard renders its 422 message inline on the field automatically.
+
+## 2. Frontend — one declaration
+
+```tsx
+// src/plugins.ts (or a plugin's entry module)
+import { defineDashboardPlugin, i18n } from '@spree/dashboard-core'
+import { LeadTimeCard } from './fields/lead-time-card'
+import en from './locales/en.json'
+
+i18n.addResourceBundle('en', 'translation', en, true, true)
+
+defineDashboardPlugin({
+ // Form: hydrate from the fetched product, save with the form's own Save.
+ formFields: {
+ product: [{ name: 'lead_time_days', from: (p) => p?.lead_time_days ?? null }],
+ },
+ slots: {
+ 'product.form_sidebar': [{ id: 'lead-time', component: LeadTimeCard as never, position: 60 }],
+ },
+
+ // Table: column + filter + sort in one ColumnDef.
+ tables: {
+ products: {
+ add: [{
+ key: 'lead_time_days',
+ label: i18n.t('admin.fields.product.lead_time_days.label'),
+ sortable: true, // header click → server-side sort via Ransack
+ filterable: true, // appears in the filter panel
+ filterType: 'number', // numeric operator set: =, ≠, >, <, ranges
+ default: true, // visible out of the box (false = opt-in via column picker)
+ render: (product) => (product.lead_time_days != null ? `${product.lead_time_days} d` : '—'),
+ }],
+ },
+ },
+})
+```
+
+The form widget binds to the host form — no `<form>` of its own, no save button:
+
+```tsx
+// src/fields/lead-time-card.tsx
+import { useHostForm } from '@spree/dashboard-core'
+import { Card, CardContent, CardHeader, CardTitle, Field, FieldError, FieldLabel, Input } from '@spree/dashboard-ui'
+import { useTranslation } from 'react-i18next'
+
+export function LeadTimeCard() {
+ const { t } = useTranslation()
+ const form = useHostForm<{ lead_time_days: number | null }>()
+ const error = form.formState.errors.lead_time_days?.message
+
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('admin.fields.product.lead_time_days.label')}</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <Field>
+ <FieldLabel className="sr-only" htmlFor="lead_time_days">
+ {t('admin.fields.product.lead_time_days.label')}
+ </FieldLabel>
+ <Input
+ id="lead_time_days"
+ type="number"
+ min={0}
+ placeholder={t('admin.fields.product.lead_time_days.placeholder')}
+ aria-invalid={Boolean(error)}
+ {...form.register('lead_time_days', {
+ // Empty input → null (not NaN, not "") so the API gets a clean value.
+ setValueAs: (v) => (v === '' || v == null ? null : Number(v)),
+ })}
+ />
+ {error && <FieldError>{error as string}</FieldError>}
+ </Field>
+ </CardContent>
+ </Card>
+ )
+}
+```
+
+```json
+// src/locales/en.json — note the top-level "admin" wrapper
+{
+ "admin": {
+ "fields": {
+ "product": {
+ "lead_time_days": {
+ "label": "Lead time (days)",
+ "placeholder": "e.g. 14"
+ }
+ }
+ }
+ }
+}
+```
+
+## 3. Verify it
+
+API first — the fastest way to confirm the backend pieces:
+
+```bash
+# write (permitted param + validation)
+npx spree api patch products/prod_xxx --data '{"lead_time_days": 14}'
+
+# filter + sort (Ransack allowlist)
+npx spree api get "products?q[lead_time_days_gt]=7&sort=-lead_time_days"
+```
+
+Then the UI: open a product — the Lead time card sits in the sidebar; edit it and the page's Save button arms; save and reload. On the products list the column renders, the header sorts, and the filter panel offers the numeric operators. Filters and sort round-trip through the URL — a filtered view is shareable — and a CSV export of the filtered list respects your filter, because the export stores the same Ransack predicate hash.
+
+## How the pieces map
+
+| Frontend behavior | Made possible by |
+|---|---|
+| Form input hydrates + saves with the page | serializer attribute + permitted param + `formFields`/`useHostForm` |
+| Table cell renders | serializer attribute + `ColumnDef.render` |
+| Header sort works | `sortable: true` + Ransack allowlist |
+| Filter panel entry works | `filterable: true` + `filterType` + Ransack allowlist |
+| Inline validation message | the Rails validation (422 → mapped onto the field) |
+
+Two `ColumnDef` extras worth knowing: `ransackAttribute` points the predicate somewhere other than the column key (the built-in `sku` column filters through `master_sku`), and `displayable: false` makes a filter-only field that never renders as a column.
+
+## Reference
+
+- [Custom form field recipe](/developer/dashboard/recipes/custom-form-field) — the form layer in isolation, and the custom-field-definition path
+- [Tables](/developer/dashboard/customization/tables) — the full `ColumnDef` and table registry API
+- [Backend integration](/developer/dashboard/customization/backend) — serializers, permitted params, error mapping
+- [Decorators](/developer/customization/decorators) — the `prepend` pattern used for the controller
diff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdx
index 5ecea89706..b96f2d6652 100644
--- a/docs/developer/dashboard/recipes/custom-form-field.mdx
+++ b/docs/developer/dashboard/recipes/custom-form-field.mdx
@@ -162,6 +162,10 @@ Extension fields are validated by the **server** — a Rails validation failing
| A real column with Rails validations, queries, or indexes | **B** |
| The field belongs visually inside your own card with other UI | **B** |
+## Going further
+
+To also surface the attribute as a **table column with filtering and sorting**, continue with [A product attribute, end to end](/developer/dashboard/recipes/attribute-end-to-end).
+
## Reference
- [Custom fields](/developer/customization/metadata) — definitions, types, the API
diff --git a/docs/docs.json b/docs/docs.json
index c53ba549fd..5967e27891 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -417,6 +417,7 @@
{
"group": "Recipes",
"pages": [
+ "developer/dashboard/recipes/attribute-end-to-end",
"developer/dashboard/recipes/custom-form-field",
"developer/dashboard/recipes/page-action-button",
"developer/dashboard/recipes/sidebar-widget"