https://github.com/xamgore/docx-template
Replace {placeholders} and manage content inside .docx files
https://github.com/xamgore/docx-template
docx microsoft-word template
Last synced: 3 days ago
JSON representation
Replace {placeholders} and manage content inside .docx files
- Host: GitHub
- URL: https://github.com/xamgore/docx-template
- Owner: xamgore
- License: mit
- Created: 2024-06-22T11:39:24.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-11-04T13:09:37.000Z (8 months ago)
- Last Synced: 2024-11-04T14:17:59.936Z (8 months ago)
- Topics: docx, microsoft-word, template
- Language: Rust
- Homepage: https://docs.rs/crate/docx-template
- Size: 2.97 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# docx-template [](https://crates.io/crates/docx-template) [](https://docs.rs/docx-template/)
Replace {placeholders} and manage content inside .docx files.
---
---
- **Primitive**: not a template engine, but can do quite a few transformations
[Replace text](#), [swap images](#), [~~delete comments~~](#), [~~flip
checkboxes~~](https://github.com/xamgore/docx-template/issues/6), [insert custom markup](https://github.com/xamgore/docx-template/issues/3)
- **Fast**: single-pass, avoids recompression, uses Aho-Corasick internally, almost O(n)
No [long time read issues](https://github.com/bokuweb/docx-rs/issues/757) like docx‑rs has
- **Not memory-efficient (yet)**: operates on a byte stream without DOM tree allocation
Keeps the whole text in‑memory
### Example
```rust
use docx_template::DocxFile;
use serde::Serialize;
use std::error::Error;
fn main() -> Result<(), Box> {
let data = Data { crustacean: "🦀".into() };
let output = DocxFile::from_path("in.docx")?.into_template(data)?.render()?;
std::fs::write("output.docx", output)?;
Ok(())
}
#[derive(Serialize)]
struct Data {
crustacean: String
}
```
### Why
A naive approach to the problem is just calling `xml.replace("{placeholder}", "🦀")`.
Which isn't 100% accurate, as placeholders can reside in multiple adjacent XML nodes like in the example below.
That's why this crate was made. It reads XML nodes, detects patterns, and applies transformations keeping the structural integrity.
```xml
{placeholder}
🦀
```
### Features
- `serde` (default) — use `json!` macro & `Serialize` structs to create templates
- `docx-rs` — insert markup defined by @bokuweb/[docx‑rs](https://lib.rs/crates/docx-rs)
- `docx-rust` — insert markup defined by @cstkingkey/[docx‑rust](https://lib.rs/crates/docx-rust)
### Ecosystem
| name | description |
|:-----------------------------------------------------------------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| @bokuweb/[docx‑rs](https://lib.rs/crates/docx-rs)
`0.4.18`
Apr 26, 2024 |
- DOM tree contains _owned_ values
- User-friendly naming and structure
- Reference ids must be set manually, despite automatic increments
- 🔥 Lots of examples
docx-template = { feature = ["docx-rs"] } |
| @cstkingkey/[docx‑rust](https://lib.rs/crates/docx-rust)
`0.1.8`
May 21, 2024 |
- DOM tree has a _\'lifetime_ parameter
- Close-to-spec naming and structure
- Reference ids must be set manually
docx-template = { feature = ["docx-rust"] } |
| @yūdachi/[docx](https://lib.rs/crates/docx)
`1.1.2`
Apr 27, 2020 | 💀 (forked by docx-rust) |
| | |
| @kaisery/[ooxmlsdk](https://lib.rs/crates/ooxmlsdk)
`0.1.16`
Oct 12, 2024 |
- Inspired by .NET [Open XML SDK](https://github.com/dotnet/Open-XML-SDK)
- Low-level, generated from specification
- Early development stage
| | |
| [office-crypto](https://lib.rs/crates/office-crypto) | Allows decrypting password protected MS Office files |
| [ms-offcrypto-writer](https://lib.rs/crates/ms-offcrypto-writer) | Encrypting ECMA376/OOXML files with agile encryption |
> [!NOTE]
> Office Open XML (also informally known as OOXML or Microsoft Open XML (MOX)) is a zipped, XML-based file format
> developed by Microsoft for representing spreadsheets, charts, presentations and word processing documents. The format
> was initially standardized by Ecma (as ECMA-376), and by the ISO and IEC (as ISO/IEC 29500) in later versions.