maroto

Maroto is a fast and simple library for creating PDFs in Go, inspired by the Bootstrap grid system. It allows you to build PDF layouts using a hierarchical structure:

• Rows can contain multiple Cols.
• Cols can contain multiple components.
• Pages are automatically added when content exceeds the available area.
• Headers can be defined to appear on every new page, and can consist of rows, lines, or table lists.

It is built on top of Gofpdf.

Maroto v2 operates in two distinct phases:

1. Declaration Phase: You create the Maroto instance and add elements (pages, rows, cols, images, etc.). During this phase, Maroto only constructs a components tree; no changes are made to the actual document.
2. Generation Phase: Triggered by calling the Generate() (Document, error) method. Maroto traverses the components tree, computes grid dimensions, and renders the document.

Maroto V2 uses a grid-based layout system to compose PDF documents.

• Grid Structure: Every page is divided into a fixed number of columns (default is 12) and an unlimited number of rows.
• Composition: Components (such as text, images, barcodes, and lines) are placed inside columns, and columns are grouped into rows.
• Workflow: You initialize a document, add content using row/column methods, and then generate the final PDF.

In Maroto V2, you can enable concurrent PDF generation using WithConcurrentMode(workers). This mode splits the document into chunks and processes them in parallel using the specified number of worker goroutines, then assembles the final output in the correct order.

Key considerations:

• Performance: Concurrent mode provides the most significant speed gains for large documents (50+ pages) or documents with heavy per-row computation.
• Memory: Memory usage scales with the number of workers because each worker holds its chunk in memory simultaneously. This mode has high memory requirements.
• Compatibility: This mode is incompatible with WithSequentialLowMemoryMode. If both are called, the last one called wins.

The Checkbox component renders a square checkbox with an optional label to its right. When Checked is true, an X mark is drawn inside the box. This is useful for forms, questionnaires, and agreements.

To use it, you can use the following constructors:

• New
• NewCol
• NewRow
• NewAutoRow

Note: The label is rendered to the right of the box using the document's default font; font styling is derived from the active core.Font.

The Text component renders a string inside a cell. It supports custom fonts, alignment, colors, hyperlinks, and automatic line breaking. You can use it in three ways:

1. As a standalone Component.
2. Wrapped directly into a Col.
3. Wrapped into a Row (either fixed height or automatic height).

Note on Automatic Height: For long content that needs to expand the row height automatically, use NewAutoRow or NewCol inside AddAutoRow.

To install Maroto V2, use the go get command to fetch the specific version from the repository.

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

In Maroto V2, you can use AddPages to push complete, pre-built page.Page objects into a document. A page.Page acts as a container for rows and is logically isolated from the main document flow.

Key behaviors:

• Rows added to a page that exceed the usable area are automatically split across additional physical pages.
• It allows for explicit pagination control, such as forcing chapters to start on new pages or composing documents from independently generated sections.

In Maroto V2, you can select standard paper sizes using the WithPageSize option. By default, Maroto uses pagesize.A4. You can switch to other ISO or North-American paper sizes by passing a constant from the pagesize package to WithPageSize during builder configuration.

Important Notes:

• WithPageSize and WithDimensions are mutually exclusive; the last one called wins.
• For non-standard dimensions not covered by the pagesize constants, use WithDimensions instead.
• Page orientation is independent. To achieve landscape mode for a specific size, combine WithPageSize with WithOrientation(orientation.Horizontal).

In Maroto V2, you can use WithBackgroundImage to stamp a single image on every page behind all other content. The image is automatically stretched to fill the entire page area. This is useful for creating letterheads, watermarks, or branded templates.

Key details:

• The background is rendered before any rows or columns, ensuring it never obscures your content.
• Supported formats include JPEG and PNG.
• You must provide an Extension (from the github.com/johnfercher/maroto/v2/pkg/consts/extension package) to tell Maroto how to decode the file.
• For best results, combine this with WithOrientation and custom margins to align your template layout correctly.