@spree/docs 0.1.234 → 0.1.235
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.
|
@@ -23,20 +23,38 @@ A role with `mutable: false` (set from seeds or the console) renders read-only i
|
|
|
23
23
|
|
|
24
24
|
## Registering extension permissions
|
|
25
25
|
|
|
26
|
-
Register your models as a catalog
|
|
26
|
+
Register your models as a catalog scope once; the keys appear in the role editor and become mintable API-key scopes with no further wiring:
|
|
27
27
|
|
|
28
28
|
```ruby
|
|
29
29
|
# in your engine's initializer
|
|
30
|
-
Spree.permissions.
|
|
30
|
+
Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> {
|
|
31
31
|
[SpreeReviews::Review]
|
|
32
32
|
})
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
- `group` places the row in the permission pickers (`:orders`, `:catalog`, `:
|
|
36
|
-
- `
|
|
37
|
-
- Pass `write: false` for read-only
|
|
35
|
+
- `group` places the row in the permission pickers (`:analytics`, `:orders`, `:catalog`, `:customers`, `:sellers`, `:loyalty`, `:marketing`, `:settings`, `:access` — or your own). Rows render in registration order, so a scope registered from an initializer lands after core's.
|
|
36
|
+
- `resources` is a lambda returning the CanCanCan subjects the keys grant; it resolves lazily, so load order does not matter.
|
|
37
|
+
- Pass `write: false` for read-only scopes.
|
|
38
38
|
|
|
39
|
-
Localize the labels in your engine's locale file under `spree.permissions_catalog.resources.<name>` (`label` and `description`), and declare the same
|
|
39
|
+
Localize the labels in your engine's locale file under `spree.permissions_catalog.resources.<name>` (`label` and `description`), and declare the same scope on your admin controllers with `scoped_resource :reviews`.
|
|
40
|
+
|
|
41
|
+
## Who may hold a key
|
|
42
|
+
|
|
43
|
+
`audiences` is the complete list of audiences whose roles may hold a scope's keys. The store's own back office is `:store`, and is the list when a registration names none — so the example above is grantable to staff and nobody else.
|
|
44
|
+
|
|
45
|
+
```ruby
|
|
46
|
+
# Staff configure the marketplace's; a seller configures their own.
|
|
47
|
+
Spree.permissions.register_scope(:reviews, group: :catalog, audiences: %i[store seller], resources: -> {
|
|
48
|
+
[SpreeReviews::Review]
|
|
49
|
+
})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Naming another audience exposes the scope to a principal outside the store's own staff, so it is always a deliberate act. Two consequences worth knowing:
|
|
53
|
+
|
|
54
|
+
- **Leaving `:store` out** keeps the scope off the staff permission picker, out of `read_all` / `write_all`, and unmintable on a secret API key — which is how a seller panel's own scopes (`seller_profile`, `seller_earnings`) exist without a store role ever being offered them.
|
|
55
|
+
- **`read_only_for: %i[seller]`** gives that audience the read key alone, for a vocabulary they consult but do not own.
|
|
56
|
+
|
|
57
|
+
A key never decides *which rows* its holder reaches. That is the controller's job, through scope fetching — a seller holding `write_products` manages their own products because the seller API reads through `current_seller`, not because the key says so.
|
|
40
58
|
|
|
41
59
|
## Beyond the catalog
|
|
42
60
|
|
|
@@ -103,7 +103,7 @@ The same `permissions` object backs the nav registry's `if` predicate, so you ca
|
|
|
103
103
|
|
|
104
104
|
## Custom permissions
|
|
105
105
|
|
|
106
|
-
If your customization introduces a new model on the backend, register it as a permission catalog
|
|
106
|
+
If your customization introduces a new model on the backend, register it as a permission catalog scope there (`Spree.permissions.register_scope` in your engine's initializer). Its keys then appear in the role editor and the API-key scope picker, and any role granted them makes `permissions.can('read', 'MyApp::Report')` resolve in the dashboard exactly like a first-party check — the abilities ship with the current-user response (`GET /api/v3/admin/me`) at sign-in, alongside `permission_keys`, the flat key list the role editor grants from.
|
|
107
107
|
|
|
108
108
|
## Reference
|
|
109
109
|
|
|
@@ -671,7 +671,7 @@ Spree::Role.find_or_create_by!(name: 'support')
|
|
|
671
671
|
Storefront customers are not part of this system: the old `:default` role and `DefaultCustomer` set are gone, customers never resolve roles, and the Store API no longer consults CanCanCan at all — customer authorization is ownership-scoped queries plus `Spree::Storefront::AccessPolicy` (swappable via `Spree::Dependencies.storefront_access_policy_class`). If an extension added storefront `can` rules, move them into an access-policy subclass or a checkout workflow `validate` hook. Extensions register their resources into the catalog once, which makes them grantable to roles **and** mintable as API-key scopes:
|
|
672
672
|
|
|
673
673
|
```ruby
|
|
674
|
-
Spree.permissions.
|
|
674
|
+
Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> { [SpreeReviews::Review] })
|
|
675
675
|
```
|
|
676
676
|
|
|
677
677
|
Two enforcement changes on the Admin API:
|