Thinreports Generator

You can register multiple .tlf layouts within a single Thinreports::Report instance and switch between them when starting new pages.

1. Register layouts using report.use_layout(path, id: :name).
2. Specify the layout when calling report.start_new_page(layout: :id) or by passing a path directly.

report = Thinreports::Report.new

report.use_layout '/path/to/default.tlf', default: true
report.use_layout '/path/to/other1.tlf', id: :other

report.start_new_page do |page|
  # uses '/path/to/default.tlf'
end

report.start_new_page layout: :other do |page|
  # uses '/path/to/other1.tlf'
end

The list API allows you to define headers and iterate through rows, which is ideal for tabular data.

Basic List

• report.list.header: Define the header content.
• report.list.add_row: Add a row of data.

List Events

You can use callbacks to manage data across pages or footers:

• list.on_page_finalize: Called before finalizing each page (useful for calculating page-specific totals).
• list.on_page_footer_insert: Called when inserting a page footer.
• list.on_footer_insert: Called when inserting the final report footer.

report = Thinreports::Report.new layout: 'list.tlf'

report.list.header do |header|
  header.item(:text_block).value('Title')
end

[100, 200, 300].each do |price|
  report.list.add_row do |row|
    row[:price] = price
  end
end

report.generate(filename: 'list.pdf')

To use Thinreports Generator in your Ruby application, add the gem to your Gemfile:

gem 'thinreports'

Then run bundle install, or install it directly via the command line:

$ gem install thinreports

To ensure text renders correctly when specific fonts are missing, you can configure fallback fonts globally.

Thinreports.configure do |config|
  config.fallback_fonts = '/path/to/fallback.ttf'
end

Or via the config object:

Thinreports.config.fallback_fonts = ['/path/to/font_a.ttf', '/path/to/font_b.ttf']

You can control how page numbers are displayed and counted:

• report.start_page_number_from(n): Sets the starting page number.
• report.start_new_page(count: true/false): Determines whether the new page increments the page counter (true is default).
• Styling Page Numbers: Access the page number item (e.g., :pageno) via page.item(:pageno) to apply styles like color or bolding.

report = Thinreports::Report.new layout: 'foo.tlf'

report.start_page_number_from 5

report.start_new_page count: true do |page|
  page.item(:pageno).styles(color: 'red', bold: true)
end

Errors related to visual styling and attributes include:

• UnknownShapeStyleName: The specified style name cannot be used. The error message will list the available styles prefixed with colons (e.g., :style1, :style2).
• UnknownShapeType: An unrecognized shape type was provided.
• UnknownFormatterType: An unrecognized formatter type was provided.
• UnsupportedColorName: The specified color name is not supported.
• DisabledListSection: An attempt was made to access a section that is currently disabled. Error message format: The [section] section is disabled.

When generating reports, you may encounter errors related to missing or incorrectly identified layout components.

• UnknownLayoutId: The specified layout ID does not exist.
• UnknownItemId: The layout does not contain an item of the specified type with the provided ID. Error message format: The layout does not have a [item_type] Item with id '[id]'.
• LayoutFileNotFound: The requested layout file could not be located.
• NoRegisteredLayoutFound: No layout has been registered with the generator.
• InvalidLayoutFormat: The layout file format is invalid.

If the report fails due to resource or version mismatches:

• FontFileNotFound: The required font file could not be located.
• IncompatibleLayoutFormat: The layout file version is incompatible with the current generator version. This occurs when a file was created in a newer version of the Editor than the Generator supports. The error message specifies the filename, the file's version, and the version required by the generator.

You can register custom font files with the PDF generator using the install_font method. This method maps a font name to a specific file path for its normal, bold, italic, and bold_italic styles. Note that this implementation currently maps the same file to all four styles.

Parameters:

• name (String): The name you want to use to refer to this font.
• file (String): The absolute path to the font file.

Returns:

• The installed font name (String).

Raises:

• Errors::FontFileNotFound if the provided file path does not exist.

install_font('MyCustomFont', '/path/to/font.ttf')

The create method is the recommended way to instantiate and build a report using a block. It handles the initialization, block execution, and finalization of the report object automatically.

report = Thinreports::BasicReport::Report::Base.create do |report|
  report.start_new_page do |page|
    # Add content to the page
  end
end

Use exists?(id) or its alias item_exists?(id) to check if a shape with the given ID is defined in the report. Returns true if it exists, false otherwise.

if page.exists?(:text_block)
  # do something
end