Loading TOC...

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.

Parameters
node A node to run entity highlight on. The node must be either a document node or an element node; it cannot be a text node.
callback A callback function that is invoked on each match. See the Usage Notes for details.
builder A NodeBuilder object that will be used to construct the highlighted copy of the input node.
dict The entity dictionary to use for matching entities in the text of the input node. If you omit this parameter, the default entity dictionary is used. (No default dictionaries currently exist.) See the Usage Notes for details.

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:

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>

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.