@spree/docs 0.1.138 → 0.1.140
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -33,6 +33,8 @@ erDiagram
|
|
|
33
33
|
string metafield_type
|
|
34
34
|
string resource_type
|
|
35
35
|
string display_on
|
|
36
|
+
boolean searchable
|
|
37
|
+
boolean sortable
|
|
36
38
|
}
|
|
37
39
|
|
|
38
40
|
Metafield {
|
|
@@ -83,6 +85,40 @@ Metafields support two visibility levels via the `display_on` attribute:
|
|
|
83
85
|
| `both` | Yes | Yes | Public product specifications |
|
|
84
86
|
| `back_end` | No | Yes | Internal notes, integration IDs |
|
|
85
87
|
|
|
88
|
+
## Search, sort & filter
|
|
89
|
+
|
|
90
|
+
Product metafield definitions can opt into SearchProvider participation:
|
|
91
|
+
|
|
92
|
+
| Flag | Effect | Allowed field types |
|
|
93
|
+
|------|--------|---------------------|
|
|
94
|
+
| `searchable` | Values are included in product text search | `short_text`, `long_text`, `number` |
|
|
95
|
+
| `sortable` | Listings can sort with `sort=cf_{namespace}_{key}` (prefix `-` for descending), e.g. `cf_custom_label` | `short_text`, `number` |
|
|
96
|
+
|
|
97
|
+
Both default to `false`. Set them on the definition (Admin UI, Admin API, or seeds). For an existing catalog with Meilisearch, run `rake spree:search:reindex` after toggling flags so index settings and product documents pick up new `cf_*` fields.
|
|
98
|
+
|
|
99
|
+
### Filtering
|
|
100
|
+
|
|
101
|
+
Any definition with either flag set also becomes filterable on product listings, using its `cf_*` key as a Ransack predicate. The Store and Admin APIs accept the same keys and the same `sort` values:
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
GET /api/v3/store/products?q[cf_custom_material_i_cont]=wool
|
|
105
|
+
GET /api/v3/admin/products?q[cf_custom_weight_gteq]=3.5
|
|
106
|
+
GET /api/v3/store/products?sort=-cf_custom_weight
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
| Field type | Predicates |
|
|
110
|
+
|------------|------------|
|
|
111
|
+
| `short_text`, `long_text` | `i_cont`, `cont`, `eq`, `not_eq`, `start`, `end`, `present`, `blank` |
|
|
112
|
+
| `number` | `eq`, `gt`, `gteq`, `lt`, `lteq`, `present`, `blank` |
|
|
113
|
+
|
|
114
|
+
Use `i_cont` for case-insensitive matching — plain `cont` is case-sensitive on PostgreSQL.
|
|
115
|
+
|
|
116
|
+
Predicates that don't match the definition's field type are ignored rather than rejected, as are keys matching no definition. Meilisearch supports the equality, range, and `present`/`blank` predicates; substring predicates (`i_cont`, `cont`, `start`, `end`) apply only to the database provider.
|
|
117
|
+
|
|
118
|
+
CSV exports honor the same predicates, so exporting a filtered product list matches what the admin sees.
|
|
119
|
+
|
|
120
|
+
In the admin dashboard, these fields appear in the products table's column selector, Sort dropdown, and filter panel — hidden by default, so admins opt in per column.
|
|
121
|
+
|
|
86
122
|
## Supported Resources
|
|
87
123
|
|
|
88
124
|
Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.
|
|
@@ -9,11 +9,11 @@ import { Since } from '/snippets/since.mdx';
|
|
|
9
9
|
|
|
10
10
|
Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
|
|
11
11
|
|
|
12
|
-
- Full-text search across product names and
|
|
12
|
+
- Full-text search across product names, SKUs, and searchable product metafields
|
|
13
13
|
- Attribute-based filtering (price range, availability, stock status)
|
|
14
14
|
- Category and taxon filtering
|
|
15
15
|
- Faceted search with filter counts
|
|
16
|
-
- Flexible sorting options
|
|
16
|
+
- Flexible sorting options (including sortable product custom fields via `sort=cf_{namespace}_{key}`)
|
|
17
17
|
|
|
18
18
|
## Product Search
|
|
19
19
|
|
|
@@ -156,6 +156,7 @@ const sorted = await client.products.list({
|
|
|
156
156
|
|
|
157
157
|
// Available sort options (prefix '-' for descending; use '-available_on' for newest):
|
|
158
158
|
// price, -price, name, -name, available_on, -available_on, best_selling
|
|
159
|
+
// Plus any product custom field marked sortable, e.g. cf_custom_label / -cf_custom_label
|
|
159
160
|
```
|
|
160
161
|
|
|
161
162
|
```typescript Admin SDK
|
|
@@ -224,6 +224,12 @@ Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_
|
|
|
224
224
|
|
|
225
225
|
Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.
|
|
226
226
|
|
|
227
|
+
### Metafield search schema
|
|
228
|
+
|
|
229
|
+
Product metafields marked `searchable` / `sortable` on `MetafieldDefinition` are projected through `Spree::SearchProvider::MetafieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.
|
|
230
|
+
|
|
231
|
+
Document shaping for `cf_*` fields stays on `search_product_presenter` — the only search-related dependency.
|
|
232
|
+
|
|
227
233
|
## Related Documentation
|
|
228
234
|
|
|
229
235
|
- [Search & Filtering](../core-concepts/search-filtering.md) — Store API search reference
|