Add Comment Ranges to Word Document using Aspose.Words for .NET and Java

Facebook

Twitter

Linkedin

Comments in Microsoft Word

A comment is an annotation that an author or reviewer adds to a document. Microsoft Word displays the comment in a balloon in the margin of the document. To add a comment a user selects a range of text and clicks New Comment in the Review pane. The created comment is anchored to the selected range of text.

Comments in Aspose.Words

Earlier versions of Aspose.Words supported comments in documents but did not support comment ranges. If you simply loaded and saved the document shown above in Aspose.Words, the comment in the resulting document would appear anchored to a position in the text just after the word “include” rather than to the complete range “the galleries include”.

Now, Aspose.Words for .NET 8.2.0 and Aspose.Words for Java 4.0.2 fully support comment ranges in DOC, DOCX, RTF, and WordprocessingML formats and also provide a complete public API to programmatically work with comments and comment ranges.

The following screenshot shows how a comment with a range is represented in the Aspose.Words object model.

The comment itself is represented by the Comment class. This class provides properties to get/set the author and date of the comment. The Comment class is also a container for the text of the comment and can contain block-level nodes Parapraph and Table.

The two new classes that we have added are CommentRangeStart and CommentRangeEnd to represent the comment range.

This structure is very similar to the OOXML w:commentReference, w:comment, w:commentRangeStart, w:commentRangeEnd elements. The only notable difference is that in OOXML the text of the comment itself is stored quite far away – in a separate document part. To the users of Aspose.Words it looks as if w:comment is stored directly instead of w:commentReference. This makes programming somewhat easier by removing one extra layer to navigate.

The comment and comment range are “linked” into a single entity via the Id attribute. The Id attribute must be the same for Comment, CommentRangeStart and CommentRangeEnd. The Id attribute in the Comment class is read-only and its value is generated by Aspose.Words. But the Id attribute in CommentRangeStart and CommentRangeEnd can be set to any value to link with any Comment object in the document.

The important requirement for a comment range to be valid is that CommentRangeStart must occur before CommentRangeEnd. The Comment object normally occurs immediately after the CommentRangeEnd object, but in fact, the Comment object can be anywhere in the document in relation to its range.

Here is how you can create a comment range in code. The screenshot is taken on Ubuntu 9.04, by the way, using Aspose.Words for Java.

Below is how you can create a comment using Aspose.Words for .NET. This time the DocumentBuilder object is used.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.Write(“A bit of text”);
// Create a comment that has a range. Typically, the comment is just after the
// comment range end node, but actially it can be anywhere. In this case inside the comment range.
Comment comment = new Comment(doc);
comment.SetText(“This is my comment 1.”);
builder.InsertNode(new CommentRangeStart(doc, comment.Id));
builder.Write(“Some text.”);
builder.InsertNode(comment);
builder.Write(” More text.”);
builder.InsertNode(new CommentRangeEnd(doc, comment.Id));

Behind the Scenes

As you would expect, Aspose.Words does a good deal of plumbing work behind the scenes to make your life working with documents easier. I just want to briefly mention some things that Aspose.Words does for you that you might not even notice:

• Maintain the integrity of comments when you copy comments from one document into another or combine documents. Aspose.Words ensures comment identifiers do not duplicate and copied comments still maintain their links between the comment and the range.

• Validate comments and comment ranges during document save. This includes removed orphaned or invalid comment ranges.

Download

To download comment ranges and other great features supported in Aspose.Words see Aspose.Words for .NET Downloads and Aspose.Words for Java Downloads.