go-template-docx

Appearance

APIs ​

We already saw in the Quick Start section how to create and use a docxTemplate object to load a docx template file, apply data to it and save the generated output file with the first functions:

go
// NewDocxTemplateFromFilename creates a new docxTemplate object from the provided DOCX filename (reading from disk).
// The docxTemplate object can be used through the exposed high-level APIs.
func NewDocxTemplateFromFilename(docxFilename string) (*docxTemplate, error)

and

go
// NewDocxTemplateFromBytes creates a new docxTemplate object from the provided DOCX file bytes.
// The docxTemplate object can be used through the exposed high-level APIs.
func NewDocxTemplateFromBytes(docxBytes []byte) (*docxTemplate, error)

High-level APIs ​

You can use all the features with simplified methods from the docxTemplate object:

Loading media files:

go
// Media adds a media file to the docxTemplate object.
// Supported media types are currently limited to JPEG and PNG images.
// The filename match the string you pass in the template expression using the image function.
// For example {{ image "computer.png" }} will load the docx.Media that have "computer.png" as its filename.
// The data should be the byte content of the media file.
func (dt *docxTemplate) Media(filename string, data []byte)

Apply data to the template:

go
// Apply applies the template with the provided values to the DOCX file.
// The templateValues parameter can be any type that can be marshalled to JSON.
func (dt *docxTemplate) Apply(templateValues any) error

Save the output file:

go
// Save saves the modified docx file to the specified filename.
func (dt *docxTemplate) Save(filename string) error

Get the byte array []byte output of the file (after applying the template):

go
// Bytes returns the output bytes of the output xlsx file bytes
// (empty if Apply was not used).
func (dt *docxTemplate) Bytes() []byte

Low-level APIs ​

If you are in need to process the templated docx file, check variables or even create your own custom template functions, you can use the following methods:

Add custom template functions:

go
// AddTemplateFuncs adds your custom template functions 
// to evaluate when applying the template.
// Existing functions will be shadowed if the same name is used.
func (dt *docxTemplate) AddTemplateFuncs(funcMap template.FuncMap)

Add pre-processors for internal XML files handling (before applying the templateValues):

go
// AddPreProcessors adds XML pre-processing maps in which 
// the key is the XML file path (e.g. "word/document.xml")
// and the value is a list of functions that overwrite it
// sequentially, before the template is applied.
func (dt *docxTemplate) AddPreProcessors(filesPreProcessors ...xml.HandlersMap)

Add post-processors for internal XML files handling (after applying the templateValues):

go
// AddPostProcessors adds XML post-processing maps in which
// the key is the XML file path (e.g., "word/document.xml")
// and the value is a list of functions that overwrite it
// sequentially, after the template is applied.
func (dt *docxTemplate) AddPostProcessors(filesPostProcessors ...xml.HandlersMap)

Get template variables found in the input file:

go
// GetTemplateVariables extracts and returns all
// template variables used in the DOCX file as a map.
func (dt *docxTemplate) GetTemplateVariables() (map[string]struct{}, error)