Richtext extension

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

Extend Domino REST API richtext

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

Built-in richtext processors

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

mime
html
markdown
plain

Set up extending richtext

There are a number of things you should setup 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 richtext.

Extending richtext 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.0.12</version>
    </dependency>
    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-core</artifactId>
      <version>4.5.7</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 richtext extension project.

Extend richtext

Set up richtext extension project

Create a new project for the richtext 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.

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 be compiled together with your richtext extension as you will be putting the extension JAR alongside the KEEP JARs. The KEEP JARs will contain all the dependencies that your extension JAR will need.

Create your own richtext processor

Create your richtext processor.

Any class will do, as long as it implements RichtextProcessor. As of this writing, RichtextProcessor has three methods, two of which needs to be overwritten. These methods are:

/**
* Get the name of the richtext processor. This should equate to the value of
* {@code richTextAs} query parameter (case insensitive), and will be used to
* determine which richtext processor provider will execute.
* 
* @return a {@code String} describing the processor's name
*/
String getProcessorName();

/**
* Execute richtext processor.
* 
* @param client {@code DominoClient} with API access
* @param doc Domino document with source data
* @param itemName field item name (internal name)
* @return a {@code JsonObject} that contains the converted richtext and other
*         properties
*/
JsonObject process(DominoClient client, Document doc, String itemName);

/**
* Used for processors that has the same name to determine what will be used. The higher
* the number, the higher the priority.
* 
* @return an {@code int} representing the priority of the processor
*/
default int getPriority() {
  return 0;
}

An example richtext 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.RichtextProcessor;

import io.vertx.core.json.JsonObject;

public class AlwaysHelloRichtextProcessor implements RichtextProcessor {

  @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.RichtextProcessor.
Edit the file com.hcl.domino.keep.info.richtext.spi.RichtextProcessor and include all the richtext extensions you created, such as:
```
com.example.AlwaysHelloRichtextProcessor
com.example.MyOwnRichtextProcessor
```

Important

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

Apply the richtext extension

Once you have finished creating your richtext extension, it's time to use it. Create the JAR file for the richtext 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

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!"
}