Summary

We have implemented the section-report format proposed at the Issue: New Report Type: SectionReport, and created pull requests for the generator and the editor respectively.

• Add a support for the section-report format thinreports-generator#106
• Add a new editor for the sectoin-report format thinreports-basic-editor#87

We are actually using this implementation in our products and would like to provide this to the Thinreports community.

However, our current implementation is incomplete and still have some issues to discuss. We would like to discuss how to solve those issues, how to proceed with the development, and work with the community towards the release of the section-report format.

Specification

The specifications of our section report implementation is based on the Issue: New Report Type: SectionReport.

Issues

However, the current implementation contains specifications that differ from the Issue: New Report Type: SectionReport, features that we added independently, and specifications that we have not been implemented. There are also some known issues. See the Implementation Status section of each pull request for details.

Examples

We have created some examples of the section-report format features as feature tests for the generator. Each example includes a description of the specifications, a Ruby code, a template file, and an output PDF file.

• Basic Usage: a concept and basic usages of the section report format
• Multiple Groups: specifications of a groups parameter
• Section Auto Stretch: auto strech specifications of sections
• Section Bottom Margin: bottom margin specifications of sections
• Section Parameters: parameter specifications of sections
• Item Follow Stretch: specifications of how the containing item is stretched by sections or stack-view-rows
• Item Parameters: parameter specifications of items (rectangles etc.)
• StackView: specifications of the stack-view tool, which we added independently
• StackViewRow Auto Stretch: auto stretch specifications of stack-view-rows (same as sections)
• StackViewRow Bottom Margin: bottom margin specifications of stack-view-rows (same as sections)
• StackViewRow Parameters: parameter specifications of stack-view-rows
• StackView with Floating Item: how to place items outside of stack-view-rows and its specifications
• Nonexistent Id: specifications when a non-existent section or item is specified as a parameter
• TextBlock Vertical Align: vertical alignment specifications when a text-block has a overflow: expand attribute

Note

Our blog post about the section-report format may be helpful:

• https://tech.misoca.jp/entry/2020/06/30/143359 (In Japanese)
• https://tech.misoca.jp/entry/2020/10/13/120500 (In Japanese)

Getting Started

Installing

See the Getting Started section of each pull request.

Hello World

First, create a template.

This is a simple template which has a detail section whose ID is hello_world. The detail section includes a text-block whose ID is text.

Create a dirctory named hello_world in an arbitrary location, and save the template as template.tlf in the hello_world directory.

Then, create generate.rb in the hello_world directory, and write the following code:

require 'thinreports'

report_params = {
  type: :section,
  layout_file: 'template.tlf',
  params: {
    groups: [
      {
        details: [
          {
            id: 'hello_world',
            items: {
              text: 'Hello World'
            }
          },
          {
            id: 'hello_world',
            items: {
              text: 'Hello Thinreports'
            }
          }
        ]
      }
    ]
  }
}

Thinreports.generate(report_params, filename: 'hello.pdf')

Execute this, and hello.pdf is generated in the hello_world directory.

$ cd /path/to/hello_world
$ ruby generate.rb

hello.pdf:

Future Development

There are still some issues and unimplemented specifications left. But the section-report format is a huge specification and it would be difficult to complete this on our own. Not only are there insufficient development resources, but there is also a need for discussion to make the specifications optimal for Thinreports.

Based on our implementation, we would like to discuss and develop it gradually with the community.

Specifically, we propose the following development approach:

1. Merge the current code into the master branch basically as it is.
2. In issues, discuss and determine specifications and architectures that need to be discussed.
3. Document the specifications as needed.
4. Create tasks as issues based on the determined specifications.
5. Develop based on the tasks.

In order for many developers to participate, we need a foundation such as the specifications and the tasks. It may take some time to put it in place, but we think it is necessary for sustainable development.

It's also a good idea to create small tasks and use labels like good for first issue to make it easier for new developers to join, and use the GitHub Project to clarify the roadmap and development status.