poi-tl (poi-template-language)

What is the project about?

poi-tl is a Word template engine that generates new Word documents (.docx) based on a Word template and data. It's similar in concept to how template engines like FreeMarker or Velocity work for HTML, but specifically designed for Word documents.

What problem does it solve?

It simplifies the process of generating Word documents programmatically. Instead of manually manipulating the document structure via code (which can be complex with Apache POI), you define a template with placeholders (tags) and then provide data to fill those placeholders. This makes document generation more maintainable, readable, and less prone to errors. It also preserves the rich formatting and styling of the original Word template.

What are the features of the project?

Text Replacement: Replace tags with text, preserving the original style of the tag.
Picture Insertion: Insert images from URLs, local paths, or in-memory objects.
Table Generation: Create tables dynamically based on data.
Numbering/List Generation: Create bulleted or numbered lists.
Conditional Sections: Show or hide sections of the document based on conditions (like an "if" statement).
Looping Sections: Repeat sections of the document for each item in a collection (like a "foreach" loop). This works for text, paragraphs, pictures, tables, lists, and charts.
Nested Templates: Include one Word template within another.
Chart Rendering: Supports various chart types (bar, column, area, line, radar, pie).
Code Highlighting: Highlight code blocks with support for many languages and styles.
Markdown Conversion: Convert Markdown text to Word document formatting.
Word Attachments: Insert attachments into the Word document.
Word Comments: Create, modify, and manage comments.
Word SDT (Structured Document Tags): Full support for structured document tags.
Textbox Support: Tags can be used within text boxes.
Picture Replacement: Replace existing pictures in the template.
Bookmarks, Anchors, Hyperlinks: Set bookmarks, anchors, and hyperlinks.
Expression Language Support: Uses SpringEL expressions, with extensibility for others (OGNL, MVEL).
Styling: Templates define styles, and styles can also be set programmatically.
Word Merging: Merge multiple Word documents, including merging at specific locations.
Custom Functions (Plug-ins): Extend functionality with custom plugins that can be executed anywhere in the document.

What are the technologies used in the project?

Java: The core language.
Apache POI: The underlying library for interacting with Word documents (specifically .docx format). Requires POI 3.16+ and recommends 5.1.0.
Maven: For dependency management.
Spring Expression Language (SpEL): For evaluating expressions within templates.
(Optional) Other expression languages: Extensible to support OGNL, MVEL, etc.

What are the benefits of the project?

Simplified Document Generation: Makes creating Word documents programmatically much easier.
Maintainability: Separates document structure (template) from data, making it easier to update either one.
Readability: Templates are more readable than code that directly manipulates the Word document object model.
Style Preservation: Retains the formatting and styles defined in the Word template.
Extensibility: Custom functions (plugins) allow for highly customized document generation.
Logic-less Templates: Focuses on data replacement and avoids complex logic within the templates themselves.

What are the use cases of the project?

Report Generation: Creating reports with dynamic data, tables, and charts.
Resume Generation: Generating personalized resumes from a template.
Contract Generation: Creating contracts with variable clauses and data.
Certificate Generation: Producing certificates with personalized information.
Document Automation: Automating any task that requires generating Word documents based on data.
API Documentation: Generating Word documentation from Swagger/OpenAPI specifications.
Mail Merge: Creating personalized letters or documents for a list of recipients.
Content Management Systems: Generating Word documents from content stored in a CMS.