README
¶
Maroto ![Travis](https://img.shields.io/badge/coverage-95.5%25-brightgreen.svg)
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
-
Grid System
-
Components To Use Inside a Col
-
Components To Use Outside a Row
-
Components To Wrap Row, TableList and Line
-
Properties: most of the components has properties which you can use to customize appearance and behavior.
-
DebugMode: Used to draw rectangles in every row and column
-
Automatic New Page: New pages are generated automatically when needed.
-
100% Unicode
-
Save: You can save on disk or export to a base64 string
TODO
- RegisterFooter
- Increase Code Coverage
- Create a custom mock with better assertions
Example
Result
Here is the pdf generated.
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 ¶
- type Align
- type Code
- type Extension
- type Family
- type Font
- type Image
- type Maroto
- type Math
- type Orientation
- type PageSize
- type PdfMaroto
- func (self *PdfMaroto) Barcode(code string, prop *RectProp) (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 *SignatureProp)
- func (self *PdfMaroto) TableList(header []string, contents [][]string, prop *TableListProp)
- func (self *PdfMaroto) Text(text string, prop *TextProp)
- type RectProp
- type Signature
- type SignatureProp
- 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 Code ¶
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
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
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
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 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) Base64Image ¶
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.
Output:
func (*PdfMaroto) Col ¶
func (self *PdfMaroto) Col(closure func())
Create a column inside a row and enable to add components inside.
func (*PdfMaroto) ColSpaces ¶
Create some empty columns.
Example ¶
ExamplePdfMaroto_ColSpaces demonstrates how to add some empty columns inside a row.
Output:
func (*PdfMaroto) FileImage ¶
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.
Output:
func (*PdfMaroto) GetDebugMode ¶
Get actual debug mode.
Example ¶
ExamplePdfMaroto_GetDebugMode demonstrates how to obtain the actual debug mode value
Output:
func (*PdfMaroto) GetPageSize ¶
Get actual page size
func (*PdfMaroto) OutputFileAndClose ¶
Save pdf in disk.
func (*PdfMaroto) RegisterHeader ¶ added in v0.12.0
func (self *PdfMaroto) RegisterHeader(closure func())
func (*PdfMaroto) SetDebugMode ¶
Enable debug mode. Draw borders in all columns created.
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.
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
Output:
func (*PdfMaroto) Text ¶
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.
Output:
type Signature ¶
type SignatureProp ¶
Represents Signature properties
func (*SignatureProp) MakeValid ¶
func (f *SignatureProp) MakeValid()
Make Signature properties valid
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()