Ryan/documenso
1
0
Fork 1
mirror of https://github.com/documenso/documenso.git synced 2026-06-22 04:12:06 +10:00
Code Issues Packages Projects Releases Wiki Activity

chore: update embed authoring docs (#2254)

Browse Source
This commit is contained in:
Lucas Smith
2025-11-27 23:29:06 +11:00
committed by GitHub
parent 7065b0dd88
commit b16862b480
1 changed files with 241 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/documentation/pages/developers/embedding/authoring.mdx
+241 -25
View File
@@ -5,18 +5,38 @@ description: Learn how to use embedded authoring to create documents and templat
# Embedded Authoring
In addition to embedding signing experiences, Documenso now supports embedded authoring, allowing you to integrate document and template creation directly within your application.
In addition to embedding signing experiences, Documenso now supports embedded authoring, allowing you to integrate document and template creation and editing directly within your application.
## How Embedded Authoring Works
The embedded authoring feature enables your users to create new documents without leaving your application. This process works through secure presign tokens that authenticate the embedding session and manage permissions.
The embedded authoring feature enables your users to create and edit documents and templates without leaving your application. This process works through secure presign tokens that authenticate the embedding session and manage permissions.
## Creating Documents with Embedded Authoring
## Available Components
To implement document creation in your application, use the `EmbedCreateDocument` component from our SDK:
The SDK provides four authoring components:
- **`EmbedCreateDocumentV1`** - Create new documents
- **`EmbedCreateTemplateV1`** - Create new templates
- **`EmbedUpdateDocumentV1`** - Edit existing documents
- **`EmbedUpdateTemplateV1`** - Edit existing templates
React Example:
```jsx
import { unstable_EmbedCreateDocument as EmbedCreateDocument } from '@documenso/embed-react';
import {
EmbedCreateDocumentV1,
EmbedCreateTemplateV1,
EmbedUpdateDocumentV1,
EmbedUpdateTemplateV1,
} from '@documenso/embed-react';
```
## Creating Documents
To implement document creation in your application, use the `EmbedCreateDocumentV1` component:
```jsx
import { EmbedCreateDocumentV1 } from '@documenso/embed-react';
const DocumentCreator = () => {
// You'll need to obtain a presign token using your API key
@@ -37,9 +57,88 @@ const DocumentCreator = () => {
};
```
## Creating Templates
To create templates, use the `EmbedCreateTemplateV1` component:
```jsx
import { EmbedCreateTemplateV1 } from '@documenso/embed-react';
const TemplateCreator = () => {
const presignToken = 'YOUR_PRESIGN_TOKEN';
return (
<div style={{ height: '800px', width: '100%' }}>
<EmbedCreateTemplate
presignToken={presignToken}
externalId="template-12345"
onTemplateCreated={(data) => {
console.log('Template created with ID:', data.templateId);
console.log('External reference ID:', data.externalId);
}}
/>
</div>
);
};
```
## Updating Documents
To edit existing documents, use the `EmbedUpdateDocumentV1` component:
```jsx
import { EmbedUpdateDocumentV1 } from '@documenso/embed-react';
const DocumentEditor = () => {
const presignToken = 'YOUR_PRESIGN_TOKEN';
const documentId = 123; // The ID of the document to edit
return (
<div style={{ height: '800px', width: '100%' }}>
<EmbedUpdateDocument
presignToken={presignToken}
documentId={documentId}
externalId="order-12345"
onlyEditFields={false}
onDocumentUpdated={(data) => {
console.log('Document updated:', data.documentId);
}}
/>
</div>
);
};
```
## Updating Templates
To edit existing templates, use the `EmbedUpdateTemplateV1` component:
```jsx
import { EmbedUpdateTemplateV1 } from '@documenso/embed-react';
const TemplateEditor = () => {
const presignToken = 'YOUR_PRESIGN_TOKEN';
const templateId = 456; // The ID of the template to edit
return (
<div style={{ height: '800px', width: '100%' }}>
<EmbedUpdateTemplate
presignToken={presignToken}
templateId={templateId}
externalId="template-12345"
onlyEditFields={false}
onTemplateUpdated={(data) => {
console.log('Template updated:', data.templateId);
}}
/>
</div>
);
};
```
## Obtaining a Presign Token
Before using the `EmbedCreateDocument` component, you'll need to obtain a presign token from your backend. This token authorizes the embedding session.
Before using any of the authoring components, you'll need to obtain a presign token from your backend. This token authorizes the embedding session.
You can create a presign token by making a request to:
@@ -53,17 +152,29 @@ You can find more details on this request at our [API Documentation](https://ope
## Configuration Options
The `EmbedCreateDocument` component accepts several configuration options:
All authoring components accept the following configuration options:
| Option | Type | Description |
| ------------------ | ------- | ------------------------------------------------------------------ |
| `presignToken` | string | **Required**. The authentication token for the embedding session. |
| `externalId` | string | Optional reference ID from your system to link with the document. |
| `host` | string | Optional custom host URL. Defaults to `https://app.documenso.com`. |
| `css` | string | Optional custom CSS to style the embedded component. |
| `cssVars` | object | Optional CSS variables for colors, spacing, and more. |
| `darkModeDisabled` | boolean | Optional flag to disable dark mode. |
| `className` | string | Optional CSS class name for the iframe. |
| Option | Type | Description |
| ------------------ | ------- | -------------------------------------------------------------------------- |
| `presignToken` | string | **Required**. The authentication token for the embedding session. |
| `externalId` | string | Optional reference ID from your system to link with the document/template. |
| `host` | string | Optional custom host URL. Defaults to `https://app.documenso.com`. |
| `css` | string | Optional custom CSS to style the embedded component. |
| `cssVars` | object | Optional CSS variables for colors, spacing, and more. |
| `darkModeDisabled` | boolean | Optional flag to disable dark mode. |
| `className` | string | Optional CSS class name for the iframe. |
| `additionalProps` | object | Optional additional props to pass to the iframe (for testing features). |
| `features` | object | Optional feature toggles to customize the authoring experience. |
### Update Component Specific Props
The `EmbedUpdateDocument` and `EmbedUpdateTemplate` components also accept:
| Option | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `documentId` | number | **Required for EmbedUpdateDocument**. The ID of the document to edit. |
| `templateId` | number | **Required for EmbedUpdateTemplate**. The ID of the template to edit. |
| `onlyEditFields` | boolean | Optional flag to restrict editing to fields only skipping the recipient configuration step (default: `false`). |
## Feature Toggles
@@ -83,9 +194,11 @@ You can customize the authoring experience by enabling or disabling specific fea
/>
```
## Handling Document Creation Events
## Handling Events
The `onDocumentCreated` callback is triggered when a document is successfully created, providing both the document ID and your external reference ID:
Each component provides callbacks for handling completion events:
### Document Events
```jsx
<EmbedCreateDocument
@@ -99,11 +212,47 @@ The `onDocumentCreated` callback is triggered when a document is successfully cr
updateOrderDocument(data.externalId, data.documentId);
}}
/>
<EmbedUpdateDocument
presignToken="YOUR_PRESIGN_TOKEN"
documentId={123}
onDocumentUpdated={(data) => {
console.log('Document updated:', data.documentId);
// Handle document update
}}
/>
```
### Template Events
```jsx
<EmbedCreateTemplate
presignToken="YOUR_PRESIGN_TOKEN"
externalId="template-12345"
onTemplateCreated={(data) => {
console.log('Template created:', data.templateId);
// Handle template creation
}}
/>
<EmbedUpdateTemplate
presignToken="YOUR_PRESIGN_TOKEN"
templateId={456}
onTemplateUpdated={(data) => {
console.log('Template updated:', data.templateId);
// Handle template update
}}
/>
```
All event callbacks receive an object with:
- `documentId` or `templateId` - The ID of the created/updated document or template
- `externalId` - Your external reference ID (if provided)
## Styling the Embedded Component
You can customize the appearance of the embedded component using standard CSS classes:
You can customize the appearance of the embedded component using standard CSS classes, custom CSS, and CSS variables:
```jsx
<EmbedCreateDocument
@@ -130,20 +279,48 @@ Here's a complete example of integrating document creation in a React applicatio
```tsx
import { useState } from 'react';
import { unstable_EmbedCreateDocument as EmbedCreateDocument } from '@documenso/embed-react';
import { EmbedCreateDocumentV1, EmbedUpdateDocumentV1 } from '@documenso/embed-react';
function DocumentCreator() {
function DocumentManager() {
// In a real application, you would fetch this token from your backend
// using your API key at /api/v2/embedding/create-presign-token
const presignToken = 'YOUR_PRESIGN_TOKEN';
const [documentId, setDocumentId] = useState<number | null>(null);
const [mode, setMode] = useState<'create' | 'edit'>('create');
if (documentId) {
if (documentId && mode === 'create') {
return (
<div>
<h2>Document Created Successfully!</h2>
<p>Document ID: {documentId}</p>
<button onClick={() => setDocumentId(null)}>Create Another Document</button>
<div>
<button onClick={() => setMode('edit')}>Edit Document</button>
<button
onClick={() => {
setDocumentId(null);
setMode('create');
}}
>
Create Another Document
</button>
</div>
</div>
);
}
if (mode === 'edit' && documentId) {
return (
<div style={{ height: '800px', width: '100%' }}>
<button onClick={() => setMode('create')}>Back to Create</button>
<EmbedUpdateDocument
presignToken={presignToken}
documentId={documentId}
externalId="order-12345"
onDocumentUpdated={(data) => {
console.log('Document updated:', data.documentId);
setMode('create');
}}
/>
</div>
);
}
@@ -153,6 +330,14 @@ function DocumentCreator() {
<EmbedCreateDocument
presignToken={presignToken}
externalId="order-12345"
features={{
allowConfigureSignatureTypes: true,
allowConfigureLanguage: true,
allowConfigureDateFormat: true,
allowConfigureTimezone: true,
allowConfigureRedirectUrl: true,
allowConfigureCommunication: true,
}}
onDocumentCreated={(data) => {
setDocumentId(data.documentId);
}}
@@ -161,7 +346,38 @@ function DocumentCreator() {
);
}
export default DocumentCreator;
export default DocumentManager;
```
With embedded authoring, your users can seamlessly create documents within your application, enhancing the overall user experience and streamlining document workflows.
## Advanced Usage
### Using Additional Props
You can pass additional props to the iframe for testing features before they're officially supported:
```jsx
<EmbedCreateDocument
presignToken="YOUR_PRESIGN_TOKEN"
additionalProps={{
experimentalFeature: true,
customSetting: 'value',
}}
/>
```
### Restricting To Only Field Editing
When updating documents or templates, you can restrict editing to fields only skipping the recipient configuration step:
```jsx
<EmbedUpdateDocument
presignToken="YOUR_PRESIGN_TOKEN"
documentId={123}
onlyEditFields={true}
onDocumentUpdated={(data) => {
console.log('Fields updated:', data.documentId);
}}
/>
```
With embedded authoring, your users can seamlessly create and edit documents and templates within your application, enhancing the overall user experience and streamlining document workflows.