--- title: Events, saving & sharing description: Listen for annotation changes, save them into the PDF, and move them in and out of your own database. --- # Events, saving & sharing Every annotation change fires an event, whoever made it: the user, your code, or someone else on a shared document. Listen for them to keep your own UI or server in step: > **Try it:** draw, move and delete. Each change is logged once the engine has saved it, as > `local`: this viewer made it. The listens while the component is mounted. Outside a component, call the event on the plugin's API; it returns a function that stops listening: ```ts const stop = annotation.onCreated(({ annotation }) => { /* … */ }); ``` `takeUntilDestroyed()` stops listening when the component or directive is destroyed. Anywhere else, such as in a service, keep the subscription and end it yourself: ```ts const subscription = annotation.created$.subscribe(({ annotation }) => { /* … */ }); subscription.unsubscribe(); ``` ## Events | Event | Fires when | Carries | | :------------------ | :------------------------------------------------------------------ | :------------------------ | | `onCreated` | An annotation was added. | `annotation`, `origin` | | `onUpdated` | An annotation was changed. | `annotation`, `origin` | | `onDeleted` | Annotations were deleted: one, plus its popup and replies. | `refs`, `page`, `origin` | | `onReordered` | The drawing order on a page changed. | `page`, `order`, `origin` | | `onResynced` | Annotations were read again, as after loading a document. | `pages` | | `onWriteFailed` | The engine refused a change the user made. | `refs`, `error` | | `onSettingsChanged` | A setting changed, through `updateSettings()` or `resetSettings()`. | `settings`, `changedKeys` | - **Once, and after it's saved.** `onCreated`, `onUpdated`, `onDeleted` and `onReordered``created$`, `updated$`, `deleted$` and `reordered$` fire when the engine has saved the change, never while it's still pending. A change fires once, however many screens show it. - **Loading isn't a list of creates.** When a document opens, its annotations arrive as one `onResynced`, not as an `onCreated``resynced$`, not as a `created$` per annotation. The same happens after a change that touches whole pages, such as flattening or redaction. Then read the `pages` it names again with `list()`. - **`annotation` is the record after the change.** It's what `get()` returns now. - **`order` is the whole page.** After a reorder, `order` holds the page's annotations as refs, bottom to top, the same order `list({ pages: [page] })` returns. The selection, a shape being drawn, text editing and hover have events of their own (`onSelectionChanged`, `onDraftChanged`, `onEditingChanged`, `onHoverChanged``selectionChanged$`, `draftChanged$`, `editingChanged$`, `hoverChanged$`); see [Selecting & editing](selecting#events). A tool's defaults have `tools.onDefaultsChanged``tools.defaultsChanged$`; see [Tools & defaults](tools#events). ## Where a change came from `origin` says who made the change: | Field | What it is | | :------------------- | :---------------------------------------------------------------------------- | | `origin.kind` | `'local'` when this viewer made the change, `'remote'` when someone else did. | | `origin.subject` | The user who made it (on a shared document). | | `origin.at` | When it happened, as an ISO 8601 string. | | `origin.transaction` | Shared by every change one call made, such as an import. | These are the engine's own events, so the fields mean the same as on [Events](/docs/engine/concepts/events). ## Save the PDF Annotations are part of the document. Save the document and they're in the file: ```ts const bytes = await documents.download(); // the whole PDF, with every annotation ``` A save waits for pending changes, so what you save is what the user sees. For the difference between a quick save that appends the changes and a full rewrite, see [Saving](/docs/engine/documents/saving). ## Export and import To take annotations out of a document, as data rather than inside a PDF, export them. One call gives you a **bundle**: every annotation with the bytes it carries (a stamp's drawing, an attached file). One call puts a bundle into a document. `AnnotationTransfer` comes from `@embedpdf/react/annotation`: ```ts const bundle = await annotation.export(); // everything const text = AnnotationTransfer.stringify(bundle); // one JSON text, ready to store // later, in the same document or another one const { annotations, dropped } = await annotation.import(await AnnotationTransfer.parse(text), { pages: 'by-position', }); ``` Use it to: - keep annotations in your own database, apart from the PDF; - carry a review over to a new version of a document; - let a user paste annotations from one document into another. > **Try it:** **Delete all**, then **Import**: they come back from the text. Import again: the > annotations with a name are left out, since they're there already. Export waits for pending changes. An import is one change: its annotations show once the engine has written them, and the whole import is [one step to undo](#an-import-is-one-step-to-undo). What to export: ```ts const selected = annotation.selection.getSelected(); await annotation.export({ refs: selected.map((a) => a.ref) }); // the selection await annotation.export({ pages: [page.ref] }); // one page ``` A selection brings what it needs: a reply brings the comment it answers, and a comment brings its replies. How to import: | Option | What it does | Default | | :------------ | :----------------------------------------------------------------------------------------------- | :---------- | | `pages` | Where each page's annotations go: `'same'` (the same page), `'by-position'`, or a list of pairs. | `'same'` | | `attribution` | `'restore'` keeps who wrote each annotation, `'stamp'` makes the importing user the author. | `'restore'` | | `history` | `false` keeps the import out of undo and redo. | one step | Use `'stamp'` when a user pastes annotations: they become theirs. `'restore'` writes annotations in other people's names, so it needs a special permission; keep it for trusted jobs, such as loading from your own database. The result tells you what happened: - **`annotations`**: the new annotations, in bundle order. - **`refMap`**: each annotation's ref in the bundle, and its new ref here. - **`dropped`**: what was left out, and why. For example, an annotation whose name is already taken on its page. Importing the same bundle twice doesn't duplicate annotations with a name. The engine's [Import & export](/docs/engine/annotations/import-export) page has every option, reason and limit. ### An import is one step to undo An undo takes away every annotation the import added, and a redo brings them back under the same refs. That's what a user expects after a paste, or after an **Import** button. When your app imports by itself, the user did nothing to undo. Pass `history: false`, and undo leaves the import alone: ```ts // behind a button or a paste: one step, undo removes them all await annotation.import(bundle, { attribution: 'stamp' }); // loading what you stored: not a step await annotation.import(bundle, { history: false }); ``` ## Keep annotations in your own database There are two ways to store annotations outside the PDF. **Store a bundle per document.** Export when the user saves, store the text, and import it when the document opens again. It's one row per document and one call each way: ```ts // on save await api.put(`/reviews/${docId}`, AnnotationTransfer.stringify(await annotation.export())); // on open, once the annotations are loaded (status 'ready') const text = await api.get(`/reviews/${docId}`); if (text) { const bundle = await AnnotationTransfer.parse(text); // your app loads them, not the user: nothing to undo await annotation.import(bundle, { history: false }); } ``` **Store each annotation as it changes.** Listen for the events and write each change to your server. Key your rows by the annotation's ref: Handle `onUpdated` the same way, and `onDeleted` by deleting each of its `refs`. On `onResynced`, compare the pages it names with `list()`.Handle `updated$` the same way, and `deleted$` by deleting each of its `refs`. On `resynced$`, compare the pages it names with `list()`. Only send `local` changes: a `remote` one was already saved by whoever made it. ### Which id to store Store the annotation's `ref`. It's plain data, and it stays valid after the document is saved and opened again. To use it as a key in a map or a URL, turn it into a string with `annotationKey(ref)`. See [Refs & identity](/docs/engine/concepts/identity). ## Good to know ### Unsaved changes To warn before someone leaves with annotations that aren't downloaded yet, use `hasUnsavedChanges` from `useDocument()`the `hasUnsavedChanges()` signal on `inject(EpdfDocument)`; see [Warn before changes are lost](../documents/saving#warn-before-changes-are-lost). ### Events on a shared document The local engine's events come from this tab: the changes made here, by the user or your code. With CloudPDF, annotations are stored on your server as people make them, and everyone with the document open gets each other's changes as events, with `origin.kind: 'remote'`. The server checks that people only change what they may, such as their own annotations. Your code stays the same: the same events, the same `list()`. Every viewer with the document open gets every change as an event, with `origin.kind` set to `'remote'` for the ones it didn't make. The annotations appear in `list()` by themselves; the events are there so you can react, such as with a notification.