diff --git a/apps/documentation/pages/developers/embedding/authoring.mdx b/apps/documentation/pages/developers/embedding/authoring.mdx index 777f3fb08..d3427f1c8 100644 --- a/apps/documentation/pages/developers/embedding/authoring.mdx +++ b/apps/documentation/pages/developers/embedding/authoring.mdx @@ -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 ( +
+ { + console.log('Template created with ID:', data.templateId); + console.log('External reference ID:', data.externalId); + }} + /> +
+ ); +}; +``` + +## 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 ( +
+ { + console.log('Document updated:', data.documentId); + }} + /> +
+ ); +}; +``` + +## 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 ( +
+ { + console.log('Template updated:', data.templateId); + }} + /> +
+ ); +}; +``` + ## 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 + + { + console.log('Document updated:', data.documentId); + // Handle document update + }} +/> ``` +### Template Events + +```jsx + { + console.log('Template created:', data.templateId); + // Handle template creation + }} +/> + + { + 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 (null); + const [mode, setMode] = useState<'create' | 'edit'>('create'); - if (documentId) { + if (documentId && mode === 'create') { return (

Document Created Successfully!

Document ID: {documentId}

- +
+ + +
+
+ ); + } + + if (mode === 'edit' && documentId) { + return ( +
+ + { + console.log('Document updated:', data.documentId); + setMode('create'); + }} + />
); } @@ -153,6 +330,14 @@ function DocumentCreator() { { 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 + +``` + +### Restricting To Only Field Editing + +When updating documents or templates, you can restrict editing to fields only skipping the recipient configuration step: + +```jsx + { + 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.