docxplate

README

docxplate

Generate document from .docx template file.
(!) Unstable with complex/many levels Structs.

Examples

Click on image to see larger.

// Using this data for all examples below
type User struct {
	Name       string
	Age        int
	Nicknames  []string
	Friends    []*User
	ImageLocal *docxplate.Image
	ImageURL   *docxplate.Image
}

user := User{
	Name:      "Alice",
	Age:       27,
	Nicknames: []string{"amber", "AL", "ice"},
	Friends: []*User{
		&User{Name: "Bob", Age: 28},
		&User{Name: "Cecilia", Age: 29},
		&User{Name: "Den", Age: 30},
	},
	ImageLocal: &docxplate.Image{
		Path:   "images/github.png",
		Width:  50,
		Height: 50,
	},
	ImageURL: &docxplate.Image{
		URL:    "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png",
		Width:  50,
		Height: 50,
	},
}

// Template to document
tdoc, _ := docxplate.OpenTemplate("template.docx")
tdoc.Params(user)
tdoc.ExportDocx("MyDoc.docx")

Struct as data input

Hello, {{Name}}! --> Hello, Alice!
You are {{Age}} years old. --> You are 27 years old.

Slice/Map placeholder to multiple rows

Here is my nicknames:
- {{Nicknames}}    
---------------------------------------------------
Here is my nicknames:
- amber
- AL
- ice

List slice structs expands to multiple rows:

My Friends:
    * {{Friends.Name}} is {{Friends.Age}} years old
---------------------------------------------------
My Friends:
    * Bob is 28 years old
    * Cecilia is 29 years old
    * Den is 30 years old

Slice/Map placeholder to implode multiple values

Use {{Nicknames ***}} to concatenate values with given separator: amber***AL***ice.
Or no separator at all {{Nicknames }} (still one space required to mark placeholder as inline values): amberALice.

Here is my nicknames: {{Nicknames , }} :)
---------------------------------------------------
Here is my nicknames: amber, AL, ice :)

Bugs

Don't use too complicated struct.
Above exmaple with User->Friends->User is limit in depth.
{{User->Friends->User->Friends}} is not supported at this moment.

Examples

Documentation

Index

• Constants
• Variables
• type Image
• type Param
  • func NewParam(key interface{}) *Param
  • func NewParamFromRaw(raw []byte) *Param
  • func (p *Param) Depth() int
  • func (p *Param) Placeholder() string
  • func (p *Param) PlaceholderInline() string
  • func (p *Param) PlaceholderKey() string
  • func (p *Param) PlaceholderKeyInline() string
  • func (p *Param) PlaceholderKeyPrefix() string
  • func (p *Param) PlaceholderPrefix() string
  • func (p *Param) RunTrigger(xnode *xmlNode)
  • func (p *Param) SetValue(val interface{})
  • func (p *Param) String() string
  • func (p *Param) ToCompact(placeholder string) string
  • func (p *Param) Walk(fn func(*Param), level int)
  • func (p *Param) WalkFunc(fn func(*Param))
• type ParamList
  • func JSONToParams(buf []byte) ParamList
  • func StructParams(v interface{}) ParamList
  • func StructToParams(paramStruct interface{}) ParamList
  • func (params ParamList) Walk(fn func(*Param))
• type ParamTrigger
  • func NewParamTrigger(raw []byte) *ParamTrigger
  • func (tr *ParamTrigger) String() string
• type ParamType
• type Template
  • func OpenTemplate(docpath string) (*Template, error)
  • func OpenTemplateWithURL(docurl string) (tpl *Template, err error)
  • func (t *Template) Bytes() ([]byte, error)
  • func (t *Template) ExportDocx(path string) error
  • func (t *Template) Params(v interface{})
  • func (t *Template) Placeholders() []string
  • func (t *Template) Plaintext() string

Constants

const (
	TriggerOnUnknown string = ":unknown"
	TriggerOnEmpty   string = ":empty"
	TriggerOnValue   string = ":="
)

On - trigger events when command to aply

const (
	TriggerCommandRemove = ":remove"
	TriggerCommandClear  = ":clear"
)

Command - what to do when triggered

const (
	TriggerScopePlaceholder = ":placeholder"
	TriggerScopeCell        = ":cell"
	TriggerScopeRow         = ":row"
	TriggerScopeList        = ":list"
	TriggerScopeTable       = ":table"
	TriggerScopeSection     = ":section" // table, list..
)

Scope - scope of affected elements by command

const ParamPattern = `{{(#|)([\w\.]+?)(| .*?)(| [:a-z]+?)}}`

ParamPattern - regex pattern to identify params

Variables

var NodeCellTypes = []string{"w-tc"}

NodeCellTypes - NB! sequence is important

var NodeRowTypes = []string{"w-tr", "w-p"}

NodeRowTypes - NB! sequence is important

var NodeSectionTypes = []string{"w-tbl", "w-p"}

NodeSectionTypes - NB! sequence is important

var NodeSingleTypes = []string{"w-r", "w-t"}

NodeSingleTypes - NB! sequence is important

Types

type Image

type Image struct {
	Path   string
	URL    string
	Width  int // dimension:pt
	Height int // dimension:pt
}

Image - Choose either path or url to set, if both are set, prioritize path.

type Param

type Param struct {
	Key   string
	Value string
	Type  ParamType
	Level int

	Params ParamList

	AbsoluteKey string // Users.1.Name
	CompactKey  string // Users.Name

	Separator string // {{Usernames SEPERATOR}}

	Trigger *ParamTrigger

	RowPlaceholder string
	// contains filtered or unexported fields
}

Param ..

func NewParam

func NewParam(key interface{}) *Param

NewParam ..

func NewParamFromRaw

func NewParamFromRaw(raw []byte) *Param

NewParamFromRaw ..

func (*Param) Depth

func (p *Param) Depth() int

Depth - how many levels param have of child nodes {{Users.1.Name}} --> 3

func (*Param) Placeholder

func (p *Param) Placeholder() string

Placeholder .. {{Key}}

func (*Param) PlaceholderInline

func (p *Param) PlaceholderInline() string

PlaceholderInline .. {{Key ,}}

func (*Param) PlaceholderKey

func (p *Param) PlaceholderKey() string

PlaceholderKey .. {{#Key}}

func (*Param) PlaceholderKeyInline

func (p *Param) PlaceholderKeyInline() string

PlaceholderKeyInline .. {{#Key ,}}

func (*Param) PlaceholderKeyPrefix

func (p *Param) PlaceholderKeyPrefix() string

PlaceholderKeyPrefix .. {{#Key

func (*Param) PlaceholderPrefix

func (p *Param) PlaceholderPrefix() string

PlaceholderPrefix .. {{Key

func (*Param) RunTrigger

func (p *Param) RunTrigger(xnode *xmlNode)

RunTrigger - execute trigger

func (*Param) SetValue

func (p *Param) SetValue(val interface{})

SetValue - any value to string

func (*Param) String

func (p *Param) String() string

String - compact debug information as string

func (*Param) ToCompact

func (p *Param) ToCompact(placeholder string) string

ToCompact - convert AbsoluteKey placeholder to ComplexKey placeholder {{Users.0.Name}} --> {{Users.Name}}

func (*Param) Walk

func (p *Param) Walk(fn func(*Param), level int)

Walk down

func (*Param) WalkFunc

func (p *Param) WalkFunc(fn func(*Param))

Walk function

type ParamList

type ParamList []*Param

ParamList ..

func JSONToParams

func JSONToParams(buf []byte) ParamList

JSONToParams - load params from JSON

func StructParams

func StructParams(v interface{}) ParamList

StructParams - load params from given any struct 1) Convert struct to JSON 2) Now convert JSON to map[string]interface{} 3) Clear params from nil

func StructToParams

func StructToParams(paramStruct interface{}) ParamList

Walk struct and collect valid params

func (ParamList) Walk

func (params ParamList) Walk(fn func(*Param))

Walk through params

type ParamTrigger

type ParamTrigger struct {
	On      string
	Command string
	Scope   string
	// contains filtered or unexported fields
}

ParamTrigger - param trigger command {{Key :On:Command:Scope}} {{MyParam :empty:remove:list}} -- Read as: "`remove` `list` on `empty` value"

func NewParamTrigger

func NewParamTrigger(raw []byte) *ParamTrigger

NewParamTrigger - take raw ":empty:remove:list" and make trigger and it's fields from it

func (*ParamTrigger) String

func (tr *ParamTrigger) String() string

String - return rebuilt trigger string

type ParamType

type ParamType int8

Param type

const (
	StringParam ParamType = iota
	StructParam
	SliceParam
	ImageParam
	VideoParam
)

type Template

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

Template ..

func OpenTemplate

func OpenTemplate(docpath string) (*Template, error)

OpenTemplate .. docpath local file

func OpenTemplateWithURL

func OpenTemplateWithURL(docurl string) (tpl *Template, err error)

OpenTemplateWithURL .. docpath is remote url

func (*Template) Bytes

func (t *Template) Bytes() ([]byte, error)

Bytes - create docx archive but return only bytes of it do not save it anywhere

func (*Template) ExportDocx

func (t *Template) ExportDocx(path string) error

ExportDocx - save new/modified docx based on template

func (*Template) Params

func (t *Template) Params(v interface{})

Params - replace template placeholders with params "Hello {{ Name }}!"" --> "Hello World!""

func (*Template) Placeholders

func (t *Template) Placeholders() []string

Placeholders - get list of used params placeholders in template If you already replaced params with values then you will not get all placeholders. Or use it after replace and see how many placeholders left.

func (*Template) Plaintext

func (t *Template) Plaintext() string

Plaintext - return as plaintext