httpdf

README

httpdf

PDF documents from HTML templates – as a web service (TBD: or command line utility).

httpdf produces a PDF file from the following inputs:

1. an HTML template, written in go's html/template syntax
2. a JSON Schema describing the inputs required to render the template
3. the actual template values as an HTTP POST request (TBD: or as a plain JSON file)

It uses a headless Chromium or Firefox instance for PDF rendering, controlled via rod.

Templates and schemas are plain text files and therefore easily manageable. The web service can render any number of templates – chosen via a unique identifier in the URL path.

Usage

The web service can be run as a simple go binary or as a docker image.

API

POST /templates/{template}/render

Render the template using the JSON-encoded data provided in the request body. Successful response is of Content-Type: application/pdf.

GET /templates/{template}/preview

Render an HTML preview of the template using data from the template's example.json file. Useful for template development.

Creating Templates

Check the templates/example directory for an example template.

Mount your templates into the container under the /templates directory. Each template is a folder by itself. The structure of the folder is as follows (file names must match exactly):

templates
└── example                 # folder name = template name
    ├── template.html       # the HTML template itself
    ├── schema.json         # JSON Schema describing the data structure required by the template
    ├── config.yaml         # template config parameters
    └── example.json        # (optional) example values

The template is identified by its folder name. In the above example, the name of the template is example.

template.html itself must contain valid (= renderable by Chromium) HTML, using html/template as a templating language.

schema.json must be a valid JSON Schema according to Draft 2020-12. Its purpose is to validate the input data before populating the HTML template. Though not recommended, the schema can be empty (define an object with no properties). If your template is using placeholders that are not defined in the schema, you risk getting unclear errors during template rendering.

config.yaml contains configuration values related to the template. It has the following structure:

page:
    width: width of the resulting PDF in mm
    height: height of the resulting PDF in mm

example.json can be added for testing and documentation purposes, providing some example data to render the template during template development

Development

In order to start the development server, employing hot-reload, use docker compose:

docker compose up

The container image includes a Chromium instance for HTML rendering. If you want to run the server directly in your host OS without using docker, you need to tell the app the path to a Chromium binary (TBD).

go run ./cmd/server

Documentation

Index

• Variables
• func NewServer(httpdf HTTPDF) http.Handler
• type HTTPDF
  • func New(templates template.Loader, validator template.Validator, ...) HTTPDF

Variables

var (
	// ErrInvalidValues is returned when the values are invalid
	ErrInvalidValues = errors.New("invalid values")
)

Functions

func NewServer

func NewServer(httpdf HTTPDF) http.Handler

Types

type HTTPDF

type HTTPDF interface {
	// Generate renders a PDF from the given template and values.
	Generate(template string, values map[string]any, out io.Writer) error
	// Preview renders an HTML preview of the given template with its example values.
	Preview(template string, out io.Writer) error
}

HTTPDF is the interface for the HTTPDF service.

func New

func New(
	templates template.Loader,
	validator template.Validator,
	htmlRenderer template.Renderer,
	pdfRenderer pdf.Renderer,
) HTTPDF

New creates a new httpdf service.