Editable Ranges

Overview

This guide shows how to mark parts of a protected Word document as editable in Java, read the ranges back and remove them with Aspose.Words FOSS for Java. An editable range is meant to mark a part of a document that stays editable when the rest of the document is protected. DocumentBuilder.startEditableRange() returns an EditableRangeStart, endEditableRange() closes it and EditableRangeStart.getEditableRange() returns the EditableRange that describes the pair, with an id and a remove() method. Protection itself is set with Document.protect, as in the protection guide. The examples below were compiled and run on Java 8, 17 and 21 with identical output. They check the saved file for the ranges and for the protection type; they do not open the file in Word, so they do not show how Word enforces the range.


Prerequisites

RequirementDetail
Java8 or later
DependencyThe package from Installation
Importimport com.aspose.words.*;
CodeThe examples are statements. Put them in a method that declares throws Exception.

Mark an Editable Range in a Protected Document

Write the locked text, call startEditableRange, write the text that may change, call endEditableRange and protect the document with ProtectionType.READ_ONLY and a password. The range had the id 0 and the paragraph that holds it read Fill in your name: [type here]. After saving and reloading, the protection type was READ_ONLY and the document contained 1 editable range start and 1 editable range end.

import com.aspose.words.*;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("This sentence stays locked.");
builder.write("Fill in your name: ");

EditableRangeStart start = builder.startEditableRange();
builder.write("[type here]");
builder.endEditableRange();
builder.writeln("");
builder.writeln("This sentence is locked too.");

EditableRange range = start.getEditableRange();
System.out.println("Editable range id: " + range.getId());
System.out.println("Text of the paragraph that holds the range: " + range.getEditableRangeStart().getParentNode().getText().trim());

doc.protect(ProtectionType.READ_ONLY, "secret");
doc.save("form.docx");

Document reloaded = new Document("form.docx");
System.out.println("Protection after reload: " + ProtectionType.getName(reloaded.getProtectionType()));
NodeCollection starts = reloaded.getChildNodes(NodeType.EDITABLE_RANGE_START, true);
NodeCollection ends = reloaded.getChildNodes(NodeType.EDITABLE_RANGE_END, true);
System.out.println("Editable range starts: " + starts.getCount() + ", ends: " + ends.getCount());

The program printed:

Editable range id: 0
Text of the paragraph that holds the range: Fill in your name: [type here]
Protection after reload: READ_ONLY
Editable range starts: 1, ends: 1

Remove an Editable Range

EditableRange.remove() removes a range from the document. The example created two ranges, removed the second and counted the EDITABLE_RANGE_START nodes: 2 before and 1 after. The text still read first area and second area.

import com.aspose.words.*;

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
EditableRangeStart first = builder.startEditableRange();
builder.write("first area");
builder.endEditableRange();
builder.write(" and ");
EditableRangeStart second = builder.startEditableRange();
builder.write("second area");
builder.endEditableRange();
builder.writeln("");

System.out.println("Ranges before: " + doc.getChildNodes(NodeType.EDITABLE_RANGE_START, true).getCount());
second.getEditableRange().remove();
System.out.println("Ranges after remove: " + doc.getChildNodes(NodeType.EDITABLE_RANGE_START, true).getCount());
System.out.println("Text is unchanged: " + doc.getText().trim());

The program printed:

Ranges before: 2
Ranges after remove: 1
Text is unchanged: first area and second area

Tips and Best Practices

  • Call startEditableRange just before the text that may change and endEditableRange right after it, as both examples do.
  • Document.protect takes the protection type and a password, as in the protection guide. The first example used ProtectionType.READ_ONLY.
  • Count the ranges with getChildNodes(NodeType.EDITABLE_RANGE_START, true) and NodeType.EDITABLE_RANGE_END. After a save and reload each count was 1 in the first example.
  • A new range had an empty single user (getSingleUser() returned an empty string) in a test. The reference page describes editorGroup as an alias used to determine whether the current user may edit the range; the examples use neither setSingleUser nor setEditorGroup.

Common Issues

IssueCauseFix
The compiler reports cannot find symbol for Document.The com.aspose.words package is not imported.Add import com.aspose.words.*;.
The compiler reports an unreported exception.The Document constructors, Document.save and some other methods declare throws Exception.Declare it on the calling method or catch it.
I cannot tell from the code whether Word lets a reader edit the range.The examples read the saved file; they do not run Word.Open the saved document in Word to check the behaviour you need.
remove() on the range left the text in place.Removing an editable range removes the markers, not the text between them.Remove the text separately if you also want it gone.

FAQ

How do I make part of a document editable?

Wrap it in startEditableRange and endEditableRange and protect the document, as the first example does. Word is expected to enforce the range; that was not tested here.

How do I find the ranges of a document?

Call getChildNodes(NodeType.EDITABLE_RANGE_START, true) on the document.

How do I remove one?

editableRangeStart.getEditableRange().remove(), as the second example does.

Which formats were tested?

Only DOCX: the first example saves and reloads a DOCX file.


API Reference Summary

Class / MethodDescription
EditableRangeRepresents a single editable range.
EditableRangeStartRepresents a start of an editable range in a Word document.
DocumentBuilder.startEditableRange()Marks the current position in the document as an editable range start.
DocumentBuilder.endEditableRange()Marks the current position in the document as an editable range end.
EditableRange.remove()Removes the editable range from the document.
EditableRange.getId()Gets the editable range identifier.

Related Guides