Rich Text extension

Overview

The Rich Text extension enables you to implement custom Rich Text processors. This allows customization to meet specific needs and improves how Rich Text is represented. Starting with Domino REST API version 1.0.12, you can add Rich Text processors for the Domino REST API.

Outgoing Rich Text processor

The outgoing Rich Text processor handles how saved data in a richtext field appears when returned as a response to a GET request. The value of the richTextAs query parameter is used to determine the outgoing Rich Text processor to use. The Domino REST API includes these built-in outgoing Rich Text processors:

mime
html
markdown
plain

Incoming Rich Text processor

The incoming Rich Text processor handles how incoming Rich Text JSON is saved in the richtext field. The value of the type property in the Rich Text JSON is used to determine the incoming Rich Text processor to use. The Domino REST API includes these built-in incoming Rich Text processors:

multipart/mixed ¹
text/plain
text/markdown
text/html

Create a Rich Text extension

Install KEEP core and extension JARs

Before creating a Rich Text extension, install KEEP Core and extension JARs to your local Maven repository.

Install Domino REST API using the Domino REST API installer.
Locate keep-core-<version>.jar and keep-extension-<version>.jar in the Domino REST API install directory.
Install both JARs to you local Maven M2 repository using the following commands:
```
mvn install:install-file -Dfile=<path-to-keep-core-jar>
mvn install:install-file -Dfile=<path-to-keep-extension-jar>
```
Note

Replace <path-to-keep-core-jar> with the path to keep-core-<version>.jar and <path-to-keep-extension-jar> with the path to keep-extension-<version>.jar.

This adds KEEP Core and the extension module to your local Maven M2 repository.

Create a Rich Text extension project

Create a Maven project for your Rich Text extension.

Run the following command to create a new Maven project:

mvn archetype:generate -DgroupId=com.example -DartifactId=richtext-extension -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

This creates the richtext-extension directory that includes a src folder and a pom.xml file.

Update the pom.xml file.
1. Set maven.compiler.source and maven.compiler.target to:
  - 1.8 for Domino r12
  - 17 for Domino r14
2. Under dependency, include the extension JAR you installed earlier:
```
<dependency>
  <groupId>com.hcl.domino.keep</groupId>
  <artifactId>keep-extension</artifactId>
  <version>1.33.0</version> 
  <scope>provided</scope>
</dependency>
```
  Note
  - The scope is set to provided so that the dependency is not compiled with your Rich Text extension, as you will be putting the extension JAR alongside the Domino REST API JARs. The Domino REST API JARs contain all the dependencies that your extension JAR needs.
  - While Domino REST API has many transitive dependencies, only those directly listed in keep-extension are safe to rely on. Others may change between versions.
Save your changes.

Create your Rich Text processor

You can implement two interfaces, IncomingRichtextProcessor and OutgoingRichtextProcessor, to create your own Rich Text processor.

IncomingRichtextProcessor methods

The IncomingRichtextProcessor has three methods:

getProcessorName returns a string representing the name of the incoming Rich Text processor. It checks the name of the incoming Rich Text processor against the value of the type property in the Rich Text JSON to determine if the incoming Rich Text processor should be used.
process checks if the incoming content of the Rich Text JSON is MIME, and returns it as a Buffer if it is. If it is not, it constructs a MIME using the Rich Text JSON properties and returns the constructed MIME as a Buffer. You can override this method to control how you want to save the incoming Rich Text.
getPriority, by default, returns 0. You can override this method to set which incoming Rich Text processor to use when multiple processors share the same name. The higher the set value, the higher the priority.

OutgoingRichtextProcessor methods

The OutgoingRichtextProcessor has three methods:

getProcessorName returns a string representing the name of the outgoing Rich Text processor. It checks the name of the outgoing Rich Text processor against the value of the richTextAs query parameter of the GET request to determine if the outgoing Rich Text processor should be used.
process is an abstract method that can be overwritten to specify how to represent the Rich Text content in the response.
getPriority, by default, returns 0. You can override this method to set which outgoing Rich Text processor to use when multiple processors share the same name. The higher the set value, the higher the priority.

Create incoming Rich Text processor

Create a class that implements IncomingRichtextProcessor.

Example

The following code shows an example Java class that implements IncomingRichtextProcessor interface to create an incoming Rich Text processor. This custom processor overrides the normal processing of incoming rich text JSON data by converting the received Rich Text JSON content and saves "Hi!" as a text/plain MIME part in the richtext field.

package com.example;

import java.util.Optional;
import java.util.Set;

import com.hcl.domino.keep.info.richtext.CreateAdditional;
import com.hcl.domino.keep.info.richtext.RichtextMimeHelper;
import com.hcl.domino.keep.info.richtext.spi.IncomingRichtextProcessor;

import io.vertx.core.buffer.Buffer;
import io.vertx.core.json.JsonObject;

/**
 * Always saves "Hi!" as a text/plain mime regardless of what's inside the Rich Text JSON
*/
public class AlwaysHiIncomingRichtextProcessor implements IncomingRichtextProcessor {

  @Override
  public String getProcessorName() {
    return "alwayshi";
  }

  @Override
  public Optional<Buffer> process(JsonObject richJson, byte[] contentBytes,
      final Set<CreateAdditional> createAdditional) {
    final Optional<String> mime = RichtextMimeHelper.plain2mime("Hi!".getBytes());

    if (!mime.isPresent()) {
      return Optional.empty();
    }
    return Optional.of(Buffer.buffer(mime.get()));
  }

}

Create a file in the src/main/resources/META-INF/services directory named com.hcl.domino.keep.info.richtext.spi.IncomingRichtextProcessor.
Edit the created file to include all your created Rich Text processors. For example:
```
com.example.AlwaysHiIncomingRichtextProcessor
```
Important

All classes declared in this file must exist and implement the IncomingRichtextProcessor interface. Otherwise, Domino REST API will fail to load them, causing an error.

Create outgoing Rich Text processor

Create a class that implements OutgoingRichtextProcessor.

Example

The following code shows an example Java class that implements the OutgoingRichtextProcessor to create a custom outgoing Rich Text processor. This custom processor intercepts rich text items from Domino documents and always returns a fixed JSON response containing “Hello!” as plain text, ignoring the actual document content.

package com.example;

import com.hcl.domino.DominoClient;
import com.hcl.domino.data.Document;
import com.hcl.domino.keep.info.richtext.spi.OutgoingRichtextProcessor;

import io.vertx.core.json.JsonObject;

/**
 * Always returns "Hello!" in the content of the Rich Text JSON response.
*/
public class AlwaysHelloRichtextProcessor implements OutgoingRichtextProcessor {

  @Override
  public String getProcessorName() {
    return "alwayshello";
  }

  @Override
  public JsonObject process(DominoClient client, Document doc, String itemName) {
    return new JsonObject()
        .put("type", "text/plain")
        .put("encoding", "plain")
        .put("content", "Hello!");
  }

}

Create a file within the src/main/resources/META-INF/services directory named com.hcl.domino.keep.info.richtext.spi.OutgoingRichtextProcessor.
Edit the created file to include all your created Rich Text processors. For example:
```
com.example.AlwaysHelloRichtextProcessor
```
Important

All classes declared in this file must exist and implement the OutgoingRichtextProcessor interface. Otherwise, Domino REST API will fail to load them, causing an error.

Apply the Rich Text extension

Once you have created your Rich Text extension, you now need to build and deploy it.

Build the JAR file for the Rich Text extension by running the following command in your project root:
```
mvn clean package
```
This generates richtext-extension-1.0-SNAPSHOT.jar in the target/ directory.
Copy the generated JAR file to your Domino REST API installation directory, where the KEEP JARs are located.

Test your Rich Text extension

After building and deploying your Rich Text extension, you can now test it.

Test your incoming Rich Text processor

Create a form with a richtext field and ensure the value of the type property matches the name of your incoming Rich Text processor. As shown in the following example, the richtext field is rtfield and the value of the type property is set to alwayshi, which is returned by the getProcessorName() method of the example incoming Rich Text processor.

{
  ...
  "Form": "SampleForm",
  "rtField": {
    "type": "alwayshi",
    "encoding": "plain",
    "content": "my content"
  },
  ...
}

Before executing the request, make sure to set the value of the richTextAs query parameter to plain, so you can verify the value of the richtext field in plain text. After executing the request, you should get the following JSON for the richtext field:

{
  "type": "text/plain",
  "encoding": "plain",
  "content": "Hi!"
}

Test your outgoing Rich Text processor

To test your outgoing Rich Text processor, you can call any API that has a richTextAs query parameter. You just need to make sure that the value of the richTextAs query parameter is set to the name of your processor.

For example, using AlwaysHelloRichtextProcessor whose getProcessorName() method returns alwayshello, and performing an API call with richTextAs=alwayshello, you should get the following JSON value for the richtext fields:

{
  "type": "text/plain",
  "encoding": "plain",
  "content": "Hello!"
}

Used by default if the value of the type property in the Rich Text JSON doesn't equate to any existing Rich Text processor. ↩