maroto

package module
v0.12.1 Latest Latest
Warning

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

 Go to latest Published: Aug 1, 2019 License: MIT Imports: 7 Imported by: 0

README

Maroto GoDoc Travis Code Coverage Go Report Card

A Maroto way to create PDFs. Maroto is inspired in Bootstrap and uses Gofpdf. Fast and simple.

Maroto definition: Brazilian expression, means an astute/clever/intelligent person.

You can write your PDFs like you are creating a site using Bootstrap. A Row may have many Cols, and a Col may have many components. Besides that, pages will be added when content may extrapolate the useful area. You can define a header which will be added always when a new page appear, in this case, a header may have many rows, lines or tablelist.

Installation

  • With go get:
go get -u github.com/johnfercher/maroto
  • With dep:
dep ensure -add github.com/johnfercher/maroto

Features

TODO

  • RegisterFooter
  • Increase Code Coverage
  • Create a custom mock with better assertions

Example

Result

Here is the pdf generated.

result

Code
func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	//m.SetDebugMode(true)

	byteSlices, _ := ioutil.ReadFile("assets/images/gopher2.png")

	base64 := base64.StdEncoding.EncodeToString(byteSlices)

	header, contents := getContents()

	m.RegisterHeader(func() {

		// Image, Barcode and QrCode
		m.Row(20, func() {
			m.Col(func() {
				m.Base64Image(base64, maroto.Png, &maroto.RectProp{
					Percent: 85,
				})
			})

			m.ColSpaces(2)

			m.Col(func() {
				m.QrCode("https://github.com/johnfercher/maroto", &maroto.RectProp{
					Percent: 75,
				})
			})

			m.Col(func() {
				id := "123456789"
				_ = m.Barcode(id, &maroto.RectProp{
					Percent: 70,
				})
				m.Text(id, &maroto.TextProp{
					Size:  8,
					Align: maroto.Center,
					Top:   17,
				})
			})
		})

		m.Line(1.0)

		// Image and Old License
		m.Row(12, func() {
			m.Col(func() {
				m.FileImage("assets/images/gopher1.jpg", nil)
			})

			m.ColSpace()

			m.Col(func() {
				m.Text("PDFGenerator: Maroto", &maroto.TextProp{
					Top: 4,
				})
				m.Text("Type: Easy & Fast", &maroto.TextProp{
					Top: 10,
				})
			})

			m.ColSpace()

			m.Col(func() {
				m.Text("GPL3", &maroto.TextProp{
					Size:  16,
					Style: maroto.Bold,
					Top:   8,
				})
			})
		})

		m.Line(1.0)

		// Features
		m.Row(22, func() {
			m.Col(func() {
				m.Text("Grid System", &maroto.TextProp{
					Size:  18,
					Style: maroto.Bold,
					Align: maroto.Center,
					Top:   9,
				})
				m.Text("Bootstrap Like + Úñîçòdë", &maroto.TextProp{
					Size:  12,
					Align: maroto.Center,
					Top:   17,
				})
			})
		})

		m.Line(1.0)

	})

	m.TableList(header, contents, nil)

	// Signatures
	m.Row(30, func() {
		m.Col(func() {
			m.Signature("Signature 1", nil)
		})

		m.Col(func() {
			m.Signature("Signature 2", nil)
		})

		m.Col(func() {
			m.Signature("Signature 3", nil)
		})
	})

	_ = m.OutputFileAndClose("maroto.pdf")
}

Documentation

Overview

Maroto is a package which provide a simple way to generate PDF documents. Maroto is inspired in Bootstrap and uses gofpdf. Simple and Fast

Features and Components

- Grid system with rows and columns

- Automatic page breaks

- Inclusion of JPEG, PNG, GIF, TIFF and basic path-only SVG images

- Lines

- Barcodes

- Qrcodes

- Signatures

Maroto has only gofpdf dependency. All tests pass on Linux and Mac.

Installation

To install the package on your system, run 

go get github.com/johnfercher/maroto

Later, to receive updates, run 

go get -u -v github.com/johnfercher/maroto/...

Quick Start

The following Go Code generates a simple PDF file. 

    m := maroto.NewMaroto(maroto.Portrait, maroto.A4)

    m.Row("MyRow", 10, func() {
		m.Col("MyCol", func() {
			m.Text("MyText", &maroto.TextProp{
				Size: 18,
				Style: maroto.Bold,
				Align: maroto.Center,
				Top: 9,
			})
		})
	})

	m.OutputFileAndClose("maroto.pdf")

See the functions in the maroto_test.go file (shown as examples in this documentation) for more advanced PDF examples.

Conversion Notes

This package is an high level API from gofpdf. The original API names have been slightly adapted. And the package search to be simpler to use.

The main contribution upside gofpdf is the grid system with high level components.

License

Maroto is released under the GPL3 License.

Acknowledgments

This package’s Code and documentation are based on gofpdf.

Roadmap

- Improve test coverage as reported by the coverage tool.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Align 

type Align string

Align is arRepresentation of a column align 

const (
	// Left represents a left horizontal align
	Left Align = "L"
	// Right represents a right horizontal align
	Right Align = "R"
	// Center represents a center horizontal and/or vertical align
	Center Align = "C"
	// Top represents a top vertical align
	Top Align = "T"
	// Bottom represents a bottom vertical align
	Bottom Align = "B"
	// Middle represents a middle align (from gofpdf)
	Middle Align = "M"
)

type Code 

type Code interface {
	AddQr(code string, marginTop float64, indexCol float64, qtdCols float64, colHeight float64, percent float64)
	AddBar(code string, marginTop float64, indexCol float64, qtdCols float64, colHeight float64, percent float64) (err error)
}

Code is the abstraction which deals of how to add QrCodes or Barcode in a PDF

func NewCode 

func NewCode(pdf gofpdf.Pdf, math Math) Code

NewCode create a Code

type Extension 

type Extension string

Extension is a representation of a Image extension 

const (
	// Jpg represents a jpg extension
	Jpg Extension = "jpg"
	// Png represents a png extension
	Png Extension = "png"
)

type Family 

type Family string

Family is a representation of a family Font 

const (
	// Arial represents an arial Font
	Arial Family = "arial"
	// Helvetica represents a helvetica Font
	Helvetica Family = "helvetica"
	// Symbol represents a symbol Font
	Symbol Family = "symbol"
	// ZapBats represents a zapfdingbats Font
	ZapBats Family = "zapfdingbats"
	// Courier represents a courier Font
	Courier Family = "courier"
)

type Font 

type Font interface {
	SetFamily(family Family)
	SetStyle(style Style)
	SetSize(size float64)
	SetFont(family Family, style Style, size float64)
	GetFamily() Family
	GetStyle() Style
	GetSize() float64
	GetFont() (Family, Style, float64)
}

Font is the abstraction which deals of how to set font configurations

func NewFont 

func NewFont(pdf gofpdf.Pdf, size float64, family Family, style Style) Font

NewFont create a Font

type Image 

type Image interface {
	AddFromFile(path string, marginTop float64, indexCol float64, qtdCols float64, colHeight float64, percent float64)
	AddFromBase64(b64 string, marginTop float64, indexCol float64, qtdCols float64, colHeight float64, percent float64, extension Extension)
}

Font is the abstraction which deals of how to add images in a PDF

func NewImage 

func NewImage(pdf gofpdf.Pdf, math Math) Image

NewImage create an Image

type Maroto 

type Maroto interface {
	// Grid System
	Row(height float64, closure func())
	RegisterHeader(closure func())
	Col(closure func())
	ColSpace()
	ColSpaces(qtd int)

	// Helpers
	SetDebugMode(on bool)
	GetDebugMode() bool
	GetPageSize() (float64, float64)

	// Outside Col/Row Components
	TableList(header []string, contents [][]string, prop *TableListProp)
	Line(spaceHeight float64)

	// Inside Col/Row Components
	Text(text string, prop *TextProp)
	FileImage(filePathName string, prop *RectProp)
	Base64Image(base64 string, extension Extension, prop *RectProp)
	Barcode(code string, prop *RectProp) error
	QrCode(code string, prop *RectProp)
	Signature(label string, prop *SignatureProp)

	// File System
	OutputFileAndClose(filePathName string) error
	Output() (bytes.Buffer, error)
}

Maroto is the principal abstraction to create a PDF document.

func NewMaroto 

func NewMaroto(orientation Orientation, pageSize PageSize) Maroto

NewMaroto create a Maroto instance returning a pointer to PdfMaroto Receive an Orientation and a PageSize.

type Math 

type Math interface {
	GetWidthPerCol(qtdCols float64) float64
	GetRectCenterColProperties(imageWidth float64, imageHeight float64, qtdCols float64, colHeight float64, indexCol float64, percent float64) (x float64, y float64, w float64, h float64)
	GetCenterCorrection(outerSize, innerSize float64) float64
}

Math is the abstraction which deals with useful calc

func NewMath 

func NewMath(pdf gofpdf.Pdf) Math

NewMath create a Math

type Orientation 

type Orientation string

Orientation is a representation of a page orientation 

const (
	// Portrait represents the portrait orientation.
	Portrait Orientation = "P"
	// Landscape represents the landscape orientation.
	Landscape Orientation = "L"
)

type PageSize 

type PageSize string

PageSize is a representation of an page size 

const (
	// A3 represents DIN/ISO A3 page size
	A3 PageSize = "A3"
	// A4 represents DIN/ISO A4 page size
	A4 PageSize = "A4"
	// A5 represents DIN/ISO A5 page size
	A5 PageSize = "A5"
	// Letter represents US Letter page size
	Letter PageSize = "Letter"
	// Legal represents US Legal page size
	Legal PageSize = "Legal"
)

type PdfMaroto 

type PdfMaroto struct {
	Pdf        gofpdf.Pdf
	Math       Math
	Font       Font
	TextHelper Text
	SignHelper Signature
	Image      Image
	Code       Code

	DebugMode bool
	// contains filtered or unexported fields
}

PdfMaroto is the principal structure which implements Maroto abstraction

func (*PdfMaroto) Barcode 

func (self *PdfMaroto) Barcode(code string, prop *RectProp) (err error)

Barcode create an barcode inside a cell.

func (*PdfMaroto) Base64Image 

func (self *PdfMaroto) Base64Image(base64 string, extension Extension, prop *RectProp)

Base64Image add an Image reading byte slices inside a cell. Defining Image properties.

Example

ExamplePdfMaroto_Base64Image demonstrates how add a Image reading a base64 string. When rectProp is nil, method make Image fullfill the context cell, based on width and cell from Image and cell. When center is true, left and top has no effect. Percent represents the width/height of the Image inside the cell: Ex: 85, means that Image will have width of 85% of column width. When center is false, is possible to manually positioning the Image with left and top. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0
	base64String := "y7seWGHE923Sdgs..."

	m.Row(rowHeight, func() {
		m.Col(func() {
			m.Base64Image(base64String, maroto.Png, &maroto.RectProp{
				Left:    5,
				Top:     5,
				Center:  true,
				Percent: 85,
			})
		})
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) Col 

func (self *PdfMaroto) Col(closure func())

Col create a column inside a row and enable to add components inside.

Example

ExamplePdfMaroto_Col demonstrates how to add a useful column 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		m.Col(func() {
			// Add Image, Text, Signature, QrCode or Barcode...
		})
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) ColSpace 

func (self *PdfMaroto) ColSpace()

ColSpace create an empty column inside a row.

Example

ExamplePdfMaroto_ColSpace demonstrates how to add a empty column inside a row. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		m.ColSpace()
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) ColSpaces 

func (self *PdfMaroto) ColSpaces(qtd int)

ColSpace create some empty columns inside a row.

Example

ExamplePdfMaroto_ColSpaces demonstrates how to add some empty columns inside a row. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		m.ColSpaces(2)
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) FileImage 

func (self *PdfMaroto) FileImage(filePathName string, prop *RectProp)

FileImage add an Image reading from disk inside a cell. Defining Image properties.

Example

ExamplePdfMaroto_FileImage demonstrates how add a Image reading from disk. When rectProp is nil, method make Image fulfill the context cell, based on width and cell from Image and cell. When center is true, left and top has no effect. Percent represents the width/height of the Image inside the cell: Ex: 85, means that Image will have width of 85% of column width. When center is false, is possible to manually positioning the Image with left and top. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		m.Col(func() {
			m.FileImage("path/Image.jpg", &maroto.RectProp{
				Left:    5,
				Top:     5,
				Center:  true,
				Percent: 85,
			})
		})
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) GetDebugMode 

func (self *PdfMaroto) GetDebugMode() bool

GetDebugMode return the actual debug mode.

Example

ExamplePdfMaroto_GetDebugMode demonstrates how to obtain the actual debug mode value 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)

	// false
	m.GetDebugMode()

	m.SetDebugMode(true)

	// true
	m.GetDebugMode()

	// Do more things and save...
}

Output:

func (*PdfMaroto) GetPageSize 

func (self *PdfMaroto) GetPageSize() (float64, float64)

GetPageSize return the actual page size

func (*PdfMaroto) Line 

func (self *PdfMaroto) Line(spaceHeight float64)

Line draw a line from margin left to margin right in the currently row.

Example

ExamplePdfMaroto_Line demonstrates how to draw a line separator. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)

	m.Line(1.0)

	// Do more things and save...
}

Output:

func (*PdfMaroto) Output 

func (self *PdfMaroto) Output() (bytes.Buffer, error)

Output extract PDF in byte slices

Example

ExamplePdfMaroto_Output demonstrates how to get a base64 string from PDF 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)

	// Do a lot of things on rows and columns...

	_, err := m.Output()
	if err != nil {
		return
	}
}

Output:

func (*PdfMaroto) OutputFileAndClose 

func (self *PdfMaroto) OutputFileAndClose(filePathName string) (err error)

OutputFileAndClose save pdf in disk.

Example

ExamplePdfMaroto_OutputFileAndClose demonstrates how to save a PDF in disk. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)

	// Do a lot of things on rows and columns...

	err := m.OutputFileAndClose("path/file.pdf")
	if err != nil {
		return
	}
}

Output:

func (*PdfMaroto) QrCode 

func (self *PdfMaroto) QrCode(code string, prop *RectProp)

QrCode create a qrcode inside a cell.

func (*PdfMaroto) RegisterHeader added in v0.12.0 

func (self *PdfMaroto) RegisterHeader(closure func())

RegisterHeader define a sequence of Rows, Lines ou TableLists which will be added in every new page

func (*PdfMaroto) Row 

func (self *PdfMaroto) Row(height float64, closure func())

Row define a row and enable add columns inside the row.

Example

ExamplePdfMaroto_Row demonstrates how to define a row. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		// ... Add some columns
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) SetDebugMode 

func (self *PdfMaroto) SetDebugMode(on bool)

SetDebugMode enable debug mode. Draw borders in all columns created.

Example

ExamplePdfMaroto_SetDebugMode demonstrates how to define debug mode 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	m.SetDebugMode(true)

	// Add some Rows, Cols, Lines and etc...
	// Here will be drawn borders in every cell

	m.SetDebugMode(false)

	// Add some Rows, Cols, Lines and etc...
	// Here will not be drawn borders

	// Do more things and save...
}

Output:

func (*PdfMaroto) Signature 

func (self *PdfMaroto) Signature(label string, prop *SignatureProp)

Signature add a space for a signature inside a cell, the space will have a line and a text below

Example

ExamplePdfMaroto_Signature demonstrates how to add a Signature space inside a col. Passing nil on signatureProp make the method use: arial Font, normal style and size 10.0. Not passing family, make method use arial. Not passing style, make method use normal. Not passing size, make method use 10.0. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		m.Col(func() {
			m.Signature("LabelForSignature", &maroto.SignatureProp{
				Size:   12.0,
				Style:  maroto.BoldItalic,
				Family: maroto.Courier,
			})
		})
	})

	// Do more things and save...
}

Output:

func (*PdfMaroto) TableList added in v0.11.0 

func (self *PdfMaroto) TableList(header []string, contents [][]string, prop *TableListProp)

TableList create a table with multiple rows and columns. Headers define the amount of columns from each row. Headers have bold style, and localized at the top of table. Contents are array of arrays. Each array is one line.

Example

ExamplePdfMaroto_TableList demonstrates how to add a table with multiple rows and columns 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)

	headers := []string{"Header1", "Header2"}
	contents := [][]string{
		{"Content1", "Content2"},
		{"Content3", "Content3"},
	}

	// 1 Row of header
	// 2 Rows of contents
	// Each row have 2 columns
	m.TableList(headers, contents, nil)

	// Do more things and save...
}

Output:

func (*PdfMaroto) Text 

func (self *PdfMaroto) Text(text string, prop *TextProp)

Text create a text inside a cell.

Example

ExamplePdfMaroto_Text demonstrates how to add a Text inside a col. Passing nil on fontProp make the method use: arial Font, normal style, size 10.0 and align left. Not passing family, make method use arial. Not passing style, make method use normal. Not passing size, make method use 10.0. Not passing align, make method use left. 

package main

import (
	"github.com/johnfercher/maroto"
)

func main() {
	m := maroto.NewMaroto(maroto.Portrait, maroto.A4)
	rowHeight := 5.0

	m.Row(rowHeight, func() {
		m.Col(func() {
			m.Text("TextContent", &maroto.TextProp{
				Size:   12.0,
				Style:  maroto.BoldItalic,
				Family: maroto.Courier,
				Align:  maroto.Center,
				Top:    1.0,
			})
		})
	})

	// Do more things and save...
}

Output:

type RectProp 

type RectProp struct {
	Left    float64
	Top     float64
	Percent float64
	Center  bool
}

RectProp represents properties from a rectangle (Image, QrCode or Barcode) inside a cell

func (*RectProp) MakeValid 

func (r *RectProp) MakeValid()

MakeValid from RectProp means will make the properties from a rectangle reliable to fit inside a cell and define default values for a rectangle

type Signature 

type Signature interface {
	AddSpaceFor(label string, fontFamily Family, fontStyle Style, fontSize float64, qtdCols float64, marginTop float64, actualCol float64)
}

Signature is the abstraction which deals of how to add a signature space inside PDF

func NewSignature 

func NewSignature(pdf gofpdf.Pdf, math Math, text Text) Signature

NewSignature create a Signature

type SignatureProp 

type SignatureProp struct {
	Family Family
	Style  Style
	Size   float64
}

SignatureProp represents properties from a Signature inside a cell

func (*SignatureProp) MakeValid 

func (f *SignatureProp) MakeValid()

MakeValid from SignatureProp define default values for a Signature

type Style 

type Style string

Style is a representation of a style Font 

const (
	// Normal represents a normal style
	Normal Style = ""
	// Bold represents a bold style
	Bold Style = "B"
	// Italic represents a italic style
	Italic Style = "I"
	// BoldItalic represents a bold and italic style
	BoldItalic Style = "BI"
)

type TableListProp added in v0.10.0 

type TableListProp struct {
	HFontSize   float64
	HFontFamily Family
	HFontStyle  Style
	Align       Align
	HHeight     float64
	Space       float64
	CFontSize   float64
	CFontFamily Family
	CFontStyle  Style
	CHeight     float64
}

TableListProp represents properties from a TableList

func (*TableListProp) MakeValid added in v0.10.0 

func (t *TableListProp) MakeValid()

MakeValid from TableListProp define default values for a TableList

type Text 

type Text interface {
	Add(text string, fontFamily Family, fontStyle Style, fontSize float64, marginTop float64, align Align, actualCol float64, qtdCols float64)
}

Text is the abstraction which deals of how to add text inside PDF

func NewText 

func NewText(pdf gofpdf.Pdf, math Math, font Font) Text

NewText create a Text

type TextProp 

type TextProp struct {
	Top    float64
	Family Family
	Style  Style
	Size   float64
	Align  Align
}

TextProp represents properties from a Text inside a cell

func (*TextProp) MakeValid 

func (f *TextProp) MakeValid()

MakeValid from TextProp define default values for a Text

Source Files

View all Source files

Directories

Path Synopsis

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.