A powerful and flexible .NET library for programmatically creating, reading, and modifying OpenDocument Text (.odt) files.
OdtKit simplifies the complexities of the ODF (OpenDocument Format) XML structure by providing a high-level, object-oriented API. It allows developers to treat ODT documents like object models, making it easy to perform complex manipulations such as template filling, table generation, and content editing, all while preserving the integrity of the document.
Key Features
Load and Save: Effortlessly read and write .odt documents from/to files, streams, or byte arrays.
Object-Oriented XML Manipulation: Interact with ODT elements (<text:p>, <table:table>, etc.) as strongly-typed C# objects.
Powerful Template Engine: Use simple C# objects with [Placeholder] attributes to dynamically fill text and image placeholders in your ODT templates.
Advanced Table Manipulation: Programmatically create, find, and modify tables. Add, remove, and clone rows with ease.
Image Embedding: Easily embed images into your documents and bind them to image placeholders.
Built-in Undo/Redo: All manipulations performed through the object wrapper API are automatically tracked, providing a complete history with undo/redo capabilities.
Type-Safe Element Wrappers: A comprehensive set of classes representing common ODT elements, reducing the need to work with raw XML and magic strings.
Installation
Install the package via the .NET CLI:
dotnet add package Codehard.OdtKit
Or through the NuGet Package Manager:
Install-Package Codehard.OdtKit
How It Works
OdtKit parses the content.xml of an ODT document into a standard XDocument. To enable safe and easy manipulation, it provides the Wrap() extension method. This method converts a raw XElement into a tree of XElementWrapper objects, which serve as intelligent, type-safe proxies to the underlying XML nodes.
All manipulations performed on these wrapper objects are automatically tracked in a history stack. For example, when you call table.Add(newRow), the library not only adds the XML element but also records an AddOperation. This architecture enables the powerful Undo/Redo feature and provides a robust, transactional way to manage document changes.
The XElementWrapper API
The XElementWrapper is the heart of OdtKit's manipulation capabilities. Once you Wrap() an XElement, you get access to a rich, object-oriented API.
Navigation
Easily traverse the XML tree using familiar properties.
Parent: Gets the parent element.
Children: Gets a read-only list of direct child elements.
Next: Gets the next sibling element.
Previous: Gets the previous sibling element.
GetSiblings(): Gets all siblings of the current element.
var paragraph = doc.Wrap().Descendants<PElement>().First();
// Get the element that comes right after the paragraph
var nextElement = paragraph.Next;
// Get all children of the paragraph's parent (i.e., its siblings)
var siblings = paragraph.Parent?.Children;
Manipulation
Modify the document structure with intuitive methods. All these operations are tracked in the history.
Add(XElementWrapper child): Adds a new child to the end of the element's children list.
AddAfterSelf(XElementWrapper sibling): Adds a new sibling immediately after the current element.
AddBeforeSelf(XElementWrapper sibling): Adds a new sibling immediately before the current element.
ReplaceWith(XElementWrapper newElement): Replaces the current element with a new one.
Remove(): Removes the current element from its parent.
RemoveNodes(): Removes all children of the current element.
// Get the first paragraph
var p = doc.Wrap().Descendants<PElement>().First();
// Create a new paragraph
var newP = new PElement(new XElement(OdtDocument.TextNamespace + "p", "A new paragraph."));
// Add it after the first one
p.AddAfterSelf(newP);
// Now, remove the original paragraph
p.Remove();
History (Undo/Redo)
Every wrapper maintains a link to the document's history. You can call Undo() or Redo() from any wrapper instance to revert or re-apply the last operation in the entire document.
Undo(): Reverts the last manipulation. Returns true if successful.
Redo(): Re-applies the last undone manipulation. Returns true if successful.
var root = doc.Wrap();
var p = root.Descendants<PElement>().First();
// Add a new paragraph
p.AddAfterSelf(new PElement(new XElement(OdtDocument.TextNamespace + "p", "New")));
doc.SaveAs("added.odt");
// The change was made via 'p', but we can undo it from the root
root.Undo();
doc.SaveAs("undone.odt");
// And redo it
root.Redo();
doc.SaveAs("redone.odt");
Querying and Templating
Descendants<T>(): Gets all descendant elements of a specific wrapper type (e.g., PElement, TableElement).
FillPlaceholders(object model): Finds all <text:placeholder> descendants and fills them with values from a model object marked with [Placeholder] attributes.
Core API Concepts
OdtDocument: The main class to load, save, and access the document's Content (as an XDocument).
OdtContainer: Manages the collection of files inside the ODT zip archive, including content.xml, images, and manifests.
XElementWrapper: The abstract base for all typed element wrappers. It provides the core manipulation, navigation, and history API.
XElementExtensions.Wrap(): An extension method on XElement that converts it into a specific XElementWrapper subclass (e.g., TableElement, PElement). This is your entry point into the typed API.
Representation Classes: Located in the Codehard.OdtKit.Representations namespace, these classes (TableElement, TableRowElement, PElement, etc.) provide the strongly-typed API for interacting with ODT elements.
