maroto

package module
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Jun 21, 2019 License: MIT Imports: 7 Imported by: 0

README

Maroto Travis

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.

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

Package Maroto 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

Representation of a column align

const (
	// Represents a left align
	Left Align = "L"
	// Represents a right align
	Right Align = "R"
	// Represents a center align
	Center Align = "C"
	// Represents a top align
	Top Align = "T"
	// Represents a bottom align
	Bottom Align = "B"
	// Represents a middle align
	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)
}

func NewCode

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

type Extension

type Extension string

Representation of a Image extension

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

type Family

type Family string

Representation of a family Font

const (
	// Represents an arial Font
	Arial Family = "arial"
	// Represents a helvetica Font
	Helvetica Family = "helvetica"
	// Represents a symbol Font
	Symbol Family = "symbol"
	// Represents a zapfdingbats Font
	ZapBats Family = "zapfdingbats"
	// 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)
}

Abstraction of Font configuration used in Maroto

func NewFont

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

Create a Font configurator used in Maroto

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)
}

Abstraction of Image adding features used in Maroto

func NewImage

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

Create an Image adding used in Maroto

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

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
}

Abstraction of useful calcs used in Maroto

func NewMath

func NewMath(pdf gofpdf.Pdf) Math

Create a Math instance with useful calcs used in Maroto

type Orientation

type Orientation string

Representation of a page orientation

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

type PageSize

type PageSize string

Representation of an page size

const (
	// Represents DIN/ISO A3 page size
	A3 PageSize = "A3"
	// Represents DIN/ISO A4 page size
	A4 PageSize = "A4"
	// Represents DIN/ISO A5 page size
	A5 PageSize = "A5"
	// Represents US Letter page size
	Letter PageSize = "Letter"
	// 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)

func (*PdfMaroto) Base64Image

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

Add an Image reading byte slices. 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())

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()

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)

Create some empty columns.

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)

Add an Image reading from disk inside a column. Defining Image properties.

Example

ExamplePdfMaroto_FileImage demonstrates how add a Image reading from disk. 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

	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

Get 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)

Get actual page size

func (*PdfMaroto) Line

func (self *PdfMaroto) Line(spaceHeight float64)

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)

Get 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)

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)

func (*PdfMaroto) RegisterHeader added in v0.12.0

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

func (*PdfMaroto) Row

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

Add 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)

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)

Add a Signature space with a label TextHelper inside a column. Create a line with the width from a column and add a Text at the bottom of the line.

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)

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)

Add a Text inside a column.

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
}

Represents rectangle properties

func (*RectProp) MakeValid

func (r *RectProp) MakeValid()

Make rectangle properties valid

type Signature

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

func NewSignature

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

type SignatureProp

type SignatureProp struct {
	Family Family
	Style  Style
	Size   float64
}

Represents Signature properties

func (*SignatureProp) MakeValid

func (f *SignatureProp) MakeValid()

Make Signature properties valid

type Style

type Style string

Representation of a style Font

const (
	// Represents a normal style
	Normal Style = ""
	// Represents a bold style
	Bold Style = "B"
	// Represents a italic style
	Italic Style = "I"
	// 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
}

Represents TableList Properties

func (*TableListProp) MakeValid added in v0.10.0

func (t *TableListProp) MakeValid()

type Text

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

func NewText

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

type TextProp

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

Represents TextHelper properties

func (*TextProp) MakeValid

func (f *TextProp) MakeValid()

Make Text properties valid

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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