Embed the editor

This page is for developers. The Editor is available as a React component, so you can open it inside your own application instead of sending people to a separate address. The component loads a document, lets the user edit it, and gives control back to your code when the user publishes or discards.

The document does not start in the component. Your system creates it through the Pages service, as described in Editor integration and Create documents with the Web Editor, and that call returns the values the component needs.

Your application -> the Editor component -> the Editor API -> Doxis Interact

Install and render

The package is @metaforcelabs/metaforce-webeditor. It is restricted, so install it with an npm token that can read the @metaforcelabs scope.

import { createRoot } from "react-dom/client";
import { MetaforceProvider, WebEditorDesign } from "@metaforcelabs/metaforce-webeditor";
 
const configurations = {
  startParameter: "START_PARAMETER",
  apiBaseUrl: "API_BASE_URL",
  internalApiKey: "INTERNAL_API_KEY",
  docId: "DOC_ID",
};
 
createRoot(document.getElementById("root")).render(
  <MetaforceProvider configurations={configurations}>
    <WebEditorDesign nav="edit" />
  </MetaforceProvider>
);

• Always pass nav="edit" to WebEditorDesign. Without it you get the attachment table instead of the editor.
• Render one MetaforceProvider per page. It writes the API address and key to a shared global object, so two providers on one page overwrite each other.

The configurations object

startParameter, docId, jobId and jwt belong to one document, and your backend produces them. The component never fetches them. A missing required value shows up as a visible text such as NO START PARAMETER SET in the requests the component makes, which makes the mistake easy to find.

The one-time token

When you pass jwt, the component sends it on the first load only. The Editor API answers with a session token that the component keeps for the rest of the session. Right after the first load the component calls onOneTimeJwtUsed. Use it to remove jwt from the address so that it cannot be used again. Treat the token as a secret: never log it and never leave it in an address that can be shared.

MetaforceProvider properties

Publish and discard are final. After either, the document is locked.

Change how the editor looks

themeAndStyle is optional, and so is every field in it.

actionButtons has one entry for each of predefined, library, preview, publish, discard, undo and redo. Each entry can set hide, text (the label), icon and className. The entry splitScreen can set hide, onText, offText, onIcon, offIcon and className.

themeAndStyle={{
  hideActionButtonText: true,
  actionButtons: {
    predefined: { hide: true },
    publish: { text: "Send" },
  },
}}

Note: className is applied to the editor’s own elements, and their class names can change in any release. Use text and icon for branding and className only when you have to.

Other screens

The package also exports HtmlPreview, PdfPreview, AttachmentPreview, LocalprintDynamoPdf and LocalprintViewpointPdf. Render them inside the same MetaforceProvider.

Get the result

Your own code calls the public API, not the component’s internal routes. Use an OAuth bearer token, as described in Authentication. {customerEnvironment} and {environmentGroupNameOrId} come from your setup, and {dxmlUID} is the id the document was created with.

List documents takes optional query parameters. status can be repeated, for example status=OK&status=Draft, and accepts Draft, OK, Discarded and Deleted. createdStart, createdEnd, modifiedStart and modifiedEnd limit the list to a period, both ends included. When your setup has extra environment groups in Pages Manager, pass the group as environmentGroupNameOrId. Without parameters you get every document.

For both kinds of list, a start that is later than its end is refused. The API widens every period by five minutes at each end, so a document just outside it can be in the result.

For example, to list the documents that are still drafts, send a GET request with the header Authorization: Bearer <token> to this address:

Get the PDF does not look at the status. A discarded document still returns a PDF. If you need to tell the difference, read the status first.

To create documents, see Create documents with the Web Editor. To get a callback when a document is finished, see Editor integration. For the full list of calls, see the Pages v4 (webeditor-v4) API documentation under Available APIs.

Troubleshooting