pdf

package module
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2023 License: MIT Imports: 11 Imported by: 0

README

go-wkhtmltopdf logo

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

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/litesrv/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.

Note: wkhtmltox does not seem to be actively maintained. Please see the project status for more information, recommendations and future plans.

Installation

go get github.com/litesrv/go-wkhtmltopdf

Usage

package main

import (
	"log"
	"os"

	pdf "github.com/litesrv/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)
	}
	object2.Footer.ContentLeft = "[date]"
	object2.Footer.ContentCenter = "Sample footer information"
	object2.Footer.ContentRight = "[page]"
	object2.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()

	// Run converter.
	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/litesrv/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 

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 

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 

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 

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 

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 

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 

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"`

	// The system font color to use for headers/footers.
	// E.g.: "#FFFFFF".
	FontColor string `json:"fontColor" yaml:"fontColor"`

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

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 

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 

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.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic-usage
converter-callbacks
http-server
http-server-advanced
json-input

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.