cts.highlight

cts.highlight(
   node as Node,
   query as cts.query,
   callback as function(NodeBuilder, xs.string, text(), cts.query*, xs.integer) as xs.string?,
   builder as NodeBuilder
) as null

Summary

Returns a copy of the node, replacing any text matching the query with the specified expression. You can use this function to easily highlight any text found in a query. Unlike fn.replace and other string functions that match literal text, cts.highlight matches every term that matches the search, including stemmed matches or matches with different capitalization.

Parameters
node	A node to highlight. The node must be either a document node, element node, object node, or array node; it cannot be a text node.
query	A query specifying the text to highlight. If a string is entered, the string is treated as a `cts:word-query` of the specified string.
callback	A function to call on each match.
builder	The builder that will be used to construct the highlighted copy.

Usage Notes

The arguments to the callback function provide context for the match.

builder as NodeBuilder

An Node builder that is building the highlighted node copy. Whetever the callback adds to the builder will be added to the final copy.

text as xs:string

The matched text.

node as text()

The node containing the matched text.

queries as cts:query*

The matching queries.

start as xs:integer
The string-length position of the first character of text in node. Therefore, the following always returns true:
fn.substring(node, start,
             fn.stringLength(text)) = text 

The return from the callback function is an action that specifies what happens next:

"continue": (default) Walk the next match. If there are no more matches, return all the builder results .
"skip": Skip walking any more matches and return all the builder results.
"break": Stop walking matches and return all the builder results.
null: Continue with the previous action.

You cannot use cts.highlight to highlight results matching cts:similar-query and cts:element-attribute-*-query items. Using cts.highlight with these queries will return the nodes without any highlighting.

You can also use cts.highlight as a general search and replace function. The specified expression will replace any matching text. For example, you could replace the word "hello" with "goodbye" in a query similar to the following:

 cts.highlight(node, "hello",
	function(builder, text, node, queries, start) {
	builder.addText("goodbye");
	});

Unfiltered queries, including registered queries, do not match in cts.walk or cts.highlight.

Example

// To highlight "MarkLogic" with bold in the following paragraph:

var doc = new NodeBuilder();
doc.startElement("p");
doc.addText("MarkLogic Server is an enterprise-class\n\
  database specifically built for content.");
doc.endElement();

var result = new NodeBuilder();
cts.highlight(doc.toNode(), "MarkLogic",
  function(builder,text,node,queries,start) {
    builder.startElement("b");
    builder.addText(text);
    builder.endElement(); }, result);
result.toNode()

=>

  <p><b>MarkLogic</b> Server is an enterprise-class
  database specifically built for content.</p>

Example

// Similar to the above use case but on JSON nodes. Note that
// an array is used to represent the original text with the
// specified object node as a member.

var x = {"p1":
  "MarkLogic Server is an enterprise-class database built for content."};
var result = new NodeBuilder();
cts.highlight(x, "MarkLogic",
  function(builder,text,node,queries,start) {
    builder.addNode( {"highlighted" : text} );
  }, result
);
result.toNode();

=>

  {
    "p1": [
      {
        "highlighted": "MarkLogic"
      },
     " Server is an enterprise-class database built for content."
    ]
  }

Example

// Also on JSON nodes but the query matches the whole node. In this case,
// no array node is created.

var x = { "p1" : "MarkLogic Server"};
var result = new NodeBuilder();
cts.highlight(x, "MarkLogic Server",
  function(builder,text,node,queries,start) {
    builder.addNode( {"highlighted" : text} )
  }, result
);
result.toNode();

Returns:

  {
    "p1": {
      "highlighted": "MarkLogic Server"
    }
  }

Example

// Given the following document with the URI "hellogoodbye.xml":

<root>
  <a>It starts with hello and ends with goodbye.</a>
</root>

******

// The following query will highlight the word "hello" in
// blue, and everything else in red.

var result = new NodeBuilder();
cts.highlight(cts.doc("hellogoodbye.xml"),
     cts.andQuery([cts.wordQuery("hello"),
                   cts.wordQuery("goodbye")]),
  function(builder, text, node, queries, start) {
    builder.startElement("font");
    if (cts.wordQueryText(queries) == "hello") {
      builder.addAttribute("color","blue");
      builder.addText(text);
      builder.endElement(); }
    else {
      builder.addAttribute("color","red");
      builder.addText(text);
      builder.endElement(); }
  }, result
);
result.toNode();

=>

<root>
  <a>It starts with <font color="blue">hello</font>
  and ends with <font color="red">goodbye</font>.</a>
</root>

Example

var results = [];
for (var x of cts.search("MarkLogic")) {
  var result = new NodeBuilder();
  cts.highlight(x,"MarkLogic",
    function(builder, text, node, queries, start) {
      builder.startElement("b");
      builder.addText(text);
      builder.endElement();
    }, result);
  results.push(result.toNode());
};
results;

returns an array with all of the nodes that contain "MarkLogic",
placing bold markup (<b> tags) around the matched words.