Rich Text extension

Rich Text extension is for customers or users that prefer to have or use their own implementation of Rich Text processor. Users will be able to adjust it to meet their own needs, resulting in a better representation of their Rich Text.

Extend Domino REST API Rich Text

Starting Domino REST API version 1.0.12, you can now add Rich Text processors for Domino REST API.

Built-in Rich Text processors

There has been no change for the existing processors, namely:

mime
html
markdown
plain

Set up extending Rich Text

There are a number of things you should set up before you can create an extension.

Install KEEP core jar

Install Domino REST API using the Domino REST API installer.
Find the keep-core-<version>.jarin the Domino REST API install directory and do a Maven install using the following command:

mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile=<path-to-keep-core-jar>

This adds KEEP Core to your local Maven M2 repository.

Create an extension helper

The goal is to create an extension helper that generates a single JAR file containing all the dependencies needed in extending Rich Text.

Extending Rich Text needs the following dependencies:

KEEP core
Vert.X core
Domino JNX API

To create an extension helper:

Create a new folder. Any folder name will do and can be placed in any directory.

Create a pom.xml file in the created folder. The file should have the following content:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.hcl.domino.extension.helper</groupId>
  <artifactId>keep-richtext-extension-helper</artifactId>
  <version>1.0</version>
  <name>Helper for KEEP richtext extension</name>
  <description>Don't try this at home</description>

  <dependencies>
    <dependency>
      <groupId>com.hcl.domino.keep</groupId>
      <artifactId>keep-core</artifactId>
      <version>1.31.2</version>
    </dependency>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-core</artifactId>
      <version>4.5.8</version>
    </dependency>
    <dependency>
      <groupId>com.hcl.domino</groupId>
      <artifactId>domino-jnx-api</artifactId>
      <version>1.41.0</version>
    </dependency>
  </dependencies>

</project>

Save the pom.xml and execute the following command:
```
mvn clean install
```
Executing the command generates a keep-richtext-extension-helper-1.0.jar file in the target directory. It will include this JAR file in your local Maven M2 repository, allowing you to use it as a dependency for your Rich Text extension project.

Extend Rich Text

Set up Rich Text extension project

Create a new project for the Rich Text extension by creating a new Maven project using the following command:
```
mvn archetype:generate -DgroupId=com.example -DartifactId=richtext-extension -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
```
The command generates a directory called richtext-extension, including a src folder and a pom.xml file.
Open the pom.xml file and change the settings of maven.compiler.source and maven.compiler.target to 1.8 for Domino r12. For Domino r14, change it to 17.

Under the dependencies section, include the JAR file that was generated by your extension helper earlier:

<dependency>
  <groupId>com.hcl.domino.extension.helper</groupId>
  <artifactId>keep-richtext-extension-helper</artifactId>
  <version>1.0</version>
  <scope>provided</scope>
</dependency>

Save the pom.xml after adding the dependency.

Note

The scope is set to provided because you don't want the dependency to be compiled together with your Rich Text extension as you will be putting the extension JAR alongside the KEEP JARs. The KEEP JARs contain all the dependencies that your extension JAR needs.

Creating your own Rich Text processors

There are 2 different interfaces that you can implement to create your own Rich Text processor, IncomingRichtextProcessor and OutgoingRichtextProcessor.

Incoming Rich Text processor

This processes how the incoming Rich Text JSON is saved in the richtext field. This processor makes use of the type property in Rich Text JSON to determine what incoming Rich Text processor to use.

Built-in incoming Rich Text processors

There are four built-in incoming Rich Text processors:

multipart/mixed - used by default if type in Rich Text JSON doesn't equate to any existing Rich Text processor.
text/plain
text/markdown
text/html

Creating your own incoming Rich Text processor

Create a class that implements IncomingRichtextProcessor.

Currently, IncomingRichtextProcessor has three methods. Two of which have default implementations.

getProcessorName is an abstract method that should return a String that represents the name of the incoming Rich Text processor. It checks this against the type property of a Rich Text JSON to determine if this incoming processor should be used.

process is a method that has a default implementation. By default, it checks if the incoming content of the Rich Text JSON looks like a mime and directly returns it as a Buffer. If not, it manually constructs a mime using the Rich Text JSON properties, and return the constructed mime as a Buffer. You are also free to override this method and control how you want to save the incoming Rich Text.

getPriority is a default method that returns 0. You can leave this method be, unless you have an incoming Rich Text processor that has the same return value of getProcessorName with other existing incoming Rich Text processors. The higher the number, the higher the priority.

An example incoming Rich Text processor will be:
```
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 within the src/main/resources/META-INF/services directory and name the file com.hcl.domino.keep.info.richtext.spi.IncomingRichtextProcessor.
Edit the file com.hcl.domino.keep.info.richtext.spi.IncomingRichtextProcessor and include all the Rich Text extensions you created, such as:
```
com.example.AlwaysHiIncomingRichtextProcessor
```

Important

All classes declared in this file must exist and implement the IncomingRichtextProcessor class. Otherwise, an error occurs when attempting to load this using Domino REST API.

Outgoing Rich Text processor

This processes how the saved data in a richtext field is shown when returned as a response to a GET request. This processor uses the value of the richTextAs query parameter to know which outgoing Rich Text processor to use.

Built-in outgoing Rich Text processors

There are four built-in outgoing Rich Text processors:

mime
plain
markdown
html

Creating your own outgoing Rich Text processor

Create a class that implements OutgoingRichtextProcessor.

Currently, OutgoingRichtextProcessor has three methods. One of which has default implementations.

getProcessorName is an abstract method that should return a String that represents the name of this incoming Rich Text processor. It checks this against the richTextAs query parameter of the GET request to know which outgoing Rich Text processor to use.

process is an abstract method that can be overwritten to specify how to represent the Rich Text content in the response.

getPriority is a default method that returns 0. You can leave this method be, unless you have an outgoing Rich Text processor that has the same return value of getProcessorName with other existing outgoing Rich Text processors. The higher the number, the higher the priority.

An example outgoing Rich Text processor would be:
```
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 and name the file com.hcl.domino.keep.info.richtext.spi.OutgoingRichtextProcessor.
Edit the file com.hcl.domino.keep.info.richtext.spi.OutgoingRichtextProcessor and include all the Rich Text extensions you created, such as:
```
com.example.AlwaysHelloRichtextProcessor
```

Important

All classes declared in this file must exist and implement the OutgoingRichtextProcessor class. Otherwise, an error occurs when attempting to load this using Domino REST API.

Apply the Rich Text extension

Once you have finished creating your Rich Text extensions, it's time to use it. Create the JAR file for the Rich Text extension by running the following command:

mvn clean package

This creates a JAR file inside the target directory with the name richtext-extension-1.0-SNAPSHOT.jar. Copy this JAR file and paste it into where your KEEP JARs are at (Domino REST API directory).

Try it out

Try the incoming Rich Text processor

Create a form that has a richtext field in it. An example response body would be:

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

Notice that the type in the Rich Text JSON is set to the name of your own incoming Rich Text processor alwayshi.

Before executing the request, you should set the value of 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!"
}

Try the outgoing Rich Text processor

To try it out, you can call any API that has a richTextAs query parameter, and set its value to your processor name.

For example, if you use the AlwaysHelloRichtextProcessor, since its getProcessorName method returns alwayshello, if you do an API and set richTextAs=alwayshello, you should get the following JSON value for the richtext fields:

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