Skip to content

ES-964213 - Add UG document for APIs to set editable ranges in protected DOCX documents #344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 16, 2025
Merged

ES-964213 - Add UG document for APIs to set editable ranges in protected DOCX documents #344

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7cbb0a2
ES-958622-EditableRange
DharanyaSakthivel-SF4210 Jun 12, 2025
9182854
ES-958622-EditableRange
DharanyaSakthivel-SF4210 Jun 16, 2025
1349bdd
ES-958622-EditableRange
DharanyaSakthivel-SF4210 Jun 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 252 additions & 0 deletions java-file-formats/word-library/working-with-security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,255 @@ document.close();
{% endhighlight %}

{% endtabs %}

## Editable ranges

An **editable range** is a portion of a Word document that allows editing even when the document is protected. In the Syncfusion .NET Word library (DocIO), editable ranges are represented using the **EditableRange** class. You can define these ranges programmatically to allow user edits within protected documents.

### Add an editable range

You can add an editable range to a Word document using the **appendEditableRangeStart()** and **appendEditableRangeEnd()** methods of the **WParagraph** class.

The following code example illustrates how to add an editable range in the Word document.

N> 1. DocIO supports editable ranges in DOCX format documents only.

{% tabs %}

{% highlight JAVA %}
// Create a Word document
WordDocument document = new WordDocument();
// Ensure at least one section and one paragraph exists
document.ensureMinimal();
// Access the last paragraph
WParagraph paragraph = document.getLastParagraph();
// Append initial text to the paragraph
paragraph.appendText("Adventure Works Cycles, the fictitious company on which the AdventureWorks ");
// Add an editable range to the paragraph
EditableRangeStart editableRangeStart = paragraph.appendEditableRangeStart();
// Append editable text
paragraph.appendText("sample databases are based, is a large, multinational manufacturing company.");
// End the editable range
paragraph.appendEditableRangeEnd(editableRangeStart);
// Protect the document and allow only reading
document.protect(ProtectionType.AllowOnlyReading, "password");
// Save the document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

### Retrieve Id of an editable range

You can retrieve the ID of an editable range using the **getId()** method of the **EditableRange** class.

The following code example illustrates how to retrieve the ID of an editable range from a Word document.

{% tabs %}

{% highlight JAVA %}
// Create a Word document
WordDocument document = new WordDocument();
// Ensure the document has at least one section and one paragraph
document.ensureMinimal();
// Access the last paragraph
WParagraph paragraph = document.getLastParagraph();
// Append text before editable range
paragraph.appendText("Adventure Works Cycles, the fictitious company on which the AdventureWorks ");
// Append editable range start
EditableRangeStart editableRangeStart = paragraph.appendEditableRangeStart();
// Append editable content
paragraph.appendText("sample databases are based, is a large, multinational manufacturing company.");
// Append editable range end
paragraph.appendEditableRangeEnd(editableRangeStart);
// Retrieve editable range ID
String editableRangeId = editableRangeStart.getId();
// Protect the document to allow only reading
document.protect(ProtectionType.AllowOnlyReading, "password");
// Save the document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

### Find an editable range

You can find an editable range by its ID in the **EditableRangeCollection** using the **findById()** method.

The following code example illustrates how to find the editable range in a Word document.

{% tabs %}

{% highlight JAVA %}
// Load an existing Word document
WordDocument document = new WordDocument("Template.docx");
// Get the editable range by ID
EditableRange editableRange = document.getEditableRanges().findById("0");
// Save the document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

### Remove an editable range

You can remove an editable range using the **remove()** method of the **EditableRangeCollection** class.

The following code example demonstrates how to remove an editable range from a Word document.

{% tabs %}

{% highlight JAVA %}
// Load an existing Word document
WordDocument document = new WordDocument("Template.docx");
// Get the editable range by ID
EditableRange editableRange = document.getEditableRanges().findById("0");
// Remove the editable range
document.getEditableRanges().remove(editableRange);
// Save the Word document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

An editable range at a specific index can also be removed from the **EditableRangeCollection** using the **removeAt()** method.

The following code example demonstrates how to remove an editable range at particular index from a Word document.

{% tabs %}

{% highlight JAVA %}
// Load an existing Word document
WordDocument document = new WordDocument("Template.docx");
// Remove the editable range at index 1
document.getEditableRanges().removeAt(1);
// Save the Word document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

### Editing permission

You can restrict editable ranges to specific groups or individuals.

#### Group permission

You can make an editable range accessible to a specific group using the **setEditorGroup()** method of the **EditableRangeStart** class.

The following code example illustrates how to make an editable range available to a group in a Word document.

{% tabs %}

{% highlight JAVA %}
// Create a new Word document
WordDocument document = new WordDocument();
// Ensure the document has at least one section and one paragraph
document.ensureMinimal();
// Access the last paragraph
WParagraph paragraph = document.getLastParagraph();
// Append text before the editable range
paragraph.appendText("Adventure Works Cycles, the fictitious company on which the AdventureWorks ");
// Add an editable range start
EditableRangeStart editableRangeStart = paragraph.appendEditableRangeStart();
// Set the editor group to Everyone
editableRangeStart.setEditorGroup(EditorType.Everyone);
// Append text inside the editable range
paragraph.appendText("sample databases are based, is a large, multinational manufacturing company.");
// Add the editable range end
paragraph.appendEditableRangeEnd(editableRangeStart);
// Protect the document with a password, allowing only reading
document.protect(ProtectionType.AllowOnlyReading, "password");
// Save the Word document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

#### Single user permission

Use the **setSingleUser()** method to assign editing permissions to a specific user.

The following code example illustrates how to make an editable range available to a single user in a Word document.

{% tabs %}

{% highlight JAVA %}
// Create a new Word document
WordDocument document = new WordDocument();
// Ensure the document has at least one section and one paragraph
document.ensureMinimal();
// Access the last paragraph
WParagraph paragraph = document.getLastParagraph();
// Append text before the editable range
paragraph.appendText("Adventure Works Cycles, the fictitious company on which the AdventureWorks ");
// Add an editable range start
EditableRangeStart editableRangeStart = paragraph.appendEditableRangeStart();
// Set the single user allowed to edit this range
editableRangeStart.setSingleUser("\"user@domain.com\"");
// Append text inside the editable range
paragraph.appendText("sample databases are based, is a large, multinational manufacturing company.");
// Add the editable range end
paragraph.appendEditableRangeEnd(editableRangeStart);
// Protect the document with a password, allowing only reading
document.protect(ProtectionType.AllowOnlyReading, "password");
// Save the Word document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

### Add editable range in a table

Using the **setFirstColumn()** and **setLastColumn()** methods of the **EditableRangeStart** class, you can specify the starting and ending columns of an editable range within a table.

The following code example illustrates how to add an editable range inside a table in a Word document.

{% tabs %}

{% highlight JAVA %}
// Load an existing Word document
WordDocument document = new WordDocument("Data/Template.docx");
// Access the first table in the first section
WTable table = (WTable) document.getSections().get(0).getTables().get(0);
// Access the paragraph in the 3rd row and 3rd column (index 2,2)
WParagraph paragraph = (WParagraph) table.getRows().get(2).getCells().get(2).getChildEntities().get(0);
// Create a new editable range start for the paragraph
EditableRangeStart editableRangeStart = new EditableRangeStart(document);
// Insert the editable range start at the beginning of the paragraph
paragraph.getChildEntities().insert(0, editableRangeStart);
// Set the editor group to allow everyone to edit
editableRangeStart.setEditorGroup(EditorType.Everyone);
// Apply editable range to the second column only (index 1)
editableRangeStart.setFirstColumn((short) 0);
editableRangeStart.setLastColumn((short) 1);
// Access another paragraph in the 6th row, 3rd column (index 5,2)
paragraph = (WParagraph) table.getRows().get(5).getCells().get(2).getChildEntities().get(0);
// Append an editable range end to close the region
paragraph.appendEditableRangeEnd();
// Protect the document with a password and allow only reading
document.protect(ProtectionType.AllowOnlyReading, "password");
// Save the Word document
document.save("EditableRange.docx", FormatType.Docx);
// Close the document
document.close();
{% endhighlight %}

{% endtabs %}

N> 1. Editable ranges are supported only in DOCX format.
N> 2. The **SingleUser** and **EditorGroup** properties cannot be set simultaneously for the same editable range. Setting one will clear the other.