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
• func FormDataChromiumPdfFormats(ctx *api.Context) gotenberg.PdfFormats
• type Api
• type ApiMock
  • func (api *ApiMock) Pdf(ctx context.Context, logger *zap.Logger, url, outputPath string, ...) error
• type Chromium
  • func (mod *Chromium) Checks() ([]health.CheckerOption, error)
  • 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) Ready() error
  • func (mod *Chromium) Routes() ([]api.Route, error)
  • func (mod *Chromium) Start() error
  • func (mod *Chromium) StartupMessage() string
  • func (mod *Chromium) Stop(ctx context.Context) error
  • func (mod *Chromium) Validate() error
• type Options
  • func DefaultOptions() Options
  • func FormDataChromiumPdfOptions(ctx *api.Context) (*api.FormData, Options)
• type Provider

Variables

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

	// ErrOmitBackgroundWithoutPrintBackground happens if
	// Options.OmitBackground is set to true but not Options.PrintBackground.
	ErrOmitBackgroundWithoutPrintBackground = errors.New("omit background without print background")

	// 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")
)

Functions

func FormDataChromiumPdfFormats

func FormDataChromiumPdfFormats(ctx *api.Context) gotenberg.PdfFormats

FormDataChromiumPdfFormats creates gotenberg.PdfFormats from the form data. Fallback to default value if the considered key is not present.

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 ApiMock

type ApiMock struct {
	PdfMock func(ctx context.Context, logger *zap.Logger, url, outputPath string, options Options) error
}

ApiMock is a mock for the Api interface.

func (*ApiMock) Pdf

func (api *ApiMock) Pdf(ctx context.Context, logger *zap.Logger, url, outputPath string, options Options) error

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) Checks

func (mod *Chromium) Checks() ([]health.CheckerOption, error)

Checks adds a health check that verifies if Chromium is healthy.

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.

func (*Chromium) Provision

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

Provision sets the module properties.

func (*Chromium) Ready

func (mod *Chromium) Ready() error

Ready returns no error if the module is ready.

func (*Chromium) Routes

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

Routes returns the HTTP routes.

func (*Chromium) Start

func (mod *Chromium) Start() error

Start does nothing if auto-start is not enabled. Otherwise, it starts a browser instance.

func (*Chromium) StartupMessage

func (mod *Chromium) StartupMessage() string

StartupMessage returns a custom startup message.

func (*Chromium) Stop

func (mod *Chromium) Stop(ctx context.Context) error

Stop stops the current browser instance.

func (*Chromium) Validate

func (mod *Chromium) Validate() error

Validate validates the module properties.

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

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

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

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

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

	// OmitBackground hides default white background and allows generating PDFs
	// with transparency.
	// Optional.
	OmitBackground 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 expectedOptions 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 from 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))
	api, _ := provider.(chromium.Provider).Chromium()
}