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.

Documented how to expose a preference in the API

Damian Legawiecf04e05d475ea
diff --git a/docs/developer/customization/model-preferences.mdx b/docs/developer/customization/model-preferences.mdx
index 32ffe2228d..d1aa8d9f19 100644
--- a/docs/developer/customization/model-preferences.mdx
+++ b/docs/developer/customization/model-preferences.mdx
@@ -94,7 +94,83 @@ The SDKs also type the settings of every type Spree ships. `TypedPromotionRule`
A write is checked against the schema before anything is saved. An unknown key, a value of the wrong type, a value outside `choices`, or an id of the wrong model or another store is refused with a `422` whose `code` is `invalid_preferences`; `details` names each failing value by its JSON pointer, such as `/preferences/channel_ids/1`. A secret reads back masked; sending the masked value back keeps the stored secret, and `null` clears it.
-Settings of a single resource, such as the store's, are read and written under their plain names (`guest_checkout`, `timezone`), never the `preferred_` methods. A model gives a preference that name with `exposes_preferences :guest_checkout, :timezone`, which defines `guest_checkout`, `guest_checkout=` and `guest_checkout?`; the API controller still lists what it accepts.
+### Exposing a setting in the API
+
+Use this when a record has a fixed set of settings that clients edit field by field, as the store, a channel or an import do. A family of types with different settings per type (rules, calculators, payment methods) sends a `preferences` object instead, as described above.
+
+The API names such a setting by its plain name (`featured`), never by the `preferred_` method. It takes three declarations, one per layer, and each layer stays in charge of its own job.
+
+**1. Expose it on the model.** `exposes_preferences` gives each preference a plain reader, writer and predicate:
+
+```ruby server/app/models/spree/brand.rb
+module Spree
+ class Brand < Spree.base_class
+ preference :featured, :boolean, default: false
+ preference :display_name, :string
+
+ exposes_preferences :featured, :display_name
+ end
+end
+```
+
+```ruby
+brand.featured # same as brand.preferred_featured
+brand.featured = true # same as brand.preferred_featured = true
+brand.featured? # true
+```
+
+It refuses a name the model already uses for something else. Errors on `preferred_featured` are reported to API clients as `featured`.
+
+**2. Return it from the serializer.** `preference_attributes` adds every exposed preference, typed from its declaration, so the generated SDK types follow the model. Name some to add only those, or pass `except:` to leave some out:
+
+```ruby server/app/serializers/spree/api/v3/admin/brand_serializer.rb
+module Spree
+ module Api
+ module V3
+ module Admin
+ class BrandSerializer < Spree::Api::V3::BaseSerializer
+ attributes :name, created_at: :iso8601, updated_at: :iso8601
+
+ preference_attributes Spree::Brand
+ end
+ end
+ end
+ end
+end
+```
+
+**3. Accept it in the controller.** Exposing a setting does not make it writable: the controller decides, as for any attribute (see [permitted attributes](/developer/customization/api#permitted-attributes)):
+
+```ruby server/app/controllers/spree/api/v3/admin/brands_controller.rb
+def resource_permitted_attributes
+ [:name, :featured, :display_name]
+end
+```
+
+The setting is then read and written like a column:
+
+<Tabs>
+ <Tab title="Admin SDK">
+ ```typescript
+ const brand = await adminClient.request('PATCH', `/brands/${brandId}`, {
+ body: { featured: true, display_name: 'Wilson' },
+ })
+ brand.featured // true
+ ```
+ </Tab>
+ <Tab title="cURL">
+ ```bash
+ curl -X PATCH 'https://api.mystore.com/api/v3/admin/brands/brand_xxx' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "featured": true, "display_name": "Wilson" }'
+ ```
+ </Tab>
+</Tabs>
+
+<Note>
+ The Seller API keeps its own list of what sellers may write, so exposing a setting to operators never makes it writable by sellers.
+</Note>
Strings, integers and booleans are cast the way Rails casts attributes (`"1"`, `"true"` and `"on"` are true; `"42"` is 42). A blank value is `nil` for a `nullable: true` preference, and the type's empty value otherwise.