Thinreports Generator

A Ruby library for Thinreports.

Prerequisites

Supported Versions

• Ruby 3.3, 3.4, 4.0
• Prawn 2.5

Installation

Add this line to your application's Gemfile:

gem'thinreports'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install thinreports

Getting Started

First of all, check out the README for an overview of Thinreports, its features, the two template formats available, and a complete example with template files and Ruby code.

Usage

See the README for usage of the Section Format.

Basic Format

The template file (.tlf) must be created in the Thinreports Basic Editor.

require'thinreports'report=Thinreports::Report.newlayout: 'report.tlf'report.start_new_pagedoitem(:title).value('Thinreports')endreport.start_new_pagedo |page|
# Item Finderpage.item(:item_id)# => Item objectpage[:item_id]# => Item object# Text blockpage.item(:text_block).value('Pure Ruby')page.item(:text_block).value='Pure Ruby'page[:text_block]='Pure Ruby'page.item('text_block').set('value',color: '#0000ff')page.item(:text_block).format_enabled(false)# Image blockpage.item(:image_block).src('/path/to/image.png')page.item(:image_block).src='/path/to/image.png'page[:image_block]='/path/to/image.png'require'open-uri'page.item(:image_block).src(open('http://www.thinreports.org/assets/logos/thinreports-logo.png'))# Attributespage.item(:any).hidepage.item(:any).showpage.item(:any).visible(true)page.item(:any).visible?# => truepage.item(:any).id# => "any"# Stylespage.item(:text).style(:color,'red')page.item(:text).style(:bold,true)page.item(:text).style(:italic,true)page.item(:text).style(:linethrough,true)page.item(:text).style(:underline,true)page.item(:text).style(:font_size,20)page.item(:text).style(:align,:leftor:centeror:right)page.item(:text).style(:valign,:topor:centeror:bottom)page.item(:rectangle).style(:border_color,'#ff0000').style(:border_width,1).style(:fill_color,'#ffffff')# Bulk setting of stylespage.item(:text).styles(color: '#00000',align: :right)# Bulk setting of valuespage.valuestext_block_a: 'value',text_block_b: 'value'# Helperspage.item_exists?(:existing_id)# => truepage.item_exists?('existing_id')# => truepage.item_exists?(:unknown_id)# => falseendreport.generate(filename: 'report.pdf')

Thinreports::Report.generate(filename: 'report.pdf',layout: 'report.tlf')do |report|
report.start_new_pagedo |page|
# :endend

Report and Page

report=Thinreports::Report.newlayout: 'foo.tlf'3.times{report.start_new_page}# Returns all pagesreport.pages# => [<Report::Page>, <Report::Page>, <Report::Page>]# Returns number of pagesreport.page_count# => 3# Add a blank pagereport.add_blank_pagereport.pages.last# => Report::BlankPage

Using multiple layouts

report=Thinreports::Report.newreport.use_layout'/path/to/default.tlf',default: truereport.use_layout'/path/to/other1.tlf',id: :otherreport.start_new_pagedo |page|
# use '/path/to/default.tlf' layoutendreport.start_new_pagelayout: :otherdo |page|
# use '/path/to/other1.tlf' layoutendreport.start_new_pagelayout: '/path/to/other2.tlf'do |page|
# use '/path/to/other2.tlf' layoutend

Callbacks

report=Thinreports::Report.newlayout: 'foo.tlf'# It will be called before finalizing each pagereport.on_page_createdo |page|
page.item(:text).value('Text for all pages')end

See also basic_report/features/report_callbacks.

List

report=Thinreports::Report.newlayout: 'list.tlf'report.list.headerdo |header|
header.item(:text_block).value('Title')end10.timesdo |n|
report.list.add_rowdo |row|
row.item(:text_block).value(n)endendreport.generate(filename: 'list.pdf')

report=Thinreports::Report.newlayout: 'list_with_footer.tlf'report.listdo |list|
total_price=0price_per_page=0list.on_page_finalizedototal_price += price_per_pageprice_per_page=0endlist.on_page_footer_insertdo |footer|
footer.valuesprice: price_per_pageendlist.on_footer_insertdo |footer|
footer.item(:price).value(total_price)end[100,200,300].eachdo |price|
list.add_rowdo |row|
row[:price]=priceendprice_per_page += priceendend

See also basic_report/features/list_events.

Page Number

# Setting starting number of pagereport.start_page_number_from5# Setting whether to count new pagereport.start_new_pagecount: true# defaultreport.start_new_pagecount: false# Change stylesreport.start_new_pagedo |page|
page.item(:pageno).hidepage.item(:pageno).showpage.item(:pageno).visible(false)page.item(:pageno).styles(color: 'red',bold: true)end

See also basic_report/features/page_number and basic_report/features/page_number_with_list.

Configuring fallback fonts

Thinreports.configuredo |config|
config.fallback_fonts='/path/to/fallback.ttf'endThinreports.config.fallback_fonts=['/path/to/font_a.ttf','/path/to/font_b.ttf']

See also basic_report/features/eudc.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thinreports/thinreports-generator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Development

Feature test requires diff-pdf command

In order to run feature test, you need to install diff-pdf in your environment, or you can run test in the docker container as below.

How to develop in Docker container

You can use the Docker container for development. This container contains the libraries required for testing, such as diff-pdf.

$ docker pull ghcr.io/hidakatsuya/ruby-with-diff-pdf:latest
$ docker run -v $PWD:/src:cached -it ghcr.io/hidakatsuya/ruby-with-diff-pdf bash
> /src#

You can run test:

> /src# bundle install
> /src# bundle exec rake test

Releasing Generator

1. Update the version number in version.rb
2. Update CHANGELOG.md and README.md (if needed)
3. Create the Release PR like #105
4. Merge the PR
5. Is the main CI green? If not, make it green
6. Run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org

License

The gem is available as open source under the terms of the MIT License.

Copyright

(c) 2021 Matsukei Co.,Ltd.