Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add 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.mdxnew file mode 100644index 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 controllerdiff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdxindex 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 APIdiff --git a/docs/docs.json b/docs/docs.jsonindex 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"