Thinreports Generator

Thinreports is an open source report generating tool for Ruby.

• Thinreports Editor (GUI Designer)
• Thinreports Generator (Report Generator for Ruby)

Getting Started

• Installation Guide
• Quick Start Guide
• Examples
• Changelog
• Discussion Group (GitHub Discussions)
• Discussion Group (Google Groups)

Supported versions

• Ruby 2.5, 2.6, 2.7, 3.0
• Prawn 2.2, 2.3, 2.4
• JRuby 9.2

Quick Reference

NOTE: You need to create a layout file .tlf using Thinreports Editor.

Basic Objects and Basic Usage

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 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 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 features/page_number and 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 features/eudc.

Features

Features of Editor is here.

Easy to generate PDF

Design layout using Editor, then embed values to text field in layout.

Simple runtime environment

Ruby, RubyGems, Prawn and Generator.

Dynamic operation

Generator can dynamically:

• change value of TextBlock and ImageBlock
• change style (border, fill, visibility, position, color, font) of Shape

Others

• External characters (Gaiji) for Japanese

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thinreports/thinreports-generator.

Development

How to run feature tests

$ bundle exec rake test:features

In order to run test:features, 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 build -t thinreports-dev .
$ docker run -v $PWD:/thinreports:cached -it thinreports-dev bash

> /thinreports#

You can run test:

> /thinreports# bundle install
> /thinreports# bundle exec rake test:features

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 master 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

Thinreports Generator is licensed under the MIT-License.

Copyright

© 2010-2015 Matsukei Co.,Ltd.