docs

README

Maroto V2

Marotov2.0.0-alpha.34is here! Try out:

• Installation withgo get:

go get github.com/johnfercher/maroto/v2/pkg@v2.0.0-alpha.34

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 HTML/JSON; (on roadmap)

Migration

1. We will no longer maintain the current versionv1.0.0of maroto.
   • The last versionv0.43.0was release asv1.0.0through the main branch, marking the end of the old version.
   • We will clearly communicate this transition in the README.md.
2. We started a new branch for versionv2.0.0.
   • Alpha/Beta versions will be released as we achieve small deliverables.
   • Initially, the project will focus on defining a design that enables us to accomplish all objectives. Subsequently, we will begin incorporating all features from the old version, and finally, we will introduce the new features.

Code Example

filename

PDF Generated

	assets/pdf/v2.pdf

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, it will be possible to write unit tests by analyzing the components tree. To facilitate the writing of unit tests, we are in the process of creating 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 pkg. 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.