# Templates

> Let users list, edit, preview and submit project message templates from your app.

The template components edit [project message templates](https://docs.polymorfa.com/messaging/templates).
`TemplateManager` lists your project's templates and opens one in
`TemplateBuilder`. `TemplateBuilder` edits a single template.

The editor covers the template name, header, body, footer, button labels,
carousel card bodies and variable examples. Save draft and Submit to Meta are
separate actions, and Preview shows a structured preview of the message.

## Server route

Templates are saved through your route, never directly from the browser. Add
`templates` to `createPolymorfaHandler` and allow `manage_templates` in the
user's grant:

```ts
createPolymorfaHandler({
  // ...
  mint: (user) => ({
    session: "support",
    conversations: [],
    allow: ["manage_templates"],
  }),
  templates: {
    projectSlug: ({ user }) => projectSlugFor(user),
    submissionSession: ({ user }) => cloudSessionFor(user),
  },
});
```

`projectSlug` chooses the project and `submissionSession` chooses the session
that submits templates to Meta. Both run on your server; a browser request
cannot override them. The key behind the route needs `templates:read` and
`templates:manage`.

For a standalone route, use `createTemplateBuilderRoute` from
`@polymorfa/nextjs` with an `authorize` callback and the same two resolvers.

## TemplateManager

```tsx
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
  <TemplateManager />
</PolymorfaProvider>
```

All 3 `TemplateManager` props, with types, defaults and a live preview, are on the [TemplateManager](https://docs.polymorfa.com/ui-kit/components/template-manager) page.

The manager is hidden unless the grant allows `manage_templates`, and it needs a
provider with `tokenEndpoint` or `client`. It is React only.

## TemplateBuilder

`TemplateBuilder` renders a `TemplateBuilderController` from
`@polymorfa/browser`. Create the controller with a transport:
`createSameOriginTemplateBuilderTransport({ path })` posts to your templates
route.

```tsx
import {
  TemplateBuilderController,
  createSameOriginTemplateBuilderTransport,
} from "@polymorfa/browser";
import { TemplateBuilder } from "@polymorfa/react";

const builder = new TemplateBuilderController(
  createSameOriginTemplateBuilderTransport({ path: "/api/polymorfa/templates" }),
);
await builder.load(templateId);

<TemplateBuilder controller={builder} />;
```

All 5 `TemplateBuilder` props, with types, defaults and a live preview, are on the [TemplateBuilder](https://docs.polymorfa.com/ui-kit/components/template-builder) page.

The controller's `create(draft)` starts a new template and `load(templateId)`
opens an existing one. Its state moves through `loading`, `ready`, `saving`,
`previewing`, `submitting`, `submitted`, `deleting`, `deleted` and `error`.
Validation issues found in the browser appear as alerts above the actions,
and Save draft stays disabled until they are fixed.

## pmfa-template-builder

```ts
import { defineTemplateElements } from "@polymorfa/elements";

defineTemplateElements();
document.querySelector("pmfa-template-builder").controller = builder;
```

The element uses the same controller. Its parts include `template-builder`,
`field`, `label`, `input`, `actions`, `primary-button` (Save draft), `button`
(Submit to Meta), `preview` (the Preview button), `preview-panel` (the preview
area) and `error`. See [Slots](https://docs.polymorfa.com/ui-kit/appearance#slots).

## Accessibility

- Every field has a visible label, including generated labels such as
  "Variable {name} example" and "Button {index} text".
- Validation messages keep their nodes while they still apply, so a screen
  reader announces each one once.

## Related

- [Message templates](https://docs.polymorfa.com/messaging/templates)
- [Appearance and styling](https://docs.polymorfa.com/ui-kit/appearance)
