renderer

README

renderer

Golang module for executing url rendering / webpage pdf generation with chromedp

Requirements

chromium / chrome browser installed on host

Options configuration

Browser

Browser config values:

• IdleType: Method to detemine render is complete
  • Type: string (valid values: auto, networkIdle, InteractiveTime)
  • Default: auto
• BrowserExecPath: Manually set chrome / chromium browser's executable path
  • Type: String
  • Default: Empty string (Auto detect)
• Container: Use this option to execute chrome / chromium browser in container environment
  • Type: bool
  • Default: false
• DebugMode: Output debug message if set to true
  • Type: bool
  • Default: false
• ChromiumDebug: Output debug message on chromium if set to true
  • Type: bool
  • Default: false

Renderer

Renderer config values:

• Headless: Browser execution mode
  • Type: bool
  • Default: false
• WindowWidth: Width of browser's window size
  • Type: Int
  • Default: 1000
• WindowHeight: Height of browser's window size
  • Type: Int
  • Default: 1000
• Timeout: Seconds before rendering timeout
  • Type: Int
  • Default: 30
• ImageLoad: Load image when rendering
  • Type: bool
  • Default: false
• UserAgent: Set custom user agent value
  • Type: string
  • Default: Empty string (Will user default user agent of the browser)

Renderer option settings:

• BrowserOpts: Browser configuration
  • Type: BrowserConf
• Opts: Renderer configuration
  • Type: RendererConf

Note: Default renderer option DefaultRendererOption will be used if not set no explicit option is set.

Example

See usage example at examples

Build Example

cd examples/render
go build

Run Example

Usage: ./render <url>
  -bHeight int
        height of browser window's size (default 1080)
  -bWidth int
        width of browser window's size (default 1920)
  -browserPath string
        manually set browser executable path
  -chromiumDebug
        turn on for chromium debug message output (must enable debug for output)
  -container
        indicate if running in container (docker / lambda) environment
  -debug
        turn on for outputing debug message
  -headless
        automation browser execution mode (default true)
  -idleType string
        how to determine loading idle and return, valid input: auto, networkIdle, InteractiveTime (default "auto")
  -imageLoad
        indicate if load image when rendering
  -networkIdleMaxInflight int
        maximum inflight requests to consider network idle, only work with idleType=networkIdle,auto
  -networkIdleWait duration
        network idle wait window to check for requests count, only work with idleType=networkIdle,auto (default 500ms)
  -timeout int
        seconds before timeout when rendering (default 30)
  -userAgent string
        set custom user agent for sending request in automation browser

Render PDF

Pdf options values:

• BrowserOpts: Browser configuration
  • Type: BrowserConf
• RendererOpts: Renderer configuration
  • Type: RendererConf
• Landscape: Set paper orientation to landscape
  • Type: bool
  • Default: false
• DisplayHeaderFooter: Display header and footer
  • Type: bool
  • Default: false
• PaperWidthCm: Paper width in centimeter
  • Type: float64
  • Default: 21
• PaperHeightCm: Paper height in centimeter
  • Type: float64
  • Default: 29.7
• MarginTopCm: Top margin in centimeter
  • Type: float64
  • Default: 1
• MarginBottomCm: Bottom margin in centimeter
  • Type: float64
  • Default: 1
• MarginLeftCm: Left margin in centimeter
  • Type: float64
  • Default: 1
• MarginRigthCm: Right margin in centimeter
  • Type: float64
  • Default: 1

Example

See usage example at examples

Build Example

cd examples/pdf
go build

Run Example

Usage: ./pdf <url>
  -browserPath string
        manually set browser executable path
  -chromiumDebug
        turn on for chrome debug message output (must enable debug for output)
  -container
        indicate if running in container (docker / lambda) environment
  -debug
        turn on for outputing debug message
  -headerFooter
        show header and footer
  -idleType string
        how to determine loading idle and return, valid input: auto, networkIdle, InteractiveTime (default "auto")
  -landscape
        create pdf in landscape layout
  -marginBottom float
        bottom margin in centimeter (default 1)
  -marginLeft float
        left margin in centimeter (default 1)
  -marginRight float
        right margin in centimeter (default 1)
  -marginTop float
        top margin in centimeter (default 1)
  -paperHeight float
        paper height in centimeter
  -paperWidth float
        paper width in centimeter

Documentation

Index

• Variables
• func IsValidIdleType(idleType string) bool
• type BrowserConf
• type PdfOption
• type Renderer
  • func NewRenderer(options ...WithOption) *Renderer
  • func (r *Renderer) Listen(ctx context.Context, conf BrowserConf)
  • func (r *Renderer) RenderPage(urlStr string, opts *RendererOption) ([]byte, error)
  • func (r *Renderer) RenderPdf(urlStr string, opts *PdfOption) ([]byte, error)
• type RendererConf
• type RendererOption
• type WithOption
  • func WithIdleCheck(idleWait time.Duration, maxInflight int) WithOption
  • func WithLogger(logger *slog.Logger) WithOption

Examples

• Renderer.RenderPage
• Renderer.RenderPdf

Variables

var DefaultPdfOption = PdfOption{
	BrowserOpts: BrowserConf{
		IdleType: defaultIdleType,
	},
	RendererOpts: RendererConf{
		Headless:     true,
		WindowWidth:  defaultWindowWidth,
		WindowHeight: defaultWindowHeight,
		Timeout:      defaultTimeout,
		ImageLoad:    true,
	},
}

Chrome DevTools Protocol reference for default values: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF

var DefaultRendererConf = RendererConf{
	Headless:     true,
	WindowWidth:  defaultWindowWidth,
	WindowHeight: defaultWindowHeight,
	Timeout:      defaultTimeout,
}

var DefaultRendererOption = RendererOption{
	BrowserOpts: BrowserConf{
		IdleType: defaultIdleType,
	},
	Opts: DefaultRendererConf,
}

Functions

func IsValidIdleType

func IsValidIdleType(idleType string) bool

IsValidIdleType checks if the given idleType is valid

Types

type BrowserConf

type BrowserConf struct {
	IdleType        string
	BrowserExecPath string
	ChromiumDebug   bool
	DebugMode       bool
	Container       bool
}

type PdfOption

type PdfOption struct {
	BrowserOpts         BrowserConf
	RendererOpts        RendererConf
	Landscape           bool
	DisplayHeaderFooter bool
	PaperWidthCm        float64
	PaperHeightCm       float64
	MarginTopCm         float64
	MarginBottomCm      float64
	MarginLeftCm        float64
	MarginRightCm       float64
}

type Renderer

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

func NewRenderer

func NewRenderer(options ...WithOption) *Renderer

NewRenderer create new renderer instance. Function options can be pass as argument to set for configuration (logger for now)

func (*Renderer) Listen

func (r *Renderer) Listen(ctx context.Context, conf BrowserConf)

func (*Renderer) RenderPage

func (r *Renderer) RenderPage(urlStr string, opts *RendererOption) ([]byte, error)

RenderPage render the given url with automated chrome browser and return back the result html content. RendererOption is use for setting the behavior of the automated browser while rendering the page.

Example

package main

import (
	"log/slog"
	"os"

	"github.com/liuminhaw/renderer"
)

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

	r := renderer.NewRenderer(renderer.WithLogger(logger))
	content, err := r.RenderPage("https://www.example.com", nil)
	if err != nil {
		logger.Error(err.Error())
		os.Exit(1)
	}

	f, err := os.Create("result.html")
	if err != nil {
		logger.Error(err.Error())
		os.Exit(1)
	}
	defer f.Close()

	f.Write(content)
}

func (*Renderer) RenderPdf

func (r *Renderer) RenderPdf(urlStr string, opts *PdfOption) ([]byte, error)

RenderPdf generate and return the pdf as byte array from the given url using automated chrome browser. PdfOption is for setting the style of the generated pdf.

Example

package main

import (
	"log/slog"
	"os"

	"github.com/liuminhaw/renderer"
)

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

	r := renderer.NewRenderer(renderer.WithLogger(logger))

	content, err := r.RenderPdf("https://www.example.com", nil)
	if err != nil {
		logger.Error(err.Error())
		os.Exit(1)
	}

	f, err := os.Create("result.pdf")
	if err != nil {
		logger.Error(err.Error())
		os.Exit(1)
	}
	defer f.Close()

	f.Write(content)
}

type RendererConf

type RendererConf struct {
	Headless     bool
	WindowWidth  int
	WindowHeight int
	Timeout      int
	ImageLoad    bool
	UserAgent    string
}

type RendererOption

type RendererOption struct {
	BrowserOpts BrowserConf
	Opts        RendererConf
}

type WithOption

type WithOption func(*Renderer)

Function options

func WithIdleCheck

func WithIdleCheck(idleWait time.Duration, maxInflight int) WithOption

WithIdleCheck can be provided to NewRenderer function to determine how to check if the network is idle before returning the result. network is considered idle when there are less than or equal to maxInflight requests in action in the last `idleWait` time duration window.

func WithLogger

func WithLogger(logger *slog.Logger) WithOption

WithLogger can be provided to NewRenderer function to set logger for the Renderer