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
- func Describe(r io.ReaderAt, size int64) (format string, sample map[string]any, err error)
- func Fields(r io.ReaderAt, size int64) ([]tag.Field, error)
- func LoadData(sources ...Source) (map[string]any, error)
- func Schema(fields []tag.Field, sample map[string]any) ([]byte, error)
- func SchemaOf(r io.ReaderAt, size int64, sample map[string]any) ([]byte, error)
- type Compiled
- type Options
- type Result
- type Source
- type Template
Constants ¶
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.
const MaxDataSize = 256 << 20
MaxDataSize bounds the bytes of a file of data.
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.
const SchemaDialect = "https://json-schema.org/draft/2020-12/schema"
SchemaDialect is the dialect of JSON Schema that Schema writes.
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").
const TemplateVersion = 1
TemplateVersion is the version of the description of compiled templates.
Variables ¶
This section is empty.
Functions ¶
func Describe ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
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.
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.
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). |