Node.js

Node.js developers can serve the Document Editor from an Express application instead of ASP.NET Core. Two public npm packages make up the Node.js side: @txtextcontrol/tx-document-editor writes the editor markup into a page, and @txtextcontrol/tx-websocket-server provides the WebSocket endpoint the editor connects to. The document itself is still synchronized by the Document Editor backend of TX Text Control .NET Server, which you run next to the Node.js application.

Prerequisites

• Node.js and npm.
• The .NET SDK 8.0 or higher to prepare and run the Document Editor backend. The steps use the .NET 10 SDK; with an older SDK, change net10.0 in the first command to your version, for example net8.0.
• A TX Text Control .NET Server license with a serial number assigned to your email address, and your nuget.config for the Text Control Private NuGet Feed. nuget.config describes the file.
• A code editor, for example Visual Studio Code.

How the Parts Work Together

Browser: page with the Document Editor
    |
    |  WebSocket, ws://localhost:8080/TXWebSocket
    v
Node.js application: Express, DocumentEditor, WebSocketServer
    |
    |  TCP, localhost:4283
    v
Document Editor backend: dotnet TXTextControl.Web.Server.Core.dll

• The page loads the editor script from the Node.js application and opens a WebSocket connection to it.
• The Node.js application renders the page with the editor markup and forwards the WebSocket traffic to the backend. WebSocketServer also serves the editor script at /TXWebSocket/GetResource, which it requests from the backend.
• The backend TXTextControl.Web.Server.Core synchronizes the document and calculates the rendering of the pages. It listens on TCP port 4283 by default, and WebSocketServer connects to localhost on this port unless you configure another address.

The Node.js application runs wherever Node.js runs. The backend is a .NET application for Windows and Linux on x64.

Prepare the Document Editor Backend

In an ASP.NET Core application, the hosted service DocumentEditorWorkerManager starts the backend for you. A Node.js application has no such service, so you publish the backend files once and start the backend yourself. A class library project that references the engine and the backend package collects all the files the backend needs.

1. Open a terminal, create the project and change to its folder:

   dotnet new classlib -n EditorBackend -f net10.0
   cd EditorBackend
   

2. Copy your nuget.config into the EditorBackend folder, and install the two packages from the private feed:

   dotnet add package TXTextControl.TextControl.Core.SDK
   dotnet add package TXTextControl.Web.DocumentEditor.Backend
   

3. Publish the project for your operating system. Use win-x64 on Windows and linux-x64 on Linux:

   dotnet publish -c Release -r win-x64 --self-contained false -o publish
   

The project needs no code. The publish folder now contains TXTextControl.Web.Server.Core.dll with its configuration file TXTextControl.Web.Server.Core.config.json, the TX Text Control assemblies, their native libraries and the Fonts folder.

Start the backend from the publish folder and leave the terminal open:

cd publish
dotnet TXTextControl.Web.Server.Core.dll

The output of the backend contains the line "Starting TCP listener on port 4283 for IPv4 and IPv6." To change the port, set TcpPort in TXTextControl.Web.Server.Core.config.json or start the backend with --port, as Configure the Backend Process describes. For production, run the backend as a Windows service, a Linux daemon or a container, as described in Run the Backend Separately.

Create the Node.js Project

1. Open a second terminal, create an empty folder named node-editor and change to it:

   mkdir node-editor
   cd node-editor
   

2. Install the editor package, the web framework Express, the template engine Pug and the WebSocket server package:

   npm install @txtextcontrol/tx-document-editor
   npm install express
   npm install pug
   npm install @txtextcontrol/tx-websocket-server
   

3. Create a folder for the views and open the project in Visual Studio Code:

   mkdir views
   code .
   

The two Text Control packages are public and install without credentials. Document Editor in the Installation Guide lists their versions and dependencies.

Add the View

Create the file index.pug in the views folder and paste the following template:

html
   head
      title= title
   body
      h3= heading
      p= text
      div(
         style='position: absolute; top: 100px; left: 80px; width: 80%; height: 700px'
      ) !{editor}

• title, heading and text are values that the application passes to the view.
• The div element is the container of the editor. The editor fills its container, so the container needs a width and a height.
• !{editor} inserts the markup of the editor into the container as HTML, without escaping it.

Write the Application

Create the file main.js in the project's root folder and paste the following code:

const { WebSocketServer } = require('@txtextcontrol/tx-websocket-server');
const { DocumentEditor } = require('@txtextcontrol/tx-document-editor');
const express = require('express');

const app = express();
const server = app.listen(8080);

app.set('view engine', 'pug');

// provide the WebSocket endpoint and forward the traffic to the backend
var wsServer = new WebSocketServer(server);

var editor = new DocumentEditor({
   webSocketURL: 'ws://localhost:8080/TXWebSocket'
});

app.get('/', (req, res) => {
   res.render('index', {
      title: 'Text Control HTML5 Document Editor',
      heading: 'Text Control HTML5 Document Editor in Node.js',
      text: '(Using the template engine "Pug")',
      editor: editor.render()
   });
});

What the Code Does

• app.listen(8080) starts the Express web server on port 8080 and returns the HTTP server.
• new WebSocketServer(server) adds the WebSocket endpoint /TXWebSocket to that server. Without a second parameter, it connects to the backend on localhost, port 4283.
• new DocumentEditor({ webSocketURL: ... }) configures the editor. webSocketURL is the address of the WebSocket endpoint as the browser reaches it.
• editor.render() returns the markup of the editor: a container, the script element that loads tx-document-editor.min.js from the endpoint and the call of TXTextControl.init with the settings.
• res.render('index', ...) renders views/index.pug with the values of the object, and the view places the editor markup in its container.

Run the Application

1. Make sure the backend from the first step is running.

2. In the terminal of the node-editor folder, start the application:

   node main.js
   

3. Open http://localhost:8080 in a browser.

The page shows the heading, the text below it and the Document Editor with its ribbon bar in the container of the view:

When the editor stays empty or reports a lost connection, check that the backend is running and that the port it listens on is the port WebSocketServer uses.

Configure the Editor

The DocumentEditor constructor accepts more settings in the same object, for example:

var editor = new DocumentEditor({
   webSocketURL: 'ws://localhost:8080/TXWebSocket',
   editMode: 'ReadAndSelect',
   controlChars: true,
   uiCulture: 'de-DE',
   userNames: ['Tim Typer']
});

• editMode sets whether the text is editable, selectable or read-only: 'Edit', 'ReadAndSelect', 'ReadOnly' or 'UsePassword'.
• controlChars shows the control characters.
• uiCulture selects the language of the user interface strings, and culture the culture that formats values such as dates.
• userNames lists the users who can edit the editable regions assigned to them when the document is read-only.

By default, render() sizes the editor to fill its container. To give it a fixed size instead, pass width and height, for example editor.render({ width: '1024px', height: '600px' }). The package also exports a DockStyle enumeration with the values None, Fill and Window for the dockStyle property of the same object. The package README lists all settings.

Once the page has loaded, the global TXTextControl object gives your scripts in the page the same JavaScript API as every other frontend, for example to load and save documents.

Connect to a Backend on Another Machine

When the backend doesn't run on the same machine or on the default port, pass its address and port in the second parameter of the WebSocketServer constructor:

var wsServer = new WebSocketServer(server, {
   serviceAddress: 'backend.example.com',
   servicePort: 4283
});

The backend's TCP port must be reachable from the Node.js application, so open it in the firewall of the backend machine. The backend accepts TCP connections from any client that reaches this port, so allow only the machine of the Node.js application.

Next Steps

• JavaScript API: program the editor from the scripts of your page.
• Loading and Saving Documents: load documents into the editor and save them.
• Angular: use the Node.js WebSocket server as the endpoint of the Angular component.
• Document Editor Architecture: how the frontend, the WebSocket endpoint and the backend work together.