docxexp

README

docx-exp

A wrapper around github.com/fumiama/go-docx to provide advanced template rendering features for DOCX files, inspired by docxtpl and docx-templates.

ATTENTION: This project is in development and may not be stable. Use at your own risk.

Features

• Variable Replacement: {{ .Var }} or {{ Var }}.
• Loops:
  • Block Loops: {{for item in Items}} ... {{endfor}} (supports paragraphs, tables, nested structures).
  • Table Row Loops: {{ range .Items }} inside a table row.
• Conditionals: {{if Condition}} ... {{endif}}.
• Injection:
  • Images: Inject images dynamically.
  • HTML: Inject HTML content (h1, h2, h3, p, img).
• Robustness: Automatically patches [Content_Types].xml to support image formats.

Installation

go get github.com/little-yangyang/docx-exp

Usage

Basic Rendering

package main

import (
    "os"
    docxexp "github.com/little-yangyang/docx-exp"
)

func main() {
    f, _ := os.Open("template.docx")
    defer f.Close()
    fi, _ := f.Stat()

    tpl, _ := docxexp.New(f, fi.Size())

    data := map[string]interface{}{
        "Name": "World",
    }
    tpl.Render(data)

    out, _ := os.Create("result.docx")
    defer out.Close()
    tpl.Save(out)
}

Block Loops

Use {{for var in Slice}} to repeat a block of content.

{{for item in Items}}
Item: {{item.Name}}
{{endfor}}

Conditionals

Use {{if Condition}} to conditionally show a block.

{{if IsVisible}}
This is visible.
{{endif}}

Injection

Use {{ inject .Injector }} in your template.

Injecting Images

data := struct {
    MyImage docxexp.Injector
}{
    MyImage: docxexp.ImageInjector{
        Path: "image.png",
        Width: 100,
        Height: 100,
    },
}

Project Structure

• examples/: Example usage scripts.
  • block_loop/: Block loops ({{for}}, {{if}}).
  • html_injection/: HTML content injection.
  • complex_report/: Complex report with tables and images.
  • simple_write/: Basic variable replacement.
• tools/: Utility scripts.
• testdata/: Test assets.
• client.go, html.go, image.go: Core library code.

Usage

See examples/ for runnable examples.

Documentation

Index

• type DocxTemplate
  • func New(r io.ReaderAt, size int64) (*DocxTemplate, error)
  • func (t *DocxTemplate) Funcs(f template.FuncMap)
  • func (t *DocxTemplate) Render(data interface{}) error
  • func (t *DocxTemplate) Save(w io.Writer) error
• type HTMLInjector
  • func (h HTMLInjector) Inject(doc *docx.Docx, p *docx.Paragraph) ([]interface{}, error)
• type ImageInjector
  • func (i ImageInjector) Inject(doc *docx.Docx, p *docx.Paragraph) ([]interface{}, error)
• type Injector

Types

type DocxTemplate

type DocxTemplate struct {
	// contains filtered or unexported fields
}

DocxTemplate represents a docx template

func New

func New(r io.ReaderAt, size int64) (*DocxTemplate, error)

New creates a new DocxTemplate

func (*DocxTemplate) Funcs

func (t *DocxTemplate) Funcs(f template.FuncMap)

Funcs registers custom functions

func (*DocxTemplate) Render

func (t *DocxTemplate) Render(data interface{}) error

func (*DocxTemplate) Save

func (t *DocxTemplate) Save(w io.Writer) error

Save writes the document to w

type HTMLInjector

type HTMLInjector struct {
	Content string
}

HTMLInjector injects HTML content into the document

func (HTMLInjector) Inject

func (h HTMLInjector) Inject(doc *docx.Docx, p *docx.Paragraph) ([]interface{}, error)

Inject implements the Injector interface

type ImageInjector

type ImageInjector struct {
	Path   string
	Width  int64
	Height int64
}

ImageInjector injects an image into the document

func (ImageInjector) Inject

func (i ImageInjector) Inject(doc *docx.Docx, p *docx.Paragraph) ([]interface{}, error)

Inject implements the Injector interface

type Injector

type Injector interface {
	Inject(doc *docx.Docx, p *docx.Paragraph) ([]interface{}, error)
}

Injector is the interface that must be implemented by types that want to inject content