chromium

package
v8.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 29, 2024 License: MIT Imports: 37 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
var (
	// 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")

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

	// ErrInvalidHttpStatusCode happens when the status code from the main page
	// matches with one of the entry in [Options.FailOnHttpStatusCodes].
	ErrInvalidHttpStatusCode = errors.New("invalid HTTP status code")

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

	// ErrLoadingFailed happens when a URL failed to load.
	ErrLoadingFailed = errors.New("loading failed")

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

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

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

Functions

func FormDataChromiumPdfFormats 

func FormDataChromiumPdfFormats(form *api.FormData) gotenberg.PdfFormats

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

func FormDataPdfMetadata added in v8.3.0 

func FormDataPdfMetadata(form *api.FormData) map[string]interface{}

FormDataPdfMetadata creates metadata object from the form data.

Types

type Api 

type Api interface {
	Pdf(ctx context.Context, logger *zap.Logger, url, outputPath string, options PdfOptions) error
	Screenshot(ctx context.Context, logger *zap.Logger, url, outputPath string, options ScreenshotOptions) 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 PdfOptions) error
	ScreenshotMock func(ctx context.Context, logger *zap.Logger, url, outputPath string, options ScreenshotOptions) 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 PdfOptions) error

func (*ApiMock) Screenshot 

func (api *ApiMock) Screenshot(ctx context.Context, logger *zap.Logger, url, outputPath string, options ScreenshotOptions) 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 PdfOptions) 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) Screenshot 

func (mod *Chromium) Screenshot(ctx context.Context, logger *zap.Logger, url, outputPath string, options ScreenshotOptions) error

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 Cookie struct {
	// Name is the cookie name.
	// Required.
	Name string `json:"name"`

	// Value is the cookie value.
	// Required.
	Value string `json:"value"`

	// Domain is the cookie domain.
	// Required.
	Domain string `json:"domain"`

	// Path is the cookie path.
	// Optional.
	Path string `json:"path,omitempty"`

	// Secure sets the cookie secure if true.
	// Optional.
	Secure bool `json:"secure,omitempty"`

	// HttpOnly sets the cookie as HTTP-only if true.
	// Optional.
	HttpOnly bool `json:"httpOnly,omitempty"`

	// SameSite is cookie 'Same-Site' status.
	// Optional.
	SameSite network.CookieSameSite `json:"sameSite,omitempty"`
}

Cookie gathers the available entries for setting a cookie in the Chromium cookies' jar.

type Options 

type Options struct {
	// SkipNetworkIdleEvent set if the conversion should wait for the
	// "networkIdle" event, drastically improving the conversion speed. It may
	// not be suitable for all HTML documents, as some may not be fully
	// rendered until this event is fired.
	SkipNetworkIdleEvent bool

	// FailOnHttpStatusCodes sets if the conversion should fail if the status
	// code from the main page matches with one of its entries.
	FailOnHttpStatusCodes []int64

	// FailOnConsoleExceptions sets if the conversion should fail if there are
	// exceptions in the Chromium console.
	FailOnConsoleExceptions bool

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

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

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

	// Cookies are the cookies to put in the Chromium cookies' jar.
	Cookies []Cookie

	// UserAgent overrides the default 'User-Agent' HTTP header.
	UserAgent string

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

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

	// OmitBackground hides default white background and allows generating PDFs
	// with transparency.
	OmitBackground bool
}

Options are the common options for all conversions.

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions returns the default values for Options.

func FormDataChromiumOptions 

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

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

type PdfOptions 

type PdfOptions struct {
	Options

	// Landscape sets the paper orientation.
	Landscape bool

	// PrintBackground prints the background graphics.
	PrintBackground bool

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

	// SinglePage defines whether to print the entire content in one single
	// page.
	SinglePage bool

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

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

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

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

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

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

	// Page ranges to print, e.g., '1-5, 8, 11-13'. Empty means all pages.
	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.
	HeaderTemplate string

	// FooterTemplate is the HTML template of the footer. It should use the
	// same format as the HeaderTemplate.
	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.
	PreferCssPageSize bool
}

PdfOptions are the available options for converting an HTML document to PDF.

func DefaultPdfOptions 

func DefaultPdfOptions() PdfOptions

DefaultPdfOptions returns the default values for PdfOptions.

func FormDataChromiumPdfOptions 

func FormDataChromiumPdfOptions(ctx *api.Context) (*api.FormData, PdfOptions)

FormDataChromiumPdfOptions creates PdfOptions 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()
}

type ScreenshotOptions 

type ScreenshotOptions struct {
	Options

	// Width is the device screen width in pixels.
	Width int

	// Height is the device screen height in pixels.
	Height int

	// Clip defines whether to clip the screenshot according to the device
	// dimensions.
	Clip bool

	// Format is the image compression format, either "png" or "jpeg" or
	// "webp".
	Format string

	// Quality is the compression quality from range [0..100] (jpeg only).
	Quality int

	// OptimizeForSpeed defines whether to optimize image encoding for speed,
	// not for resulting size.
	OptimizeForSpeed bool
}

ScreenshotOptions are the available options for capturing a screenshot from an HTML document.

func DefaultScreenshotOptions 

func DefaultScreenshotOptions() ScreenshotOptions

DefaultScreenshotOptions returns the default values for ScreenshotOptions.

func FormDataChromiumScreenshotOptions 

func FormDataChromiumScreenshotOptions(ctx *api.Context) (*api.FormData, ScreenshotOptions)

FormDataChromiumScreenshotOptions creates ScreenshotOptions from the form data. Fallback to default value if the considered key is not present.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.