DS Server

React

Topic

React applications show the Document Editor of DS Server with the DocumentEditor component of the npm package @txtextcontrol/tx-react-ds-document-editor. The component loads the editor from DS Server and gets its access token there, so a first application needs no backend of your own. You prepare a security profile, create a Vite application, add the component and insert text with the JavaScript API once the editor is ready.

Prerequisites

  • Node.js and npm, and an editor such as Visual Studio Code.
  • A DS Server that is installed, licensed and reachable from the browser, as the Installation Guide and Licensing describe. The samples use http://localhost:5000. With a trial token instead, skip the next section, use https://trial.dsserver.io as the service URL and the client ID and secret of the token; see Trial Token.

The package version 5.0.0 requires React 19 and DS Server 5.0.

Prepare a Security Profile

With a client ID and a client secret, the component requests its access token from the browser with the client credentials grant type. The security profile must allow this grant type, which is off by default.

  1. In the admin portal of DS Server, choose Security Profiles, click + Create new profile, enter a name and click Create.

  2. Copy the Client ID and the Client Secret of the new profile.

  3. Switch on Allow "Client Credentials" grant type and click Done.

    The Authorized Redirect URIs list of a security profile and, below it, the Allow Client Credentials grant type switch turned on in green.

Any visitor of the page can read client credentials that are part of its JavaScript. Use them for development. For production, pass an access token that your server requested, as Use an Access Token shows.

Create the React Application

  1. Open a command prompt and create a new React application with Vite:

    npm create vite@latest my-ds-editor-app

    Select React as the framework and JavaScript as the variant, keep the default linter and answer No to Install with npm and start now?, because the next steps install the packages.

  2. Change to the new folder and install the dependencies:

    cd my-ds-editor-app
npm install

  3. Install the Document Editor package:

    npm i @txtextcontrol/tx-react-ds-document-editor

Add the Editor Component

Open src/App.jsx, replace its complete content with the following code and save the file. Replace the service URL, the client ID and the client secret with your values.

import DocumentEditorPackage from '@txtextcontrol/tx-react-ds-document-editor';

// Vite 8 returns the CommonJS module for a default import
const DocumentEditor = DocumentEditorPackage.default ?? DocumentEditorPackage;

function App() {
  function handleLoad() {
    // wait until the editor is ready
    TXTextControl.addEventListener('textControlLoaded', () => {
      TXTextControl.selection.setText('Welcome to DS Server');
    });
  }

  return (
    <DocumentEditor
      style={{ width: '1000px', height: '600px' }}
      serviceURL="http://localhost:5000"
      authSettings={{ clientId: '<client ID>', clientSecret: '<client secret>' }}
      onLoad={handleLoad}
    />
  );
}

export default App;

What the Code Does

  • The package is a CommonJS module. Since Vite 8, the default import of such a module returns the whole module object in a project whose package.json sets "type": "module", as the Vite template does. The code takes the component from its default property; with ??, it works with earlier Vite versions too. A plain import DocumentEditor from '@txtextcontrol/tx-react-ds-document-editor' makes React report an invalid element type under Vite 8.
  • style sets the size of the editor. serviceURL is the address of DS Server and must start with http:// or https://.
  • authSettings holds the credentials of the security profile, or an accessToken.
  • onLoad runs as soon as the editor script is loaded and the global TXTextControl object exists. The handler waits for textControlLoaded, which fires when the editor is ready, and inserts text with selection.setText.

React in Client-Side Libraries lists every property, such as editMode, userNames and culture.

Run the Application

  1. In the command prompt, start the development server:

    npm run dev

  2. Open the address it prints, http://localhost:5173 by default, in your browser.

The page shows the Document Editor with its ribbon bar and the text "Welcome to DS Server".

The React component has no property for a document. Load one in onLoad, after textControlLoaded, with loadDocument, and save it with saveDocument. The ribbon of the DS Server editor has no File tab.

Use an Access Token

To keep the client secret on your server, request the access token there and pass it in authSettings. The component uses the token when it loads the editor, so render it only after the token has arrived. Replace the content of src/App.jsx with the following code, and https://localhost:7143/api/token with the address of your token endpoint:

import { useEffect, useState } from 'react';
import DocumentEditorPackage from '@txtextcontrol/tx-react-ds-document-editor';

// Vite 8 returns the CommonJS module for a default import
const DocumentEditor = DocumentEditorPackage.default ?? DocumentEditorPackage;

function App() {
  const [accessToken, setAccessToken] = useState(null);

  useEffect(() => {
    // request the access token from your own backend
    fetch('https://localhost:7143/api/token')
      .then(response => response.json())
      .then(token => setAccessToken(token.access_token));
  }, []);

  if (!accessToken) {
    return null;
  }

  return (
    <DocumentEditor
      style={{ width: '1000px', height: '600px' }}
      serviceURL="http://localhost:5000"
      authSettings={{ accessToken: accessToken }}
    />
  );
}

export default App;

Keep the Client Secret on Your Server shows an ASP.NET Core endpoint that returns the token. The Vite development server runs on another origin, so the endpoint must allow it with a CORS policy. Protect the endpoint, for example with the sign-in of your application, because anyone who can call it gets a token.

Troubleshooting

  • "Element type is invalid" in the browser console: the plain default import returned the module object. Take the component from default, as the code above does.
  • "DS Server is not registered." The editor area stays gray and shows this message when the DS Server has no license. Register it in the admin portal, as Licensing describes.
  • Could not retrieve OAuth token. Error: unsupported_grant_type in the browser console: the security profile doesn't allow the client credentials grant type.

Document Editor and Viewer in Troubleshooting covers more problems.

Next Steps