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 ¶
- type Align
- type BarcodeProp
- type Code
- type Extension
- type Family
- type Font
- type FontProp
- type Image
- type Maroto
- type Math
- type Orientation
- type PageSize
- type PdfMaroto
- func (self *PdfMaroto) Barcode(code string, prop ...BarcodeProp) (err error)
- func (self *PdfMaroto) Base64Image(base64 string, extension Extension, prop ...RectProp)
- func (self *PdfMaroto) Col(closure func())
- func (self *PdfMaroto) ColSpace()
- func (self *PdfMaroto) ColSpaces(qtd int)
- func (self *PdfMaroto) FileImage(filePathName string, prop ...RectProp)
- func (self *PdfMaroto) GetDebugMode() bool
- func (self *PdfMaroto) GetPageSize() (float64, float64)
- func (self *PdfMaroto) Line(spaceHeight float64)
- func (self *PdfMaroto) Output() (bytes.Buffer, error)
- func (self *PdfMaroto) OutputFileAndClose(filePathName string) (err error)
- func (self *PdfMaroto) QrCode(code string, prop ...RectProp)
- func (self *PdfMaroto) RegisterHeader(closure func())
- func (self *PdfMaroto) Row(height float64, closure func())
- func (self *PdfMaroto) SetDebugMode(on bool)
- func (self *PdfMaroto) Signature(label string, prop ...FontProp)
- func (self *PdfMaroto) TableList(header []string, contents [][]string, prop ...TableListProp)
- func (self *PdfMaroto) Text(text string, prop ...TextProp)
- type Proportion
- type RectProp
- type Signature
- type Style
- type TableListProp
- type Text
- type TextProp
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 BarcodeProp ¶ added in v0.13.1
type BarcodeProp struct { // Left is the space between the left cell boundary to the barcode, if center is false Left float64 // Top is space between the upper cell limit to the barcode, if center is false Top float64 // Percent is how much the barcode will occupy the cell, // ex 100%: The barcode will fulfill the entire cell // ex 50%: The greater side from the barcode will have half the size of the cell Percent float64 // Proportion is the proportion between size of the barcode // Ex: 16x9, 4x3... Proportion Proportion // Center define that the barcode will be vertically and horizontally centralized Center bool }
BarcodeProp represents properties from a barcode inside a cell
func (*BarcodeProp) MakeValid ¶ added in v0.13.1
func (r *BarcodeProp) MakeValid()
MakeValid from BarcodeProp means will make the properties from a barcode reliable to fit inside a cell and define default values for a barcode
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, rectPercent float64, heightPercentFromWidth float64) (err error) }
Code is the abstraction which deals of how to add QrCodes or Barcode in a PDF
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
type FontProp ¶ added in v0.13.1
type FontProp struct { // Family of the text, ex: Arial, helvetica and etc Family Family // Style of the text, ex: Normal, bold and etc Style Style // Size of the text Size float64 }
FontProp represents properties from a text
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
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 ...BarcodeProp) error QrCode(code string, prop ...RectProp) Signature(label string, prop ...FontProp) // 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
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 ...BarcodeProp) (err error)
Barcode create an barcode inside a cell.
func (*PdfMaroto) Base64Image ¶
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 barcodeProp 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 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 ¶
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 ¶
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 barcodeProp 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 ¶
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 ¶
GetPageSize return the actual page size
func (*PdfMaroto) Line ¶
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 ¶
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 ¶
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) 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 ¶
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 ¶
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 ¶
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.FontProp{ 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) // Do more things and save... }
Output:
func (*PdfMaroto) Text ¶
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 Proportion ¶ added in v0.13.1
type Proportion struct { // Width from the rectangle: Barcode, image and etc Width float64 // Height from the rectangle: Barcode, image and etc Height float64 }
Proportion represents a proportion from a rectangle, example: 16x9, 4x3...
type RectProp ¶
type RectProp struct { // Left is the space between the left cell boundary to the rectangle, if center is false Left float64 // Top is space between the upper cell limit to the barcode, if center is false Top float64 // Percent is how much the rectangle will occupy the cell, // ex 100%: The rectangle will fulfill the entire cell // ex 50%: The greater side from the rectangle will have half the size of the cell Percent float64 // Center define that the barcode will be vertically and horizontally centralized Center bool }
RectProp represents properties from a rectangle (Image, QrCode or Barcode) inside a cell
type Signature ¶
type Signature interface {
AddSpaceFor(label string, textProp TextProp, qtdCols float64, marginTop float64, actualCol float64)
}
Signature is the abstraction which deals of how to add a signature space inside PDF
type TableListProp ¶ added in v0.10.0
type TableListProp struct { // HeaderHeight is the height of the cell with headers HeaderHeight float64 // HeaderProp is the custom properties of the text inside // the headers HeaderProp FontProp // ContentHeight is the height of the cells with contents ContentHeight float64 // ContentProp is the custom properties of the text inside // the contents ContentProp FontProp // Align is the align of the text (header and content) inside the columns Align Align // HeaderContentSpace is the space between the header and the contents HeaderContentSpace 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 TextProp, marginTop float64, actualCol float64, qtdCols float64)
}
Text is the abstraction which deals of how to add text inside PDF
type TextProp ¶
type TextProp struct { // Top is space between the upper cell limit to the barcode, if align is not center Top float64 // Family of the text, ex: Arial, helvetica and etc Family Family // Style of the text, ex: Normal, bold and etc Style Style // Size of the text Size float64 // Align of the text Align Align // Extrapolate define if the text will automatically add a new line when // text reach the right cell boundary Extrapolate bool }
TextProp represents properties from a Text inside a cell