Allors Documents

Embed template tags inside OpenDocument texts: write the template in LibreOffice Writer, bind it to a model, render the document.

Status

Packages

Package	Holds
Allors.Documents	The template and its renderer, the tag language, the inspection, Validate, the model contracts (IShape, IResolver) and the dictionary shape and resolver. Targets netstandard2.0 and net10.0, is trimmable and AOT-compatible, uses no reflection and has no dependencies.
Allors.Documents.Reflection	OpenDocumentTemplate<T>, ReflectionShape and ReflectionResolver: templates over plain classes and dictionaries, their members read through reflection.
Allors.Documents.Barcodes	The picture renderers code128, ean13 and qr: a barcode of the value's text, drawn with ZXing.Net for the frame that shows it.
Allors.Documents.Imaging	PictureScaling, a picture processor that scales a picture down to its frame with SkiaSharp, turns a photo upright and keeps its format.

Allors.Documents is all a render needs. The other packages are optional: reflection for an application without a resolver of its own, barcodes and imaging for one that draws no barcodes and scales no pictures of its own. An application that has those capabilities wraps its own code as a renderer or picture processor, which Renderers and picture processing shows, and needs neither package.

Usage

using Allors.Documents;
using Allors.Documents.Reflection;

var template = new OpenDocumentTemplate<InvoiceModel>(templateBytes);
RenderResult result = template.Render(model);

File.WriteAllBytes("invoice.odt", result.Document);
foreach (Finding finding in result.Findings)
{
    Console.WriteLine(finding); // error: <$Invoice.Totl>: Invoice has no member Totl (content.xml paragraph 12 "Total <$Invoice.Totl>")
}

A template is read once and rendered any number of times, from any thread. A render never throws for what the template says: a value the model cannot give prints blank, and the findings say which tag and where. Validate reports the same before any data exists.

Documentation

The documentation is written for template authors, developers and maintainers. The pages live under docs/ in this repository; the links go to their sources on GitHub.

For template authors: Write a template · Tags · Formatting · Pictures · Maps · Findings

For developers: Render your first document · Validate templates · Resolve your own model · Renderers and picture processing · API · Design

For everyone: Terminology · Documentation index

For maintainers: Architecture · Releasing · Writing documentation · Documentation website

Changes are recorded in CHANGELOG.md. Agents follow AGENTS.md, which points to the same pages.