API reference

Complete reference for all ODF-Report methods.

Report

Report.new(path = nil, io: nil, &block)

Creates a new report. Provide either a file path or an io: string with the template content.

# From file
report = ODFReport::Report.new("template.odt") do |r|
  # define replacements
end

# From string/IO
report = ODFReport::Report.new(io: template_string) do |r|
  # define replacements
end

Report#generate(dest = nil)

Generates the document. If dest is provided, writes to that file path. Otherwise returns the document as a binary string.

# Write to file
report.generate("output.odt")

# Get binary data
data = report.generate

Fields

add_field(name, value = nil, &block)

Replaces all occurrences of [NAME] in the document with the given value.

r.add_field :user_name, "Jane Smith"
r.add_field(:date) { |record| record.created_at.strftime("%Y-%m-%d") }

Parameters:

Texts

add_text(name, value = nil, &block)

Replaces the placeholder paragraph with HTML-formatted ODF content.

r.add_text :description, '<p>A paragraph with <strong>bold</strong> text.</p>'
r.add_text(:notes) { |record| record.html_notes }

Parameters: Same as add_field.

Works like add_field but parses the value as HTML and converts it into ODF paragraphs. Requires the template to define matching character/paragraph styles. See Texts and Supported HTML tags for details.

Tables

add_table(name, collection, opts = {}, &block)

Repeats table rows for each item in the collection.

r.add_table("ITEMS", @items, header: true) do |t|
  t.add_column(:description)
  t.add_column(:price) { |item| format("$%.2f", item.price) }
end

Parameters:

add_column(name, value = nil, &block)

Alias for add_field. Used inside table blocks for readability.

t.add_column(:product_name)
t.add_column(:price) { |item| format("$%.2f", item.price) }

Sections

add_section(name, collection, opts = {}, &block)

Repeats the named section for each item in the collection.

r.add_section("SC_INVOICE", @invoices) do |s|
  s.add_field(:number)
  s.add_table("TB_ITEMS", :items) do |t|
    t.add_column(:description)
  end
end

Parameters:

Inside a section block, you can use add_field, add_text, add_table, add_section, and add_image.

Images

add_image(name, value = nil, &block)

Replaces a named image frame with the specified image file.

r.add_image :logo, "/path/to/logo.png"
r.add_image(:photo) { |record| record.photo_path }

Parameters: