README
¶
gobl.html
Generate HTML files from GOBL documents.
Released under the Apache 2.0 LICENSE, Copyright 2024 Invopop Ltd..
Development
Generate Templates
GOBL HTML uses templ to define a set of components in Go. To generate the templates, run:
templ generate
Hot reload is very convenient to make changes and preview them quickly. There are two mechanisms we're currently using:
Air
Air is a great tool to auto reload potentially any project, but works great with Go. Install with:
go install github.com/air-verse/air@latest
The .toml is already configured and ready in this repository, so simply run:
air
Air is a bit more reliable at detecting file changes, especially for stylesheets. You'll always need to wait a few seconds before page reloads to give the system chance to recompile. A proxy is available with Air, but we didn't find it to be very reliable and was breaking with query parameters, it obviously also wouldn't work for PDF reloads.
Templ Watcher
Templ comes with a watch flag that can also be useful. However, it has the disadvantage of using .txt files for comparisons and the generated code should not be uploaded to git directly. Start the process with:
templ generate --watch --cmd="go run ./cmd/gobl.html serve --pdf prince"
Before uploading changes to git, be sure to re-run the regular templ generate command, as the live version makes temporary modifications to files that need to be replaced.
Testing
Tests are currently pretty limited. To ensure the basics are covered, the contents of the examples directory are converted to HTML, pretty printed, and output to the examples/out directory. The tests will ensure the output matches what's expected. To update the output test data run:
go test ./... --update
When adding new examples make sure to run:
go test examples_test.go --update
This will ensure the test file for that example is updated.
Documentation
¶
Overview ¶
Package goblhtml provides a simple way to render HTML documents from GOBL envelopes.
Index ¶
- Variables
- func Render(ctx context.Context, env *gobl.Envelope, opts ...Option) ([]byte, error)
- type Option
- func WithCalFormatter(date, timeFormat string, loc *time.Location) Option
- func WithCurrencyTemplate(val string) Option
- func WithDecimalMark(val string) Option
- func WithEmbeddedAssets() Option
- func WithLabel(label string) Option
- func WithLayout(l layout.Code) Option
- func WithLocale(locale i18n.Code) Option
- func WithLogo(logo *org.Image) Option
- func WithNegativeTemplate(val string) Option
- func WithNotes(txt string) Option
- func WithNumFormatter(nf num.Formatter) Option
- func WithSandbox(sandbox bool) Option
- func WithThousandsSeparator(val string) Option
- func WithVoid(void bool) Option
- func WithWatermark(watermark string) Option
Constants ¶
This section is empty.
Variables ¶
var EnableAdjustmentMode = func(o *internal.Opts) { o.AdjustmentMode = true }
EnableAdjustmentMode indicates that invoice types credit-note and debit-note or similar should be rendered as adjustments to the original invoice, as required in certain jurisdictions. By default, this mode is disabled.
Functions ¶
Types ¶
type Option ¶
Option defines a configuration option to use for rendering.
func WithCalFormatter ¶
WithCalFormatter prepares simple date and time formatting. The date and time formats are configured independently; date-time values render as "<date><sep><time>" using the provided formats. Pass an empty string to keep the ISO default for a given field.
func WithCurrencyTemplate ¶ added in v0.59.0
WithCurrencyTemplate sets a custom template for determining the position of currency units in the formatted amounts. This will modify the currency's default formatter.
func WithDecimalMark ¶ added in v0.59.0
WithDecimalMark sets a custom decimal mark for formatting currency amounts. This will modify the currency's default formatter.
func WithEmbeddedAssets ¶ added in v0.38.0
func WithEmbeddedAssets() Option
WithEmbeddedAssets indicates that the stylesheets and scripts should be embedded inside the HTML document as opposed to links.
func WithLabel ¶ added in v0.52.0
WithLabel indicates that the document should be rendered with the provided label
func WithLayout ¶ added in v0.26.0
WithLayout indicates that the document should be rendered acording to the given Layout.
func WithLocale ¶
WithLocale sets the locale to use for rendering.
func WithLogo ¶
WithLogo overrides whatever logo was defined in the original envelope, if at all, using the provided logo according to the document type.
func WithNegativeTemplate ¶ added in v0.59.0
WithNegativeTemplate sets a custom negative template for formatting currency amounts. This will modify the currency's default formatter.
func WithNumFormatter ¶
WithNumFormatter defines a customer number formatter to use instead of that provided by default for the currency.
func WithSandbox ¶ added in v0.52.0
WithSandbox indicates that the document should be rendered in sandbox mode
func WithThousandsSeparator ¶ added in v0.59.0
WithThousandsSeparator sets a custom thousands separator for formatting currency amounts. This will modify the currency's default formatter.
func WithVoid ¶ added in v0.35.0
WithVoid indicates that the document is marked as void and should be rendered accordingly.
func WithWatermark ¶ added in v0.52.0
WithWatermark indicates that the document should be rendered with the provided watermark
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets contains the static resources for things like styles.
|
Package assets contains the static resources for things like styles. |
|
cmd
|
|
|
gobl.html
command
Package main provides the entry point for the gobl.html command-line tool.
|
Package main provides the entry point for the gobl.html command-line tool. |
|
Package components defines all the templ components that will be used to render GOBL envelopes.
|
Package components defines all the templ components that will be used to render GOBL envelopes. |
|
bill
Package bill provides templates for rendering objects from GOBL's `bill` package.
|
Package bill provides templates for rendering objects from GOBL's `bill` package. |
|
images
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
note
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
org
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
regimes/ar
Package ar provides additional templates and helper methods for the Argentine tax regime.
|
Package ar provides additional templates and helper methods for the Argentine tax regime. |
|
regimes/co
Package co provides additional output for Colombian invoices.
|
Package co provides additional output for Colombian invoices. |
|
regimes/es
Package es provides additional templates and helper methods for the Spanish tax regime.
|
Package es provides additional templates and helper methods for the Spanish tax regime. |
|
regimes/gr
Package gr provides additional templates and helper methods for the Greek tax regime.
|
Package gr provides additional templates and helper methods for the Greek tax regime. |
|
regimes/mx
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
regimes/pl
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
regimes/pt
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
regimes/sa
Package sa defines extra output for Saudi Arabian invoices.
|
Package sa defines extra output for Saudi Arabian invoices. |
|
t
templ: version: v0.3.977
|
templ: version: v0.3.977 |
|
utils
Package utils provides utility functions for the components package.
|
Package utils provides utility functions for the components package. |
|
Package internal is used for internal option configuration.
|
Package internal is used for internal option configuration. |
|
gallery
Package gallery builds examples/index.html: scan examples/*.json, locale hints, embed catalog.html.
|
Package gallery builds examples/index.html: scan examples/*.json, locale hints, embed catalog.html. |
|
Package layout provides all the possible layouts for a document.
|
Package layout provides all the possible layouts for a document. |
|
Package locales provides all the content for translations.
|
Package locales provides all the content for translations. |
|
pkg
|
|
|
pdf
Package pdf provides a wrapper around different PDF generation tools to provide single conversion process regardless of implementation.
|
Package pdf provides a wrapper around different PDF generation tools to provide single conversion process regardless of implementation. |