form

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package form fills templates with data and makes the forms that business systems print (invoices, slips, certificates) as BDF documents.

A template is an Excel workbook, a Word document or a PowerPoint presentation whose text holds tags (package form/tag): {{name}} for a value, {{#items}} … {{/items}} for what a list repeats. Filling it lays the file out with the tags replaced by the data: a workbook as the pages Excel prints, a document as its pages, a presentation as its slides. See Fill of converter/xlsx, converter/docx and converter/pptx for what the tags do in each.

A template is also a file whose fields have places: a PDF with the fields of a form (its AcroForm; converter/pdfform), and a template of pdfme (the JSON file that its designer saves; converter/pdfme). Their fields are the names that the data has values for.

data, err := form.LoadData(form.Source{FileName: "order.json", Data: order},
	form.Source{Name: "items", FileName: "lines.csv", Data: lines})
res, err := form.Fill(template, size, &form.Options{Data: data})
err = res.Doc.WriteSingle(out)

The data is an object of the values of JSON. Sums, taxes, what is carried over to the next page and the rounding of all of them are the data's: a template looks values up and formats them, and does not calculate with them (the formulas of a workbook aside).

Compile makes a compiled template (.bdft) of a template: a BDF document that holds the template with what it asks of data, and shows it filled with sample data. It is checked once, and is filled like the template.

Index

Constants

View Source
const (
	FormatXLSX  = "xlsx"
	FormatDOCX  = "docx"
	FormatPPTX  = "pptx"
	FormatPDF   = "pdf"
	FormatPDFME = "pdfme"
)

Formats of templates: the documents of Office with tags in their text, and the files whose fields are what is filled: a PDF with the fields of a form, and a template of pdfme.

View Source
const MaxDataSize = 256 << 20

MaxDataSize bounds the bytes of a file of data.

View Source
const MaxTemplateSize = 256 << 20

MaxTemplateSize bounds the bytes of the source stored in a compiled template. Both compiling and reading a compiled template enforce it.

View Source
const SchemaDialect = "https://json-schema.org/draft/2020-12/schema"

SchemaDialect is the dialect of JSON Schema that Schema writes.

View Source
const SchemaKeyword = "x-bdf"

SchemaKeyword is the keyword of the schemas of Schema that holds what a template says of a name: the kind of its tags ("value", "section" or "image"), their number format, how a section repeats ("mode", and "slots"), the symbology of a code ("code"), where the tags are ("at"), what a person is shown for the values of a choice ("labels"), and that a text may have several lines ("multiline").

View Source
const TemplateVersion = 1

TemplateVersion is the version of the description of compiled templates.

Variables

This section is empty.

Functions

func Describe

func Describe(r io.ReaderAt, size int64) (format string, sample map[string]any, err error)

Describe tells what a template is: its format (FormatXLSX …; that of the template a compiled template holds), and the sample of its data that it has for itself: of a compiled template the sample it was compiled with, of a template of pdfme what its designer left in its fields. sample is nil for a template without one.

func Fields

func Fields(r io.ReaderAt, size int64) ([]tag.Field, error)

Fields reads the tags of a template without filling it: the names that data for it has, or the first mistake in its tags.

func LoadData

func LoadData(sources ...Source) (map[string]any, error)

LoadData reads files of data into the data of a template: the values of JSON, with numbers as float64 and dates (of YAML, and of workbooks) as time.Time.

func Schema

func Schema(fields []tag.Field, sample map[string]any) ([]byte, error)

Schema describes the data that a template asks for as a JSON Schema: an object with a property for each name that the tags of the template look up, in the order of the template. A program that makes a form for the data of a template (an editor, a page that asks a person for the values) makes it of the schema.

A template does not say all of it, and the schema is what its tags suggest:

  • A section with names in it, with {{.}}, or with a way to repeat (rows, slots, pages) is a list: of objects with those names, or of values. A section of slots holds as many items as it has slots, at most.
  • Another section is a condition: true or false.
  • A value with a number format is a number, with a date format a date (a text as tag.ParseDate reads it), and otherwise a text or a number.
  • A picture is a text: the path of a file, or a data: URL. A QR code or a barcode is the text that the symbol says.
  • A name with dots (customer.name) is a property of an object.

A name in a section is looked up in the item of the section first and in what is around it next, so that the tags alone do not tell which of the two has it: it is a property of the item, unless the template looks the same name up around the section too. A sample of the data (that of a compiled template, or nil) settles it: the names are where the sample has them, a section is a list, an object or a condition as its value in the sample is, and a value has the type of its value there.

Nothing is required: a tag whose name the data lacks is left empty. Construction is limited to 65,536 fields and nodes, nested at most 256 levels.

func SchemaOf

func SchemaOf(r io.ReaderAt, size int64, sample map[string]any) ([]byte, error)

SchemaOf returns the JSON Schema of the data of a template. A compiled template gives the schema it holds (that of its sample); with a sample, or for a template that is not compiled, the schema is made of the tags (Schema).

Types

type Compiled

type Compiled struct {
	// Doc is the document to write as the .bdft: its pages are the
	// template filled with the sample data.
	Doc      *bdf.Document
	Template *Template
	Warnings []string
}

Compiled is a compiled template.

func Compile

func Compile(r io.ReaderAt, size int64, name string, opts *Options) (*Compiled, error)

Compile checks a template and makes its compiled form. The data of the options is the sample that the pages of the compiled template show the template filled with; without data they show the template with its tags (a template of pdfme with what its designer left in its fields, which is then the sample). name is the file name of the template, when it has one. The source may be at most MaxTemplateSize bytes.

type Options

type Options struct {
	// Data is the data: an object of the values of JSON (see LoadData).
	Data map[string]any
	// Strict makes a tag whose name the data does not have an error;
	// without it the tag is replaced by nothing, with a warning.
	Strict bool
	// Files holds the pictures that the data names by their paths.
	Files fs.FS
	// Convert are the options of the conversion: the fonts, the images,
	// the sheets or slides to fill (Pages; for a Word document the pages
	// to keep) and the parameters of the format ("views", "paper" …). nil
	// converts with the defaults.
	Convert *converter.Options
}

Options controls filling a template.

type Result

type Result struct {
	Doc      *bdf.Document
	Warnings []string
	// Fields are the names that the tags of the template look up.
	Fields []tag.Field
	// Format is the format of the template (FormatXLSX …).
	Format string
}

Result is a filled template.

func Fill

func Fill(r io.ReaderAt, size int64, opts *Options) (*Result, error)

Fill fills a template, or a compiled template, with data.

type Source

type Source struct {
	// Name is where the data of the file goes: "" makes it the data
	// itself (a JSON or YAML object, whose values the values of the
	// sources before it with the same names give way to), and a name
	// ("items", "customer.address") makes it the value of that name.
	//
	// A CSV or TSV file is a list of objects: the first record names the
	// values of the others. Without a name it is the list named after the
	// file ("lines" for lines.csv). A workbook (.xlsx) is such a list for
	// each of its sheets, by the names of the sheets; with a name, a
	// workbook of one sheet is that list.
	Name string
	// FileName tells the format of the data by its extension: .json,
	// .yaml or .yml, .csv or .tsv, .xlsx.
	FileName string
	Data     []byte
}

Source is a file of data for a template.

type Template

type Template struct {
	// Version is TemplateVersion.
	Version int `json:"version"`
	// Format is the format of the template the document holds (FormatXLSX
	// …), Name its file name when it had one, and Source the hash of the part
	// (of the type bdf.PartSource) that is the template.
	Format string `json:"format"`
	Name   string `json:"name,omitempty"`
	Source string `json:"source"`
	// Fields are the names that the tags of the template look up.
	Fields []tag.Field `json:"fields"`
	// Sample is the data the pages of the document show the template
	// filled with (none: they show the tags).
	Sample map[string]any `json:"sample,omitempty"`
	// Schema is the JSON Schema of the data (Schema, made of the fields
	// and the sample): what a program makes a form for the data of,
	// without reading the template.
	Schema json.RawMessage `json:"schema,omitempty"`
}

Template describes a compiled template: the part of the type bdf.PartTemplate of a .bdft, as JSON.

func ReadTemplate

func ReadTemplate(r io.ReaderAt, size int64) (*Template, []byte, error)

ReadTemplate reads a compiled template: its description, and the template it holds.

Directories

Path Synopsis
Package tag reads the tags of form templates: the marks in the text of a Word, Excel or PowerPoint file that data replaces when the template is filled (package form).
Package tag reads the tags of form templates: the marks in the text of a Word, Excel or PowerPoint file that data replaces when the template is filled (package form).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL