@seamware/odrl-policy-editor 1.8.1 → 1.9.0-PRE-66.51
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.
- package/README.md +94 -4
- package/dist-component/odrl-policy-editor.d.ts +19 -10
- package/dist-component/odrl-policy-editor.js +6540 -6517
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -339,7 +339,7 @@ at runtime triggers a re-render automatically.
|
|
|
339
339
|
| `hide-cancel-button` | Boolean — hides the Cancel button (e.g. when the host provides its own) | absent (visible) |
|
|
340
340
|
| `variant` | `"card"` \| `"plain"` — editor framed as a card, or with no chrome | `"card"` |
|
|
341
341
|
| `load` | `"remote"` \| `"none"` — fetch the policy when `mode="edit"` | `"remote"` |
|
|
342
|
-
| `save` | `"remote"` \| `"none"` — store the policy in the PAP
|
|
342
|
+
| `save` | `"remote"` \| `"event"` \| `"none"` — store the policy in the PAP, hand it to the host instead (see [Emit-Only Mode](#emit-only-mode-saveevent)), or remove the Save button | `"remote"` |
|
|
343
343
|
| `validate` | `"remote"` \| `"none"` — validate against the PAP; `none` removes the Validate button and panel | `"remote"` |
|
|
344
344
|
| `templates` | `"remote"` \| `"none"` — list and manage PAP templates; `none` removes both template tabs | `"remote"` |
|
|
345
345
|
| `mappings` | `"remote"` \| `"none"` — fetch the visual builder's dropdown mappings | `"remote"` |
|
|
@@ -430,7 +430,11 @@ over the host page.
|
|
|
430
430
|
`load`, `save`, `validate`, `templates` and `mappings` decide, one by one,
|
|
431
431
|
whether the editor talks to the PAP. Each defaults to `remote` (the behaviour
|
|
432
432
|
of earlier versions); `none` makes no request and hides the UI that depends on
|
|
433
|
-
it.
|
|
433
|
+
it. `save` has a third mode, `event`, which keeps the Save button but hands
|
|
434
|
+
the finished policy to the host instead of writing it — see
|
|
435
|
+
[Emit-Only Mode](#emit-only-mode-saveevent). Unknown values, and modes a
|
|
436
|
+
capability does not support, fall back to `remote`, so a typo never silently
|
|
437
|
+
disables (or silently enables) a backend call.
|
|
434
438
|
|
|
435
439
|
Used as a form control — the host owns the policy and nothing goes to the PAP:
|
|
436
440
|
|
|
@@ -454,6 +458,11 @@ entry with the same `name` replaces the built-in one. Mappings an operator adds
|
|
|
454
458
|
through the PAP's `paths.mapping` are only visible with `mappings="remote"`. With `save="none"`,
|
|
455
459
|
filling in a template loads the result into the editor instead of storing it.
|
|
456
460
|
|
|
461
|
+
Because the capability modes are string attributes, framework bindings work as
|
|
462
|
+
written: React's `<odrl-policy-editor save="event" />`, Angular's
|
|
463
|
+
`[attr.save]="'event'"` and Vue's `:save="'event'"` all set the attribute the
|
|
464
|
+
element reads.
|
|
465
|
+
|
|
457
466
|
### JavaScript Properties
|
|
458
467
|
|
|
459
468
|
For richer configuration that cannot be expressed as string attributes, use
|
|
@@ -511,8 +520,8 @@ Events bubble and cross Shadow DOM boundaries (`composed: true`).
|
|
|
511
520
|
|
|
512
521
|
| Event | Detail payload | Fired when |
|
|
513
522
|
|--------------------|---------------------------------------------|----------------------------------|
|
|
514
|
-
| `policy-created` | `{ policy: OdrlPolicyJson, id: string }`
|
|
515
|
-
| `policy-updated` | `{ policy: OdrlPolicyJson, id: string }`
|
|
523
|
+
| `policy-created` | `{ policy: OdrlPolicyJson, id: string, persisted: boolean }` | A new policy is saved (or, with `save="event"`, completed) |
|
|
524
|
+
| `policy-updated` | `{ policy: OdrlPolicyJson, id: string, persisted: boolean }` | An existing policy is updated |
|
|
516
525
|
| `policy-validated` | `{ result: ValidationResponse }` | Policy validation completes |
|
|
517
526
|
| `editor-cancelled` | `{}` | The user clicks Cancel |
|
|
518
527
|
| `template-created` | `{ template: object, id: string }` | A new template is created in the management tab |
|
|
@@ -538,6 +547,87 @@ editor.addEventListener('editor-cancelled', () => {
|
|
|
538
547
|
});
|
|
539
548
|
```
|
|
540
549
|
|
|
550
|
+
### Emit-Only Mode (`save="event"`)
|
|
551
|
+
|
|
552
|
+
By default the editor stores a policy in the PAP and *then* emits
|
|
553
|
+
`policy-created` / `policy-updated`. Set `save="event"` to turn the component
|
|
554
|
+
into a pure policy *builder*: the user configures the policy as usual, but on
|
|
555
|
+
Save nothing is written — the finished ODRL JSON is handed to the host
|
|
556
|
+
application through the very same events, with `detail.persisted === false`.
|
|
557
|
+
|
|
558
|
+
`save` is one of the [capability modes](#capability-modes): `"remote"` (the
|
|
559
|
+
default) writes to the PAP, `"event"` emits instead, `"none"` removes the Save
|
|
560
|
+
button altogether.
|
|
561
|
+
|
|
562
|
+
```html
|
|
563
|
+
<odrl-policy-editor
|
|
564
|
+
id="editor"
|
|
565
|
+
api-base-url="https://pap.example.com"
|
|
566
|
+
save="event"
|
|
567
|
+
></odrl-policy-editor>
|
|
568
|
+
|
|
569
|
+
<script>
|
|
570
|
+
document.getElementById('editor').addEventListener('policy-created', (e) => {
|
|
571
|
+
// e.detail.persisted === false — the PAP has not stored anything
|
|
572
|
+
console.log('Policy built:', e.detail.policy);
|
|
573
|
+
console.log('Suggested id:', e.detail.id); // derived from the odrl:uid
|
|
574
|
+
myOwnBackend.save(e.detail.id, e.detail.policy);
|
|
575
|
+
});
|
|
576
|
+
</script>
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
Because listener code is identical in all modes, switching between them is a
|
|
580
|
+
single attribute change — check `detail.persisted` if the host needs to tell
|
|
581
|
+
them apart.
|
|
582
|
+
|
|
583
|
+
**Editing a policy the host stores itself**
|
|
584
|
+
|
|
585
|
+
`save="event"` only governs writing. With `mode="edit"` the editor would still
|
|
586
|
+
*load* the policy from the PAP, which 404s for a policy the host keeps in its
|
|
587
|
+
own store. Combine it with `load="none"` and hand the policy in through the
|
|
588
|
+
`policy` JS property:
|
|
589
|
+
|
|
590
|
+
```javascript
|
|
591
|
+
const editor = document.querySelector('odrl-policy-editor');
|
|
592
|
+
editor.setAttribute('mode', 'edit');
|
|
593
|
+
editor.setAttribute('load', 'none');
|
|
594
|
+
editor.setAttribute('save', 'event');
|
|
595
|
+
|
|
596
|
+
// The host supplies the policy; the property accepts an object or JSON text.
|
|
597
|
+
editor.policy = await myOwnBackend.load(id);
|
|
598
|
+
|
|
599
|
+
editor.addEventListener('policy-updated', (e) => {
|
|
600
|
+
myOwnBackend.save(e.detail.id, e.detail.policy);
|
|
601
|
+
});
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
**What emit-only mode changes**
|
|
605
|
+
|
|
606
|
+
| Behaviour | `save="remote"` (default) | `save="event"` | `save="none"` |
|
|
607
|
+
|-----------|---------------------------|----------------|---------------|
|
|
608
|
+
| Save button | `PUT /policy/{id}` (or the service-scoped variant), then event | event only | not rendered |
|
|
609
|
+
| Create from template | stores, then event | event only | policy adopted into the editor, `policy-changed` only |
|
|
610
|
+
| `detail.persisted` | `true` | `false` | — |
|
|
611
|
+
|
|
612
|
+
**What it does not change** — `save="event"` suppresses *policy writes* only.
|
|
613
|
+
Every other capability is configured on its own, and by default still talks to
|
|
614
|
+
the PAP:
|
|
615
|
+
|
|
616
|
+
- `GET /mappings` — the visual builder's vocabulary dropdowns; switch off with
|
|
617
|
+
`mappings="none"` to use the mappings bundled in the package, or supply your
|
|
618
|
+
own through the `mappings` property.
|
|
619
|
+
- `GET /policy/{id}` — when `mode="edit"`; switch off with `load="none"` and
|
|
620
|
+
use the `policy` property.
|
|
621
|
+
- `POST /validate` — only when the user runs a validation; switch off with
|
|
622
|
+
`validate="none"`.
|
|
623
|
+
- `GET /templates` — the template picker *and* the template management tab,
|
|
624
|
+
which writes templates to the PAP. Switch both off with `templates="none"`
|
|
625
|
+
if the component must issue no requests at all.
|
|
626
|
+
|
|
627
|
+
A policy emitted this way carries an `odrl:uid` (generated if the user did not
|
|
628
|
+
set one) and `detail.id` mirrors it, so the host can store the policy under a
|
|
629
|
+
stable identifier.
|
|
630
|
+
|
|
541
631
|
### Full Embedding Example
|
|
542
632
|
|
|
543
633
|
A complete working example is available at `examples/embed-example.html`. To run
|
|
@@ -26,10 +26,11 @@ export type EmbeddedThemePreset = 'light' | 'dark';
|
|
|
26
26
|
export type Capability = 'load' | 'save' | 'validate' | 'templates' | 'mappings';
|
|
27
27
|
|
|
28
28
|
/**
|
|
29
|
-
* Where a capability is served from: `"remote"` (the PAP API, the default)
|
|
30
|
-
* `"none"` (switched off: no request is made and its UI is not rendered)
|
|
29
|
+
* Where a capability is served from: `"remote"` (the PAP API, the default),
|
|
30
|
+
* `"none"` (switched off: no request is made and its UI is not rendered) or
|
|
31
|
+
* `"event"` (the host answers through a Custom Event; supported by `save`).
|
|
31
32
|
*/
|
|
32
|
-
export type CapabilityMode = 'remote' | 'none';
|
|
33
|
+
export type CapabilityMode = 'remote' | 'none' | 'event';
|
|
33
34
|
|
|
34
35
|
/** The mode of every capability. */
|
|
35
36
|
export type CapabilityModes = Record<Capability, CapabilityMode>;
|
|
@@ -100,15 +101,23 @@ export interface EmbeddedEventMap {
|
|
|
100
101
|
*/
|
|
101
102
|
'policy-changed': { policy: Record<string, unknown> };
|
|
102
103
|
/**
|
|
103
|
-
* Fired after a new policy
|
|
104
|
+
* Fired after a new policy has been accepted by the editor.
|
|
104
105
|
*
|
|
105
106
|
* `id` is the id the policy is stored under at the PAP (`GET /policy/{id}`).
|
|
106
107
|
* It is derived from the policy's `odrl:uid`, and differs from it when the
|
|
107
108
|
* uid is not a valid policy id (e.g. a UUID or an IRI).
|
|
109
|
+
*
|
|
110
|
+
* `persisted` is `true` when the policy was written to the PAP and `false`
|
|
111
|
+
* with `save="event"`, where the editor writes nothing and storing the
|
|
112
|
+
* policy under `id` is left to the host.
|
|
113
|
+
*/
|
|
114
|
+
'policy-created': { policy: Record<string, unknown>; id: string; persisted: boolean };
|
|
115
|
+
/**
|
|
116
|
+
* Fired after an existing policy has been updated in the editor.
|
|
117
|
+
*
|
|
118
|
+
* See `policy-created` for the meaning of `id` and `persisted`.
|
|
108
119
|
*/
|
|
109
|
-
'policy-
|
|
110
|
-
/** Fired after an existing policy is successfully updated. */
|
|
111
|
-
'policy-updated': { policy: Record<string, unknown>; id: string };
|
|
120
|
+
'policy-updated': { policy: Record<string, unknown>; id: string; persisted: boolean };
|
|
112
121
|
/** Fired after a policy validation completes. */
|
|
113
122
|
'policy-validated': { result: Record<string, unknown> };
|
|
114
123
|
/** Fired when the user clicks Cancel. */
|
|
@@ -207,7 +216,7 @@ export const TAG_NAME: 'odrl-policy-editor';
|
|
|
207
216
|
* | `hide-cancel-button` | Boolean — hides the Cancel button | absent |
|
|
208
217
|
* | `variant` | `"card"` \| `"plain"` — framed as a card, or no chrome | `"card"` |
|
|
209
218
|
* | `load` | `"remote"` \| `"none"` — fetch the policy when `mode="edit"` | `"remote"` |
|
|
210
|
-
* | `save` | `"remote"` \| `"none"` — store the policy in the PAP
|
|
219
|
+
* | `save` | `"remote"` \| `"event"` \| `"none"` — store the policy in the PAP, emit it to the host, or hide the Save button | `"remote"` |
|
|
211
220
|
* | `validate` | `"remote"` \| `"none"` — validate against the PAP (Validate button) | `"remote"` |
|
|
212
221
|
* | `templates` | `"remote"` \| `"none"` — list and manage PAP templates | `"remote"` |
|
|
213
222
|
* | `mappings` | `"remote"` \| `"none"` — fetch the builder's dropdown mappings | `"remote"` |
|
|
@@ -227,8 +236,8 @@ export const TAG_NAME: 'odrl-policy-editor';
|
|
|
227
236
|
* | Event | Detail |
|
|
228
237
|
* |--------------------|---------------------------------------------|
|
|
229
238
|
* | `policy-changed` | `{ policy: object }` |
|
|
230
|
-
* | `policy-created` | `{ policy: object, id: string }`
|
|
231
|
-
* | `policy-updated` | `{ policy: object, id: string }`
|
|
239
|
+
* | `policy-created` | `{ policy: object, id: string, persisted: boolean }` |
|
|
240
|
+
* | `policy-updated` | `{ policy: object, id: string, persisted: boolean }` |
|
|
232
241
|
* | `policy-validated` | `{ result: object }` |
|
|
233
242
|
* | `editor-cancelled` | `{}` |
|
|
234
243
|
* | `template-created` | `{ template: object, id: string }` |
|