docxtpl

README

Go Docx Template

[!IMPORTANT] This library is currently in active development and is therefore not recommended for production use

Introduction

A simple Go library for merging docx files with data.

This is a wrapper library around the go-docx library by fumiama. All of the methods on the docx.Docx struct from go-docx are inherited by the docxtpl.DocxTmpl struct with an additional Render method.

Usage

Installation

go get github.com/tomwatkins1994/go-docx-template@latest 

Render a document

package main

import (
  "os"

  "github.com/tomwatkins1994/go-docx-template"
)

func main() {
  // Parse the document 
  // If using a reader, use docxtpl.Parse instead
  doc, err := docxtpl.ParseFromFilename("template.docx")
  if err != nil {
    panic(err)
  }

  // Render the document
  data := struct {
    FirstName     string
    LastName      string
    Gender        string
  }{
    FirstName: "Tom",
    LastName:  "Watkins",
    Gender:    "Male",
  }
  err = doc.Render(data)
  if err != nil {
    panic(err)
  }

  // Create a new file for the output
  f, err := os.Create("generated.docx")
  if err != nil {
    panic(err)
  }
  err = doc.Save(f)
  if err != nil {
    panic(err)
  }
  err = f.Close()
  if err != nil {
    panic(err)
  }
}

Examples of docx files can be found in the tests directory of this repository.

Acknowledgements

A lof of the heavy lifting such as XML parsing is done by the go-docx library by fumiama.

This library was also heavily inspired by the excellent python-docx-template library for Python written by elapouya.

License

AGPL-3.0. See LICENSE

Documentation

Index

• Constants
• Variables
• type ContentTypes
• type Default
• type DocxTmpl
  • func Parse(reader io.ReaderAt, size int64) (*DocxTmpl, error)
  • func ParseFromFilename(filename string) (*DocxTmpl, error)
  • func (d *DocxTmpl) CreateInlineImage(filepath string) (*InlineImage, error)
  • func (d *DocxTmpl) RegisterFunction(name string, fn any) error
  • func (d *DocxTmpl) Render(data interface{}) error
  • func (d *DocxTmpl) Save(writer io.Writer) error
• type InlineImage
  • func (i *InlineImage) GetExifData() (map[string]imagemeta.TagInfo, error)
  • func (i *InlineImage) GetResolution() (wDpi int64, hDpi int64)
  • func (i *InlineImage) GetSize() (w int64, h int64, err error)
  • func (i *InlineImage) Resize(width int, height int) error
• type InlineImageError
  • func (e *InlineImageError) Error() string
• type Override

Constants

const (
	EMUS_PER_INCH = 914400
	DEFAULT_DPI   = 72
)

Variables

var JPEG_CONTENT_TYPE = Default{Extension: "jpeg", ContentType: "image/jpeg"}

var JPG_CONTENT_TYPE = Default{Extension: "jpg", ContentType: "image/jpg"}

var PNG_CONTENT_TYPE = Default{Extension: "png", ContentType: "image/png"}

Types

type ContentTypes

type ContentTypes struct {
	XMLName   xml.Name   `xml:"Types"`
	Xmlns     string     `xml:"xmlns,attr"`
	Defaults  []Default  `xml:"Default"`
	Overrides []Override `xml:"Override"`
}

type Default

type Default struct {
	Extension   string `xml:"Extension,attr"`
	ContentType string `xml:"ContentType,attr"`
}

type DocxTmpl

type DocxTmpl struct {
	*docx.Docx
	// contains filtered or unexported fields
}

func Parse

func Parse(reader io.ReaderAt, size int64) (*DocxTmpl, error)

Parse the document from a reader and store it in memory. You can it invoke from a file.

reader, err := os.Open(FILE_PATH)
if err != nil {
	panic(err)
}
fileinfo, err := reader.Stat()
if err != nil {
	panic(err)
}
size := fileinfo.Size()
doc, err := docxtpl.Parse(reader, int64(size))

func ParseFromFilename

func ParseFromFilename(filename string) (*DocxTmpl, error)

Parse the document from a filename and store it in memory.

func (*DocxTmpl) CreateInlineImage

func (d *DocxTmpl) CreateInlineImage(filepath string) (*InlineImage, error)

func (*DocxTmpl) RegisterFunction

func (d *DocxTmpl) RegisterFunction(name string, fn any) error

func (*DocxTmpl) Render

func (d *DocxTmpl) Render(data interface{}) error

Replace the placeholders in the document with passed in data.

func (*DocxTmpl) Save

func (d *DocxTmpl) Save(writer io.Writer) error

Save the document to a writer. This could be a new file.

f, err := os.Create(FILE_PATH)
if err != nil {
	panic(err)
}
err = doc.Save(f)
if err != nil {
	panic(err)
}
err = f.Close()
if err != nil {
	panic(err)
}

type InlineImage

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

func (*InlineImage) GetExifData

func (i *InlineImage) GetExifData() (map[string]imagemeta.TagInfo, error)

Return a map of EXIF data from the image.

func (*InlineImage) GetResolution

func (i *InlineImage) GetResolution() (wDpi int64, hDpi int64)

Get the resolution (DPI) of the image. It gets this from EXIF data and defaults to 72 if not found.

func (*InlineImage) GetSize

func (i *InlineImage) GetSize() (w int64, h int64, err error)

Get the size of the image in pixels.

func (*InlineImage) Resize

func (i *InlineImage) Resize(width int, height int) error

Resize the image. Width and height should be pixel values.

type InlineImageError

type InlineImageError struct {
	Message string
}

func (*InlineImageError) Error

func (e *InlineImageError) Error() string

type Override

type Override struct {
	PartName    string `xml:"PartName,attr"`
	ContentType string `xml:"ContentType,attr"`
}