|
1 | | -# Edit Event API |
| 1 | +# Edit Event API v2 |
2 | 2 |
|
3 | | -Open SCD offers an API for editing the scd document which can be used with [Html Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent). The main Open SCD components listens to events of the type `oscd-edit`, applies the changes to the `doc` and updates the `editCount` property. |
| 3 | +Open SCD offers an API for editing the scd document which can be used with [Html Custom Events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent). The main Open SCD components listens to events of the type `oscd-edit-v2`, applies the changes to the `doc` and updates the `editCount` property. |
4 | 4 |
|
5 | 5 | The edits to the `doc` will be done in place, e.g. the `doc` changes but will keep the same reference. If your plugin needs to react to changes in the doc, you should listen to changes in the `editCount` property. |
6 | 6 |
|
7 | 7 | ## Event factory |
8 | 8 |
|
9 | 9 | Open SCD core exports a factory function for edit events, so you do not have to build them manually. |
10 | 10 |
|
| 11 | +```ts |
| 12 | +function newEditEventV2<E extends EditV2>( |
| 13 | + edit: E, |
| 14 | + options?: EditEventOptionsV2 |
| 15 | +): EditEventV2 |
| 16 | + |
| 17 | +type EditV2 = InsertV2 | SetAttributesV2 | SetTextContentV2 | RemoveV2 | EditV2[]; |
| 18 | + |
| 19 | +interface EditEventOptionsV2 = { |
| 20 | + title?: string; |
| 21 | + squash?: boolean; |
| 22 | + createHistoryEntry?: boolean; |
| 23 | +}; |
| 24 | +``` |
| 25 | + |
| 26 | +### EditEventOptionsV2 |
| 27 | + |
| 28 | +* `title` set a title to be shown in the history. |
| 29 | +* `squash` squash edit with previous history entry, this is useful if you want to create multiple edits based on an user action, but need the updated `doc` before applying each edit. Defaults to `false`. |
| 30 | +* `createHistoryEntry` decides whether a history for the `edit` should be created. Defaults to `true`. |
| 31 | + |
| 32 | +### Insert |
| 33 | + |
| 34 | +Insert events can be used to add new nodes or move existing nodes in the document. Since a node can only have one parent, using an insert on an existing node will replace it's previous parent with the new parent, essentially moving the node to a different position in the xml tree. |
| 35 | + |
| 36 | +If the reference is not `null`, the node will be inserted before the reference node. The reference has to be a child node of the parent. And if the reference is `null` the node will be added as the last child of the parent. |
| 37 | + |
| 38 | +```ts |
| 39 | +interface InsertV2 { |
| 40 | + parent: Node; |
| 41 | + node: Node; |
| 42 | + reference: Node | null; |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +### Remove |
| 47 | + |
| 48 | +This event will remove the node from the document. |
| 49 | + |
| 50 | +```ts |
| 51 | +interface RemoveV2 { |
| 52 | + node: Node; |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +### SetAttributes |
| 57 | + |
| 58 | +Sets attributes for the element, can set both regular and namespaced attributes. |
| 59 | + |
| 60 | +```ts |
| 61 | +interface SetAttributesV2 { |
| 62 | + element: Element; |
| 63 | + attributes: Partial<Record<string, string | null>>; |
| 64 | + attributesNS: Partial<Record<string, Partial<Record<string, string | null>>>>; |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +To set a namespaced attribute see the following example. Here we are setting the attribute `exa:type` for the namespace `https://example.com` to `secondary`. |
| 69 | + |
| 70 | +```ts |
| 71 | +const setNamespacedAttributes: SetAttributesV2 = { |
| 72 | + element, |
| 73 | + attributes: {}, |
| 74 | + attributesNS: { |
| 75 | + "https://example.com": { |
| 76 | + "exa:type": "secondary" |
| 77 | + } |
| 78 | + } |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +### SetTextContent |
| 83 | + |
| 84 | +Sets the text content of the element, removes any other children. To remove text content you can pass `null` as value for `textContent`. |
| 85 | + |
| 86 | +```ts |
| 87 | +interface SetTextContentV2 { |
| 88 | + element: Element; |
| 89 | + textContent: string; |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +### Complex edits |
| 94 | + |
| 95 | +Complex edits can be used to apply multiple edits as a single event. This will create a single entry in the history. You can create complex edit events by passing an array of edit events to the `newEditEventV2` factory function. |
| 96 | + |
| 97 | +```ts |
| 98 | +import { newEditEventV2 } from '@openscd/core'; |
| 99 | + |
| 100 | +const complexEditEvent = newEditEventV2([ insert, update, remove ]); |
| 101 | + |
| 102 | +someComponent.dispatchEvent(complexEditEvent); |
| 103 | + |
| 104 | +``` |
| 105 | + |
| 106 | +## History |
| 107 | + |
| 108 | +All edit events with the option `createHistoryEntry` will create a history log entry and can be undone and redone through the history addon. |
| 109 | + |
| 110 | + |
| 111 | +# Archives |
| 112 | + |
| 113 | +## Edit Event API v1 (deprecated) |
| 114 | + |
| 115 | +The edit event API v1 is still available and listens to events of the type `oscd-edit`. |
| 116 | + |
| 117 | +## Event factory |
| 118 | + |
| 119 | +Open SCD core exports a factory function for edit events, so you do not have to build them manually. |
| 120 | + |
11 | 121 | ```ts |
12 | 122 | function newEditEvent<E extends Edit>( |
13 | 123 | edit: E, |
@@ -158,7 +268,7 @@ With open SCD version **v0.36.0** and higher some editor action features are no |
158 | 268 |
|
159 | 269 | --- |
160 | 270 |
|
161 | | -# Archives - Editor Action API (deprecated) |
| 271 | +## Editor Action API (deprecated) |
162 | 272 |
|
163 | 273 | ### Event factory |
164 | 274 |
|
|
0 commit comments