docs

README

Maroto V2

News 🆕

1. Github Star

• Please, if you like maroto consider to nominate@johnfercheras a Github star. It's free!
• Link: https://stars.github.com/

2. Discussion Opened:Maroto Document Processor 🔥🔥🔥:

• We are about to create a document processor to generate PDFs by interpreting serialized data as: yml, json or html. Please contribute with your ideas in this discussion.

3. Marotov2.1.3is here! Try out:

• Installation withgo get:

go get github.com/johnfercher/maroto/v2@v2.1.3

The public API was completely redesigned with the aim of enhancing the library in various aspects. The main objectives ofv2.0.0are:

1. Improve usability;
2. Allow unit testing;
3. Add built-in metrics;
4. Improve execution time;
5. Allow recursive Row/Col; (on roadmap)
6. Allow generation based on serialized data.

Migration

1. We will no longer maintain the current versionv1.0.0of maroto.
   • The last versionv0.43.0was released asv1.0.0through the main branch, marking the end of the old version.
   • The oldv1code was moved to av1branch.
2. The master branch now keeps thev2code, being the default implementation now.
   • Beta versions will be released as we achieve small deliverables.
   • There still some issues not solved fromv1, butv2already solved more than 20 issues fromv1.

Code Example

This is part of the simplest example.

filename

PDF Example

This is part of the billing example.

	assets/pdf/billingv2.pdf

Maroto Columns and Rows

Maroto employs a flexible grid system to structure content in a PDF document, consisting of rows and columns. This system is designed to provide both simplicity and versatility in layout management.

Columns

• Grid System: Maroto's layout is based on a 12-unit grid system. This means the width of each page is effectively divided into 12 equal parts (or "grid spaces").
• Column Width: When creating a column (using col.New(colSize)), the colSize parameter specifies how many of these 12 grid spaces the column should occupy. For example, col.New(1) creates a column that spans 1/12 of the page width, while col.New(6) spans half the page width.
• Content Placement: Columns are the primary containers for content such as text, images, and other components. The width of a column determines how much horizontal space its content occupies.
• Total Width Constraint: The sum of the widths of all columns within a single row should not exceed 12 grid spaces, aligning with the full width of the page.
• Grid Space Customization: Is possible to customize the max grid sum.

Rows

• Vertical Structuring: Rows in Maroto are used to organize content vertically. Each row acts as a horizontal container for columns.
• Row Height: The height of a row is defined when it is created (e.g., row.New(20)). This height determines the vertical space allocated for the row. Unlike columns, row height is not based on a grid system but is a relative unit of mm.
• Sequential Layout: Rows are added to the document in the order they are defined, creating a top-to-bottom flow of content. Each new row is placed immediately below the preceding row.
• Layout Flexibility: Rows offer flexibility in the layout design, allowing for various configurations of columns within them. From single full-width columns to multiple columns of different widths, rows accommodate diverse layout patterns.

Conventions

The way that marotov2works is similar to the old version. The concept of components still exists, but now they are more rigorously controlled by maroto, meaning thatv2will be less tightly integrated with gofpdf. This constraint will enable marotov2to utilize other PDF providers, such as pdfcpu, in the future and even to generate other types of documents.

!> gofpdf has been archived by the owner on Nov 13, 2021.

Structure

In marotov2, everything is a component. When you add a row to the document, you are essentially adding a component. Similarly, when you add an image to a col, you are also introducing a component. The functioning of marotov2is straightforward: it involves constructing a components tree and processing the tree by incorporating the components into the document.

Components tree

Runtime

Marotov2now features a distinct separation into two runtime phases: Declaration Phase and Generation Phase.

1. Declaration Phase: During this phase, you will create the maroto instance, add various elements such as pages, rows, cols, images, and so on.
   • When calling the add methods, maroto will not make any changes to the document. Instead, it will solely construct the components tree.
2. Generation Phase: This phase is triggered when the Generate() (Document, error) method is called.
   • In this phase, maroto will traverse the components tree structure, compute the grid dimensions, and add components to the document.

Improve Usability

The recursive design of marotov1has proven to be a limiting factor in enhancing project features. This issue was identified years ago. To enhance code quality and streamline the addition of new features, a refactor of the maroto interface is necessary. This involves extracting interfaces for each feature within maroto, such as (Row, Col, Text, QRCode, Image, etc). With the new interfaces, usability will be greatly improved, enabling maroto to reach a whole new level in this fresh new step.

New Interfaces

filename

Unit Testing

In marotov2, is be possible to write unit tests by analyzing the components tree. To facilitate the writing of unit tests, we created a dedicated test package.

For an example, refer to this link.

Built-in Metrics

This new version of maroto introduces an optional decorator that provides metrics for nearly all operations performed by the library. When the decorator is enabled, maroto will populate the report struct within the document response.

The report struct contains the following information. For a complete example, refer to this link.

filename

Execution Time Improvement

In Marotov2, numerous performance enhancements have been implemented. The core algorithm is now at least twice as fast as V1. This disparity becomes even more remarkable when parallel generation is enabled. The subsequent results were achieved by generating a PDF with 100 pages encompassing all components supported by Marotov2.

filename

The PDF generated was a custom version of (billing example), with 100 pages. The pages are merged using pdfcpu. For a complete example, please refer to this link.

Documentation

Overview

Package docs is the documentation of maroto lib. Maroto is a package which provide a simple way to generate PDF documents. The project 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

- DataMatrix codes

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

Later, to receive updates, run

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

Quick Start

The following Go Code generates a simple PDF file.

    m := pdf.NewMaroto(consts.Portrait, consts.Letter)

    m.Row(10, func() {
		m.Col(12, func() {
			m.Text(props.Text{
				Size: 18,
				Style: consts.Bold,
				Align: consts.Center,
				Top: 9,
			})
		})
	})

	m.OutputFileAndClose("pkg.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 MIT License.

Acknowledgments

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

Roadmap

- Improve test coverage as reported by the coverage tool.