chromium

Documentation

Overview

Package chromium provides a module which adds routes for converting HTML documents to PDF. Other modules may also retrieve the API provided by this module.

Index

• Variables
• type API
• type Chromium
  • func (mod Chromium) Chromium() (API, error)
  • func (mod Chromium) Descriptor() gotenberg.ModuleDescriptor
  • func (mod Chromium) Metrics() ([]gotenberg.Metric, error)
  • func (mod Chromium) PDF(ctx context.Context, logger *zap.Logger, URL, outputPath string, ...) error
  • func (mod *Chromium) Provision(ctx *gotenberg.Context) error
  • func (mod Chromium) Routes() ([]api.Route, error)
  • func (mod Chromium) Validate() error
• type LinkTag
• type Options
  • func DefaultOptions() Options
  • func FormDataChromiumPDFOptions(ctx *api.Context) (*api.FormData, Options)
• type Provider
• type ScriptTag

Variables

var (
	// ErrURLNotAuthorized happens if a URL is not acceptable according to the
	// allowed/denied lists.
	ErrURLNotAuthorized = errors.New("URL not authorized")

	// ErrInvalidEmulatedMediaType happens if the emulated media type is not
	// "screen" nor "print". Empty value are allowed though.
	ErrInvalidEmulatedMediaType = errors.New("invalid emulated media type")

	// ErrInvalidEvaluationExpression happens if an evaluation expression
	// returns an exception or undefined.
	ErrInvalidEvaluationExpression = errors.New("invalid evaluation expression")

	// ErrInvalidPrinterSettings happens if the Options have one or more
	// aberrant values.
	ErrInvalidPrinterSettings = errors.New("invalid printer settings")

	// ErrPageRangesSyntaxError happens if the Options have an invalid page
	// ranges.
	ErrPageRangesSyntaxError = errors.New("page ranges syntax error")

	// ErrRpccMessageTooLarge happens when the messages received by
	// ChromeDevTools are larger than 100 MB.
	ErrRpccMessageTooLarge = errors.New("rpcc message too large")

	// ErrConsoleExceptions happens when there are exceptions in the Chromium
	// console. It also happens only if the Options.FailOnConsoleExceptions is
	// set to true.
	ErrConsoleExceptions = errors.New("console exceptions")
)

Types

type API

type API interface {
	PDF(ctx context.Context, logger *zap.Logger, URL, outputPath string, options Options) error
}

API helps to interact with Chromium for converting HTML documents to PDF.

type Chromium

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

Chromium is a module which provides both an API and routes for converting HTML document to PDF.

func (Chromium) Chromium

func (mod Chromium) Chromium() (API, error)

Chromium returns an API for interacting with Chromium for converting HTML documents to PDF.

func (Chromium) Descriptor

func (mod Chromium) Descriptor() gotenberg.ModuleDescriptor

Descriptor returns a Chromium's module descriptor.

func (Chromium) Metrics

func (mod Chromium) Metrics() ([]gotenberg.Metric, error)

Metrics returns the metrics.

func (Chromium) PDF

func (mod Chromium) PDF(ctx context.Context, logger *zap.Logger, URL, outputPath string, options Options) error

PDF converts a URL to PDF. It creates a dedicated Chromium instance. Substantial calls to this method may increase CPU and memory usage drastically. In such a scenario, the given context may also be done before the end of the conversion.

func (*Chromium) Provision

func (mod *Chromium) Provision(ctx *gotenberg.Context) error

Provision sets the module properties.

func (Chromium) Routes

func (mod Chromium) Routes() ([]api.Route, error)

Routes returns the HTTP routes.

func (Chromium) Validate

func (mod Chromium) Validate() error

Validate validates the module properties.

type LinkTag

type LinkTag struct {
	// Href is the "href" attribute of the HTML <link> element.
	// Required.
	Href string `json:"href"`
}

LinkTag represents an HTML <link> element.

type Options

type Options struct {
	// FailOnConsoleExceptions sets if the conversion should fail if there are
	// exceptions in the Chromium console.
	// Optional.
	FailOnConsoleExceptions bool

	// WaitDelay is the duration to wait when loading an HTML document before
	// converting it to PDF.
	// Optional.
	WaitDelay time.Duration

	// WaitWindowStatus is the window.status value to wait for before
	// converting an HTML document to PDF.
	// Optional.
	WaitWindowStatus string

	// WaitForExpression is the custom JavaScript expression to wait before
	// converting an HTML document to PDF until it returns true
	// Optional.
	WaitForExpression string

	// UserAgent overrides the default User-Agent header.
	// Optional.
	UserAgent string

	// ExtraHTTPHeaders are the HTTP headers to send by Chromium while loading
	// the HTML document.
	// Optional.
	ExtraHTTPHeaders map[string]string

	// ExtraLinkTags are HTML <link> attributes that are added on the fly.
	// Optional.
	ExtraLinkTags []LinkTag

	// EmulatedMediaType is the media type to emulate, either "screen" or
	// "print".
	// Optional.
	EmulatedMediaType string

	// ExtraScriptTags are HTML <script> attributes that are added on the fly.
	// Optional.
	ExtraScriptTags []ScriptTag

	// Landscape sets the paper orientation.
	// Optional.
	Landscape bool

	// PrintBackground prints the background graphics.
	// Optional.
	PrintBackground bool

	// Scale is the scale of the page rendering.
	// Optional.
	Scale float64

	// PaperWidth is the paper width, in inches.
	// Optional.
	PaperWidth float64

	// PaperHeight is the paper height, in inches.
	// Optional.
	PaperHeight float64

	// MarginTop is the top margin, in inches.
	// Optional.
	MarginTop float64

	// MarginBottom is the bottom margin, in inches.
	// Optional.
	MarginBottom float64

	// MarginLeft is the left margin, in inches.
	// Optional.
	MarginLeft float64

	// MarginRight is the right margin, in inches.
	// Optional.
	MarginRight float64

	// Page ranges to print, e.g., '1-5, 8, 11-13'. Empty means all pages.
	// Optional.
	PageRanges string

	// HeaderTemplate is the HTML template of the header. It should be valid
	// HTML  markup with following classes used to inject printing values into
	// them:
	// - date: formatted print date
	// - title: document title
	// - url: document location
	// - pageNumber: current page number
	// - totalPages: total pages in the document
	// For example, <span class=title></span> would generate span containing
	// the title.
	// Optional.
	HeaderTemplate string

	// FooterTemplate is the HTML template of the footer. It should use the
	// same format as the HeaderTemplate.
	// Optional.
	FooterTemplate string

	// PreferCSSPageSize defines whether to prefer page size as defined by CSS.
	// If false, the content will be scaled to fit the paper size.
	// Optional.
	PreferCSSPageSize bool
}

Options are the available options for converting HTML document to PDF.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default values for Options.

func FormDataChromiumPDFOptions

func FormDataChromiumPDFOptions(ctx *api.Context) (*api.FormData, Options)

FormDataChromiumPDFOptions creates Options form the form data. Fallback to default value if the considered key is not present.

type Provider

type Provider interface {
	Chromium() (API, error)
}

Provider is a module interface which exposes a method for creating an API for other modules.

func (m *YourModule) Provision(ctx *gotenberg.Context) error {
	provider, _ := ctx.Module(new(chromium.Provider))
	chromium, _ := provider.(chromium.Provider).Chromium()
}

type ScriptTag

type ScriptTag struct {
	// Src is the "src" attribute of the HTML <script> element.
	// Required.
	Src string `json:"src"`
}

ScriptTag represents an HTML <script> element.