MarkLogic 12 Product Documentation

cts.entityHighlight

cts.entityHighlight(
   node as Node,
   callback as function,
   builder as NodeBuilder,
   [dict as cts.entityDictionary]
) as null

Summary

Returns a copy of the node, replacing any entities found with the specified expression. You can use this function to easily highlight any entities in an XML document in an arbitrary manner. If you do not need fine-grained control of the XML markup returned, you can use the entity.enrich javascript function instead. A valid entity enrichment license key is required to use cts.entityHighlight; without a valid license key, it throws an exception. If you have a valid license for entity enrichment, you can entity enrich text in English and in any other languages for which you have a valid license key. For languages in which you do not have a valid license key, cts.entityHighlight finds no entities for text in that language.

Usage Notes

In addition to a valid Entity Enrichment license key, this function requires that you have installed the Entity Enrichment package. For details on installing the Entity Enrichment package, see the Installation Guide and the "Marking Up Documents With Entity Enrichment" chapter of the Search Developer's Guide.

There are six built-in variables to represent an entity match. These variables can be used inline in the expression parameter.

builder

The NodeBuilder object used to build the highlighted node copy. Anything you add to builder is added to the final result. This is the same builder you pass in as the builder parameter of cts.entityHighlight

entityType

A string containing the type of the entity, as defined in the type field of the matched cts.entity in the entity dictionary.

text

A string containing the matched text. In the case of overlapping matches, this value may not encompass the entirety of the entity match string. Instead, it contains only the non-overlapping part of the text, to prevent introduction of duplicate text in the final result.

normText

A string containing the normalized label of the entity, as defined in the normalized field of the matched entity in the entity dictionary.

entityId

A string containing the ID of the entity, as defined in the id field of the matched entity in the entity dictionary.

node

The text node containing the match.

start

The offset (in codepoints) of the start of text in the matched text node.

Your callback function should return one of the following values to indicate what should happen next:

• 'continue': Proceed with the next match. (Default)
• 'skip': Skip walking any more matches and return all builder results.
• 'break': Stop walking matches and return all builder results.
• null: Continue with the previous action.

Example

'use strict';
const dictionary = cts.entityDictionary([
  cts.entity('11208172', 'Nixon', 'Nixon', 'person'),
  cts.entity('11208172', 'Nixon', 'Richard Nixon', 'person'),
  cts.entity('11208172', 'Nixon', 'Richard M. Nixon', 'person'),
  cts.entity('11208172', 'Nixon', 'Richard Milhous Nixon', 'person'),
  cts.entity('11208172', 'Nixon', 'President Nixon', 'person'),
  cts.entity('08932568', 'Paris', 'Paris', 'district:national capital'),
  cts.entity('09145751', 'Paris', 'Paris', 'district:town')
]);
const inputNode = new NodeBuilder()
                   .addElement('node', 'Richard Nixon never visited Paris.')
                   .toNode();
const resultBuilder = new NodeBuilder();
cts.entityHighlight(inputNode,
  function(builder, entityType, text, normText, entityId, node, start) {
    if (text != '') {
      builder.addElement(fn.replace(entityType, ':| ', '-'), text);
    } 
  },
  resultBuilder, dictionary);
resultBuilder.toNode();

// Returns output similar to the following. (Whitespace has been added
// here to improve readability.)
// 
// <node>
//   <person>Richard Nixon</person> never visited 
//   <district-national-capital>Paris</district-national-capital>.
// </node>