Thinreports Generator
A Ruby library for Thinreports.
Prerequisites
Supported Versions
- Ruby 3.0, 3.1, 3.2, 3.3
- Prawn 2.4+
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.new layout: 'report.tlf'
report.start_new_page do
item(:title).value('Thinreports')
end
report.start_new_page do |page|
# Item Finder
page.item(:item_id) # => Item object
page[:item_id] # => Item object
# Text block
page.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 block
page.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'))
# Attributes
page.item(:any).hide
page.item(:any).show
page.item(:any).visible(true)
page.item(:any).visible? # => true
page.item(:any).id # => "any"
# Styles
page.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, :left or :center or :right)
page.item(:text).style(:valign, :top or :center or :bottom)
page.item(:rectangle).style(:border_color, '#ff0000')
.style(:border_width, 1)
.style(:fill_color, '#ffffff')
# Bulk setting of styles
page.item(:text).styles(color: '#00000', align: :right)
# Bulk setting of values
page.values text_block_a: 'value', text_block_b: 'value'
# Helpers
page.item_exists?(:existing_id) # => true
page.item_exists?('existing_id') # => true
page.item_exists?(:unknown_id) # => false
end
report.generate(filename: 'report.pdf')
Thinreports::Report.generate(filename: 'report.pdf', layout: 'report.tlf') do |report|
report.start_new_page do |page|
# :
end
end
Report and Page
report = Thinreports::Report.new layout: 'foo.tlf'
3.times { report.start_new_page }
# Returns all pages
report.pages # => [<Report::Page>, <Report::Page>, <Report::Page>]
# Returns number of pages
report.page_count # => 3
# Add a blank page
report.add_blank_page
report.pages.last # => Report::BlankPage
Using multiple layouts
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|
# use '/path/to/default.tlf' layout
end
report.start_new_page layout: :other do |page|
# use '/path/to/other1.tlf' layout
end
report.start_new_page layout: '/path/to/other2.tlf' do |page|
# use '/path/to/other2.tlf' layout
end
Callbacks
report = Thinreports::Report.new layout: 'foo.tlf'
# It will be called before finalizing each page
report.on_page_create do |page|
page.item(:text).value('Text for all pages')
end
See also basic_report/features/report_callbacks.
List
report = Thinreports::Report.new layout: 'list.tlf'
report.list.header do |header|
header.item(:text_block).value('Title')
end
10.times do |n|
report.list.add_row do |row|
row.item(:text_block).value(n)
end
end
report.generate(filename: 'list.pdf')
report = Thinreports::Report.new layout: 'list_with_footer.tlf'
report.list do |list|
total_price = 0
price_per_page = 0
list.on_page_finalize do
total_price += price_per_page
price_per_page = 0
end
list.on_page_footer_insert do |footer|
footer.values price: price_per_page
end
list.on_footer_insert do |footer|
footer.item(:price).value(total_price)
end
[100, 200, 300].each do |price|
list.add_row do |row|
row[:price] = price
end
price_per_page += price
end
end
See also basic_report/features/list_events.
Page Number
# Setting starting number of page
report.start_page_number_from 5
# Setting whether to count new page
report.start_new_page count: true # default
report.start_new_page count: false
# Change styles
report.start_new_page do |page|
page.item(:pageno).hide
page.item(:pageno).show
page.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.configure do |config|
config.fallback_fonts = '/path/to/fallback.ttf'
end
Thinreports.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
- Update the version number in
version.rb
- Update
CHANGELOG.md
andREADME.md
(if needed) - Create the Release PR like #105
- Merge the PR
- Is the main CI green? If not, make it green
- 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.