Range

The concept of Range is similar to Range Object in MS Word API. Working with a range is much closer to how a user interacts with a document in MS Word.

A range is basically a contiguous area in a document. It is signified as a pair of positions (START, END), where a coordinate of START always less than a coordinate of END. It may span across multiple sections, paragraphs, etc., in other words, across different nodes of the DOM tree. Thus, a user can ignore the underlying model of the document. Such an approach is going to make the usage of API much more friendly.

Ways to Specify a Range

A range can be specified in one of the three ways:

Position in a document based on nodes IDs

/range/{startId}/{endId}

, where:

  • {startId} - id of the node from which the range starts (included). Required.
  • {endId} - id of the node at which the range ends (excluded). Optional. If missed, the end of the range corresponds to the end of the node with id = startId, i.e. the range is limited by the bounds of “startId node”.

The following is an example of a range consisting of the second and third paragraphs:

/range/id0.1/id0.3

Position in a document based on nodes pseudo names

/range/{startPseudoName}/{endPseudoName}

, where:

  • {startPseudoName} - a pseudo name of the node from which the range starts (included). Required.
  • {endPseudoName} - a pseudo name of the node at which the range ends (excluded). Optional. If missed, the end of the range corresponds to the end of the node with pseudoname = startPseudoName, i.e. the range is limited by the bounds of “startPseudoName node”.

The following PseudoNames are available:

  • TableN for tables.
  • ImageN for images.

An example of a range, consisting of the text from the first table and after the table till the second table, is presented below:

/range/table0/table1

Positions inside nodes

A certain position inside a node can be specified with a selector that is separated from a node identifier with a colon.

/range/{startIdentifier}:{startSelector}/{endIdentifier}:{endSelector}

, where:

  • {startIdentifier} - an identifier (id or a pseudo name) of the node from which the range starts (included). Required.
  • {endIdentifier} - an identifier (id or a pseudo name) of the node at which the range ends (excluded). Optional. If missed, the end of the range corresponds to the end of the node with identifier = startIdentifier, i.e. the range is limited by the bounds of “startIdentifier node”.
  • {startSelector} - a selector that specifies a certain position inside the start node (included). Optional. If missed, the start of the range corresponds to the beginning of the start node.
  • {endSelector} - a selector that specifies a certain position inside the end node (excluded). Optional. If missed, the end of the range corresponds to the element before the beginning of the end node.

Selectors cannot be used without a node identifier.

The following Selectors are available:

  • end - specifies the end of the node (“end” here is supposed to be a virtual node after the last child node, i.e. it means that the whole content of the node should be included for an end node).

An example of a range, consisting of all nodes starting from the end of the 1st table till the beginning of the 6th paragraph, is presented below:

/range/table0:end/id0.5

Operations with a Range

The following operations can be defined on a range:

Get the text from the range

Get the text from all nodes in the range. You may use one of the following two APIs to get the text from the range:

Remove the text from the range

With the following APIs you can remove the text from the range. Text from all nodes inside the range would be removed.

Replace the content in the range

The replacement should be done according to MS Word rules. For example, several nodes, except the case when all nodes are runs of one paragraph, should be replaced with one new paragraph. However, several runs in one paragraph should be replaced with the new run(s). The style should be consistent to removed nodes.

Content in the range can be replaced with one of the following two APIs:

Save the selected range as a new document

The range should be saved as a separate document. The original document must not be changed. The said task can be achieved with one of the following two APIs:

Use cases

Some of the common use cases are presented below.

Use case 1. A user wants to get a text from the first two paragraphs in the document

First, he needs to call Paragraph API to get a list of paragraphs that are contained in a document.

He sees that the first two paragraphs correspond to id0.0 and id0.2 (NodeId in the response), so he calls Range API to get the text he requires:

Use case 2. A user wants to save the selected range as a new document

First, he needs to call Paragraph API to get a list of paragraphs that are contained in a document.

Now, he calls the following API to save the first two paragraphs (correspond to id0.0 and id0.2 in the response) as a new document:

Cloud SDK Family

Using an SDK is the best way to speed up the development. An SDK takes care of low-level details and lets you focus on your project tasks. Please check out the GitHub repository for a complete list of Aspose.Words Cloud SDKs.

The following set of Code Examples for various SDKs demonstrates how to use this REST API in your projects.

Use case 1. Get text from the first two paragraphs in the document.

Use case 2. Save the selected range as a new document.