> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder/storing-a-rendering-copy.md).

# Storing a rendering copy

In [stateless](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) mode the raw XML in the `save` event is yours to keep. But the CDN only renders files it stores, so a preview or a production banner needs a copy in Filerobot too.

`dam-store` makes that copy for you on every stateless save, using the same upload the DAM-backed editor uses, before the `save` event fires.

```js
builder.damStore = true

builder.addEventListener('save', (e) => {
  const { content, templateQuery, stored, storeError } = e.detail

  if (stored) {
    // stored.url is the template's CDN URL with its current ?vh= cache key.
    // Append templateQuery and it is a render:
    img.src = `${stored.url}&${templateQuery}`
  }
})
```

{% hint style="info" %}
Join with `?` instead of `&` if your URL happens to carry no query. And `stored.url` can rarely come back empty - the record read-back after the upload failed. The file is stored regardless, under `stored.uuid`.
{% endhint %}

### What to know

* **The raw `content` arrives either way.** A failed upload replaces `stored` with `storeError`, a message. Whether a save without a rendering copy counts as saved is your call, made where it always is: the save ack, so `confirmSave(false)` or returning `false` from React's `onSave`.
* **The credential needs upload rights.** A [security template](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md) must have a scope that allows uploads, or every save reports `storeError`.
* **`store-folder` must sit inside a security template's upload scope.** The element reads the scope when it exchanges the template for a key, and checks a new template's folder against it before uploading:

  | Upload scope              | `store-folder`             | New template's copy                                       |
  | ------------------------- | -------------------------- | --------------------------------------------------------- |
  | one folder, e.g. `/A/B/*` | unset (or `/`)             | stored in `/A/B`                                          |
  | any                       | inside a scope folder      | stored there                                              |
  | several folders           | unset (or `/`)             | not stored: `storeError` lists the folders to choose from |
  | any                       | outside every scope folder | not stored: `storeError` names the folder and the scope   |

  The element never moves a copy to a folder you did not choose; fix the attribute instead. A sass key carries no readable scope, so `store-folder` is used as given.
* **Same name and folder versions the file in place.** When `template-id` names an existing DAM file, that file's own folder is reused. Otherwise new templates land in `store-folder`, which defaults to `/` (with a scoped security template, see above).
* **Persist `stored.uuid`.** Under a VERSION conflict policy each save is its own file row, and `stored.uuid` is always the current one. Do not echo it into `template-id` - an id change deliberately reloads the editor, discarding unsaved work.
* **The element remembers the copy it last made**, so follow-up saves keep working against it even while your own id stays opaque. Unchanged re-saves resolve to that copy instead of erroring. That memory lives in the element instance, so to carry it across a page reload or a remount, pass the persisted uuid back in as `stored-uuid` / `storedUuid`, or as the `storedUuid` field of `load()`.
* **The stored `template_query` is record-agnostic.** Values of variables bound to [custom metadata](https://docs.scaleflex.com/developers-headless/studio/template-builder/custom-metadata.md) are stripped before the query is attached as file metadata, so one record's data never becomes the template's own default.

### Saves can arrive after close

The raw content never dies with the element. Closing the editor changes nothing - the element outlives a close, so a save still inside its upload window emits moments later with its real outcome, possibly **after** the `close` event.

Keep your `save` listener attached until it arrives. If your close handler tears the element down anyway, removing it from the DOM flushes the pending save immediately - raw content with a `storeError` note, and the copy goes unreported if it does land. The React wrapper does the same from its unmount cleanup.

Call `flushPendingSaves()` yourself only if you detach listeners without removing the element.

### Closing the editor during a save

{% hint style="info" %}
Needs a widget release newer than 0.7.2. Version 0.7.2 has no public way to tell that a save is still uploading.
{% endhint %}

A host that removes the element on close (common in React, which unmounts it) can cut a save off mid-upload, and gets a `storeError` for a copy that would have landed. Keep the element in the page, hidden, until the save is in:

* `hasPendingSaves` is `true` while a save is uploading, and the `pendingsaveschange` event (`onPendingSavesChange` in React) fires when that changes.
* `whenSaved({ timeout })` resolves once every pending save has reached your `save` listener (`onSave`), with its real outcome. It never rejects; a failed copy arrives as a `save` with `storeError`. On `timeout` (60 s is a sensible value) the remaining saves are delivered with a `storeError` and it resolves.

```tsx
const builder = useRef<SfxTemplateBuilder>(null)

const close = async () => {
  setHidden(true)
  await builder.current?.whenSaved({ timeout: 60_000 })
  setMounted(false) // every save has reached onSave
}
```

DAM-backed mode is not covered: the deployment saves inside the editor, and the element hears nothing until the save is done.

Rapid saves are serialized, so `save` events always arrive in the order the editor posted them.

### Version note

`dam-store` was added after 0.3.0. A pinned CDN bundle older than that ignores the attribute silently.

### Where to go next

* [The render URL](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md) - what to append to `stored.url`
* [API reference](https://docs.scaleflex.com/developers-headless/studio/template-builder/api-reference.md) - the `save` detail shapes in full
