pdf

package module
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2021 License: MIT Imports: 11 Imported by: 7

README

go-wkhtmltopdf logo

Go bindings and high-level interface for HTML to PDF conversion.

Build status pkg.go.dev documentation MIT license Go report card Discord channel GitHub issues Buy me a coffee

Implements wkhtmltopdf Go bindings. It can be used to convert HTML documents to PDF files. The package does not use the wkhtmltopdf binary. Instead, it uses the wkhtmltox library directly.

Full documentation can be found at https://pkg.go.dev/github.com/adrg/go-wkhtmltopdf.

Examples

Prerequisites

In order to use the package, wkhtmltox must be installed. Installation packages for multiple operating systems can be found at https://builds.wkhtmltopdf.org.

Please see the wiki pages of this project for detailed installation instructions.

Installation

go get github.com/adrg/go-wkhtmltopdf

Usage

package main

import (
	"log"
	"os"

	pdf "github.com/adrg/go-wkhtmltopdf"
)

func main() {
	// Initialize library.
	if err := pdf.Init(); err != nil {
		log.Fatal(err)
	}
	defer pdf.Destroy()

	// Create object from file.
	object, err := pdf.NewObject("sample1.html")
	if err != nil {
		log.Fatal(err)
	}
	object.Header.ContentCenter = "[title]"
	object.Header.DisplaySeparator = true

	// Create object from URL.
	object2, err := pdf.NewObject("https://google.com")
	if err != nil {
		log.Fatal(err)
	}
	object.Footer.ContentLeft = "[date]"
	object.Footer.ContentCenter = "Sample footer information"
	object.Footer.ContentRight = "[page]"
	object.Footer.DisplaySeparator = true

	// Create object from reader.
	inFile, err := os.Open("sample2.html")
	if err != nil {
		log.Fatal(err)
	}
	defer inFile.Close()

	object3, err := pdf.NewObjectFromReader(inFile)
	if err != nil {
		log.Fatal(err)
	}
	object3.Zoom = 1.5
	object3.TOC.Title = "Table of Contents"

	// Create converter.
	converter, err := pdf.NewConverter()
	if err != nil {
		log.Fatal(err)
	}
	defer converter.Destroy()

	// Add created objects to the converter.
	converter.Add(object)
	converter.Add(object2)
	converter.Add(object3)

	// Set converter options.
	converter.Title = "Sample document"
	converter.PaperSize = pdf.A4
	converter.Orientation = pdf.Landscape
	converter.MarginTop = "1cm"
	converter.MarginBottom = "1cm"
	converter.MarginLeft = "10mm"
	converter.MarginRight = "10mm"

	// Convert objects and save the output PDF document.
	outFile, err := os.Create("out.pdf")
	if err != nil {
		log.Fatal(err)
	}
	defer outFile.Close()

	if err := converter.Run(outFile); err != nil {
		log.Fatal(err)
	}
}

Stargazers over time

Stargazers over time

Contributing

Contributions in the form of pull requests, issues or just general feedback, are always welcome. See CONTRIBUTING.MD.

Contributors: adrg, leandrosilva.

References

For more information see the wkhtmltopdf documentation and the wkhtmltox documentation.

License

Copyright (c) 2016 Adrian-George Bostan.

This project is licensed under the MIT license. See LICENSE for more details.

Documentation

Overview

Package pdf implements wkhtmltopdf Go bindings. It can be used to convert HTML documents to PDF files. The package does not use the wkhtmltopdf binary. Instead, it uses the wkhtmltox library directly.

Example

package main

import (
	"log"
	"os"

	pdf "github.com/adrg/go-wkhtmltopdf"
)

func main() {
	pdf.Init()
	defer pdf.Destroy()

	// Create object from file.
	object, err := pdf.NewObject("sample1.html")
	if err != nil {
		log.Fatal(err)
	}
	object.Header.ContentCenter = "[title]"
	object.Header.DisplaySeparator = true

	// Create object from URL.
	object2, err := pdf.NewObject("https://google.com")
	if err != nil {
		log.Fatal(err)
	}
	object.Footer.ContentLeft = "[date]"
	object.Footer.ContentCenter = "Sample footer information"
	object.Footer.ContentRight = "[page]"
	object.Footer.DisplaySeparator = true

	// Create object from reader.
	inFile, err := os.Open("sample2.html")
	if err != nil {
		log.Fatal(err)
	}
	defer inFile.Close()

	object3, err := pdf.NewObjectFromReader(inFile)
	if err != nil {
		log.Fatal(err)
	}
	object3.Zoom = 1.5
	object3.TOC.Title = "Table of Contents"

	// Create converter.
	converter, err := pdf.NewConverter()
	if err != nil {
		log.Fatal(err)
	}
	defer converter.Destroy()

	// Add created objects to the converter.
	converter.Add(object)
	converter.Add(object2)
	converter.Add(object3)

	// Set converter options.
	converter.Title = "Sample document"
	converter.PaperSize = pdf.A4
	converter.Orientation = pdf.Landscape
	converter.MarginTop = "1cm"
	converter.MarginBottom = "1cm"
	converter.MarginLeft = "10mm"
	converter.MarginRight = "10mm"

	// Convert objects and save the output PDF document.
	outFile, err := os.Create("out.pdf")
	if err != nil {
		log.Fatal(err)
	}
	defer outFile.Close()

	if err := converter.Run(outFile); err != nil {
		log.Fatal(err)
	}
}

For more information see http://wkhtmltopdf.org/usage/wkhtmltopdf.txt

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Destroy

func Destroy()

Destroy releases all the resources used by the library.

func HasPatchedQT added in v0.3.0

func HasPatchedQT() bool

HasPatchedQT returns true if the library is built against the wkhtmltopdf version of QT.

func Init

func Init() error

Init initializes the library, allocating all necessary resources.

func Version

func Version() string

Version returns the version of the library.

Types

type Colorspace

type Colorspace string

Colorspace represents the color mode of the output document content.

const (
	Color     Colorspace = "Color"
	Grayscale Colorspace = "Grayscale"
)

Colorspace values.

type Converter

type Converter struct {
	*ConverterOpts

	// Warning is called when a warning is issued in the conversion process.
	Warning func(msg string)

	// Error is called when an error is encountered in the conversion process.
	Error func(msg string)

	// PhaseChanged is called when the conversion phase changes.
	PhaseChanged func(phaseIndex int)

	// ProgressChanged is called when the conversion progress changes.
	// The progress is reported for each conversion phase.
	ProgressChanged func(progressPercent int)

	// Finished is called when the conversion process ends.
	Finished func(success bool)
	// contains filtered or unexported fields
}

Converter represents an HTML to PDF converter. The contained options are applied to all converted objects.

func NewConverter

func NewConverter() (*Converter, error)

NewConverter returns a new converter instance, configured using sensible defaults. See NewConverterOpts for the default options.

func NewConverterWithOpts added in v0.2.1

func NewConverterWithOpts(opts *ConverterOpts) (*Converter, error)

NewConverterWithOpts returns a new converter instance, configured using the specified options. If no options are provided, sensible defaults are used. See NewConverterOpts for the default options.

func (*Converter) Add

func (c *Converter) Add(object *Object)

Add appends the specified object to the list of objects to be converted.

func (*Converter) CurrentPhaseIndex added in v0.3.0

func (c *Converter) CurrentPhaseIndex() int

CurrentPhaseIndex returns the index of the current conversion phase.

func (*Converter) Destroy

func (c *Converter) Destroy()

Destroy releases all resources used by the converter.

func (*Converter) PhaseDescription added in v0.3.0

func (c *Converter) PhaseDescription(phaseIndex int) string

PhaseDescription returns the description of the phase with the specified index. If the phase index is invalid, the method returns an empty string.

func (*Converter) Phases added in v0.3.0

func (c *Converter) Phases() []string

Phases returns the list of phases undergone in the conversion process.

func (*Converter) Run

func (c *Converter) Run(w io.Writer) error

Run performs the conversion and copies the output to the provided writer.

type ConverterOpts added in v0.2.1

type ConverterOpts struct {
	// The paper size of the output document.
	// E.g.: A4.
	PaperSize PaperSize `json:"paperSize" yaml:"paperSize"`

	// The width of the output document.
	// E.g.: "4cm".
	Width string `json:"width" yaml:"width"`

	// The height of the output document.
	// E.g. "12in".
	Height string `json:"height" yaml:"height"`

	// The orientation of the output document.
	// E.g.: Portrait.
	Orientation Orientation `json:"orientation" yaml:"orientation"`

	// The color mode of the output document.
	// E.g.: Color.
	Colorspace Colorspace `json:"colorspace" yaml:"colorspace"`

	// DPI of the output document.
	// E.g.: 96.
	DPI uint64 `json:"dpi" yaml:"dpi"`

	// A number added to all page numbers when rendering headers, footers and
	// tables of contents.
	PageOffset int64 `json:"pageOffset" yaml:"pageOffset"`

	// Copies of the converted documents to be included in the output document.
	// E.g.: 1.
	Copies uint64 `json:"copies" yaml:"copies"`

	// Specifies whether copies should be collated.
	Collate bool `json:"collate" yaml:"collate"`

	// The title of the output document.
	Title string `json:"title" yaml:"title"`

	// Specifies whether outlines should be generated for the output document.
	GenerateOutline bool `json:"generateOutline" yaml:"generateOutline"`

	// The maximum number of nesting levels in outlines.
	// E.g.: 4.
	OutlineDepth uint64 `json:"outlineDepth" yaml:"outlineDepth"`

	// A location to write an XML representation of the generated outlines.
	OutlineDumpPath string `json:"outlineDumpPath" yaml:"outlineDumpPath"`

	// Specifies whether the conversion process should use lossless compression.
	UseCompression bool `json:"useCompression" yaml:"useCompression"`

	// Size of the top margin. (e.g. "2cm")
	// E.g.: "1cm".
	MarginTop string `json:"marginTop" yaml:"marginTop"`

	// Size of the bottom margin. (e.g. "2cm")
	// E.g.: "1cm".
	MarginBottom string `json:"marginBottom" yaml:"marginBottom"`

	// Size of the left margin. (e.g. "2cm")
	// E.g.: "10mm".
	MarginLeft string `json:"marginLeft" yaml:"marginLeft"`

	// Size of the right margin. (e.g. "2cm")
	// E.g.: "10mm".
	MarginRight string `json:"marginRight" yaml:"marginRight"`

	// The maximum number of DPI for the images in the output document.
	// E.g.: 600.
	ImageDPI uint64 `json:"imageDPI" yaml:"imageDPI"`

	// The compression factor to use for the JPEG images in the output document.
	// E.g.: 100 (range 0-100).
	ImageQuality uint64 `json:"imageQuality" yaml:"imageQuality"`

	// Path of the file used to load and store cookies for web objects.
	CookieJarPath string `json:"cookieJarPath" yaml:"cookieJarPath"`
}

ConverterOpts defines a set of options to be used in the conversion process.

func NewConverterOpts added in v0.2.1

func NewConverterOpts() *ConverterOpts

NewConverterOpts returns a new instance of converter options, configured using sensible defaults.

Defaults options:

PaperSize:       A4
Orientation:     Portrait
Colorspace:      Color
DPI:             96
Copies:          1
Collate:         true
GenerateOutline: true
UseCompression:  true
MarginLeft:      "10mm"
MarginRight:     "10mm"
ImageDPI:        600
ImageQuality:    100

type ErrorAction

type ErrorAction string

ErrorAction defines actions to take in case of object load failure.

const (
	ActionAbort  ErrorAction = "abort"
	ActionIgnore ErrorAction = "ignore"
	ActionSkip   ErrorAction = "skip"
)

Error action values.

type Header struct {
	// The system font name to use for headers/footers.
	// E.g.: "Arial".
	Font string `json:"font" yaml:"font"`

	// The font size to use for headers/footers.
	// E.g.: 12.
	FontSize uint64 `json:"fontSize" yaml:"fontSize"`

	// Content to print on each of the available regions of the header/footer.
	// Substitution variables that can be used in the content fields:
	//  - [page]       The number of the current page.
	//  - [frompage]   The number of the first page.
	//  - [topage]     The number of the last page.
	//  - [webpage]    The URL of the source page.
	//  - [section]    The name of the current section.
	//  - [subsection] The name of the current subsection.
	//  - [date]       The current date in system local format.
	//  - [isodate]    The current date in ISO 8601 extended format.
	//  - [time]       The current time in system local format.
	//  - [title]      The title of the of the current page object.
	//  - [doctitle]   The title of the output document.
	//  - [sitepage]   The number of the page in the currently converted site.
	//  - [sitepages]  The number of pages in the current site being converted.
	// e.g.: object.Footer.ContentRight = "[page]"
	ContentLeft   string `json:"contentLeft" yaml:"contentLeft"`
	ContentCenter string `json:"contentCenter" yaml:"contentCenter"`
	ContentRight  string `json:"contentRight" yaml:"contentRight"`

	// Specifies whether a line separator should be printed for headers/footers.
	DisplaySeparator bool `json:"displaySeparator" yaml:"displaySeparator"`

	// The amount of space between the header/footer and the content.
	// E.g.: 0.
	Spacing float64 `json:"spacing" yaml:"spacing"`

	// Location of a user defined HTML document to be used as the header/footer.
	CustomLocation string `json:"customLocation" yaml:"customLocation"`
}

Header contains settings related to the headers and footers of an object.

type Object

type Object struct {
	*ObjectOpts
	// contains filtered or unexported fields
}

Object represents an HTML document. The contained options are applied only to the current object.

func NewObject

func NewObject(location string) (*Object, error)

NewObject returns a new object instance from the document at the specified location. The location can be a file path or a URL. The object is configured using sensible defaults. See NewObjectOpts for the default options.

func NewObjectFromReader

func NewObjectFromReader(r io.Reader) (*Object, error)

NewObjectFromReader creates a new object from the specified reader. The object is configured using sensible defaults. See NewObjectOpts for the default options.

func NewObjectWithOpts added in v0.2.1

func NewObjectWithOpts(opts *ObjectOpts) (*Object, error)

NewObjectWithOpts returns a new object instance from the document at the specified location. The location can be a file path or a URL. The object is configured using the specified options. If no options are provided, sensible defaults are used. See NewObjectOpts for the default options.

func (*Object) Destroy

func (o *Object) Destroy()

Destroy releases all resources used by the object.

type ObjectOpts added in v0.2.1

type ObjectOpts struct {
	// Specifies the location of the HTML document. Can be a file path or a URL.
	Location string `json:"location" yaml:"location"`

	// Specifies whether external links in the HTML document should be converted
	// to external PDF links.
	UseExternalLinks bool `json:"useExternalLinks" yaml:"useExternalLinks"`

	// Specifies whether internal links in the HTML document should be converted
	// into PDF references.
	UseLocalLinks bool `json:"useLocalLinks" yaml:"useLocalLinks"`

	// Specifies whether HTML forms should be converted into PDF forms.
	ProduceForms bool `json:"produceForms" yaml:"produceForms"`

	// Specifies whether the sections from the HTML document are included in
	// outlines and TOCs.
	IncludeInOutline bool `json:"includeInOutline" yaml:"includeInOutline"`

	// Specifies whether the page count of the HTML document participates in
	// the counter used for tables of contents, headers and footers.
	CountPages bool `json:"countPages" yaml:"countPages"`

	// Contains settings for the TOC of the object.
	TOC TOC `json:"toc" yaml:"toc"`

	// Contains settings for the header of the object.
	Header Header `json:"header" yaml:"header"`

	// Contains settings for the footer of the object.
	Footer Header `json:"footer" yaml:"footer"`

	// The username to use when logging in to a website.
	Username string `json:"username" yaml:"username"`

	// The password to use when logging in to a website.
	Password string `json:"password" yaml:"password"`

	// The amount of milliseconds to wait after page load, before
	// executing JS scripts.
	// E.g.: 300.
	JavascriptDelay uint64 `json:"javascriptDelay" yaml:"javascriptDelay"`

	// Specifies the `window.status` value to wait for, before
	// rendering the page.
	// E.g.: "ready".
	WindowStatus string `json:"windowStatus" yaml:"windowStatus"`

	// Zoom factor to use for the document content.
	// E.g.: 1.
	Zoom float64 `json:"zoom" yaml:"zoom"`

	// Specifies whether local file access is blocked.
	BlockLocalFileAccess bool `json:"blockLocalFileAccess" yaml:"blockLocalFileAccess"`

	// Specifies whether slow JS scripts should be stopped.
	StopSlowScripts bool `json:"stopSlowScripts" yaml:"stopSlowScripts"`

	// Specifies a course of action when an HTML document fails to load.
	// E.g.: ActionAbort.
	ErrorAction ErrorAction `json:"errorAction" yaml:"errorAction"`

	// The name of a proxy to use when loading the HTML document.
	Proxy string `json:"proxy" yaml:"proxy"`

	// Specifies whether the background of the HTML document is preserved.
	PrintBackground bool `json:"printBackground" yaml:"printBackground"`

	// Specifies whether the images in the HTML document are loaded.
	LoadImages bool `json:"loadImages" yaml:"loadImages"`

	// Specifies whether Javascript should be executed.
	EnableJavascript bool `json:"enableJavascript" yaml:"enableJavascript"`

	// Specifies whether to use intelligent shrinkng in order to fit more
	// content on a page.
	UseSmartShrinking bool `json:"useSmartShrinking" yaml:"useSmartShrinking"`

	// The minimum font size allowed for rendering content.
	MinFontSize uint64 `json:"minFontSize" yaml:"minFontSize"`

	// The text encoding to use if the HTML document does not specify one.
	// E.g.: "utf-8".
	DefaultEncoding string `json:"defaultEncoding" yaml:"defaultEncoding"`

	// Specifies whether the content should be rendered using the print media
	// type instead of the screen media type.
	UsePrintMediaType bool `json:"usePrintMediaType" yaml:"usePrintMediaType"`

	// The location of a user defined stylesheet to use when converting
	// the HTML document.
	UserStylesheetLocation string `json:"userStylesheetLocation" yaml:"userStylesheetLocation"`

	// Specifies whether NS plugins should be enabled.
	EnablePlugins bool `json:"enablePlugins" yaml:"enablePlugins"`
}

ObjectOpts defines a set of options to be used in the conversion process.

func NewObjectOpts added in v0.2.1

func NewObjectOpts() *ObjectOpts

NewObjectOpts returns a new instance of object options, configured using sensible defaults.

Defaults options:

UseExternalLinks:  true
UseLocalLinks:     true
IncludeInOutline:  true
CountPages:        true
JavascriptDelay:   300
Zoom:              1
StopSlowScripts:   true
ErrorAction:       ActionAbort
PrintBackground:   true
LoadImages:        true
EnableJavascript:  true
UseSmartShrinking: true
DefaultEncoding:   "utf-8"
TOC:
	UseDottedLines:       true
	Title:                "Table of Contents"
	GenerateForwardLinks: true
	GenerateBackLinks:    true
	Indentation:          "1em"
	FontScale:            1
Header:
	Font:     "Arial"
	FontSize: 12
Footer:
	Font:     "Arial"
	FontSize: 12

type Orientation

type Orientation string

Orientation represents the orientation of the output document pages.

const (
	Portrait  Orientation = "Portrait"
	Landscape Orientation = "Landscape"
)

Page orientation values.

type PaperSize

type PaperSize string

PaperSize represents the size of the output document pages.

const (
	A0        PaperSize = "A0"        // 841 x 1189 mm
	A1        PaperSize = "A1"        // 594 x 841 mm
	A2        PaperSize = "A2"        // 420 x 594 mm
	A3        PaperSize = "A3"        // 297 x 420 mm
	A4        PaperSize = "A4"        // 210 x 297 mm
	A5        PaperSize = "A5"        // 148 x 210 mm
	A6        PaperSize = "A6"        // 105 x 148 mm
	A7        PaperSize = "A7"        // 74 x 105 mm
	A8        PaperSize = "A8"        // 52 x 74 mm
	A9        PaperSize = "A9"        // 37 x 52 mm
	B0        PaperSize = "B0"        // 1000 x 1414 mm
	B1        PaperSize = "B1"        // 707 x 1000 mm
	B2        PaperSize = "B2"        // 500 x 707 mm
	B3        PaperSize = "B3"        // 353 x 500 mm
	B4        PaperSize = "B4"        // 250 x 353 mm
	B5        PaperSize = "B5"        // 176 x 250 mm
	B6        PaperSize = "B6"        // 125 x 176 mm
	B7        PaperSize = "B7"        // 88 x 125 mm
	B8        PaperSize = "B8"        // 62 x 88 mm
	B9        PaperSize = "B9"        // 33 x 62 mm
	B10       PaperSize = "B10"       // 31 x 44 mm
	C5E       PaperSize = "C5E"       // 163 x 229 mm
	Comm10E   PaperSize = "Comm10E"   // 105 x 241 mm
	DLE       PaperSize = "DLE"       // 110 x 220 mm
	Executive PaperSize = "Executive" // 190.5 x 254 mm
	Folio     PaperSize = "Folio"     // 210 x 330 mm
	Ledger    PaperSize = "Ledger"    // 431.8 x 279.4 mm
	Legal     PaperSize = "Legal"     // 215.9 x 355.6 mm
	Letter    PaperSize = "Letter"    // 215.9 x 279.4 mm
	Tabloid   PaperSize = "Tabloid"   // 279.4 x 431.8 mm
)

Paper size values.

type TOC

type TOC struct {
	// Specifies whether dotted lines should be used for the line of items
	// of the TOC.
	UseDottedLines bool `json:"useDottedLines" yaml:"useDottedLines"`

	// The title used for the table of contents.
	// E.g.: "Table of Contents".
	Title string `json:"title" yaml:"title"`

	// Specifies whether the TOC items should contain links to the content.
	GenerateForwardLinks bool `json:"generateForwardLinks" yaml:"generateForwardLinks"`

	// Specifies whether the content should contain links to the TOC.
	GenerateBackLinks bool `json:"generateBackLinks" yaml:"generateBackLinks"`

	// The indentation used for the TOC nesting levels.
	// E.g.: "1em".
	Indentation string `json:"indentation" yaml:"indentation"`

	// Scaling factor for each nesting level of the TOC.
	// E.g.: 1.
	FontScale float64 `json:"fontScale" yaml:"fontScale"`
}

TOC contains settings related to the table of contents of an object.

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL