ODF-REPORT

Gem for generating .odt files by making strings substitution in a previously created .odt file.

---

INSTALL

gem install sandrods-odf-report --source=http://gems.github.com

---

USAGE

Step 1 — the template

First of all, you need to create a .odt file to serve as a template

Templates are normal .odt files with placeholders for Substitutions

There are two kinds of substitutions available: fields and tables

Fields placeholders

It’s just an upcase sentence, surrounded by brackets. It will be replaced for wathever value you supply.

In the folowing example:

report = ODFReport.new("Users/john/my_template.odt") do |r|

  r.add_field :user_name, @user.name
  r.add_field :address, "My new address"
  
end

All occurences of [USER_NAME] found in the file will be replaced by the value of @user.name whereas all [ADDRESS] ’es will contains My new address

It’s as simple as that.

Table placeholders

To use table placeholders, you should create a Table in your document and give it a name. In OpenOffice, it’s just a matter of right-clicking the table you just created, choose Table Properties… and type a name in the Name field.

If the table has two rows, the first one will be treated as a header and left untouched. Otherwise you should use a table with one row only.

As with Field placeholders, just insert a [FIELD_NAME] in each cell and let the magic takes place.

Taking the folowing example:

report = ODFReport.new("Users/john/my_template.odt") do |r|

  r.add_field "USER_NAME", @user.nome
  r.add_field "ADDRESS", @user.address

  r.add_table("TABLE_1", @list_of_itens) do |row, item|
    row["ITEM_ID"] = item.id
    row["DESCRIPTION"] = "==> #{item.description}"
  end

end

and considering you have a table like this in your template

---------------------------------
|  [ITEM_ID]  |  [DESCRIPTION]  |
---------------------------------

* this is my lame attempt to draw a table. 
  you don't suppose to type this. 
  you have to use an actual table. 
  i don't know... just thought I'd mention it ;-)

and a collection @list_of_itens, it will be created one row for each item in the collection, and the replacement will take place accordingly.

Any format applied to the fields in the template will be preserved.

---

Step 2 — generating the document

It’s fairly simple to generate the document. You can use this inside a Rails application or in a standalone script.

Generating a document in a Rails application

In a controller, you can have a code like this:

def print

  @ticket = Ticket.find(params[:id])

  report = ODFReport.new("#{RAILS_ROOT}/app/reports/ticket.odt") do |r|
   
    r.add_field(:id, @ticket.id.to_s)
    r.add_field(:created_by, @ticket.created_by)
    r.add_field(:created_at, @ticket.created_at.strftime("%d/%m/%Y - %H:%M"))
    r.add_field(:type, @ticket.type.name)
    r.add_field(:status, @ticket.status_text)
    r.add_field(:date, Time.now.strftime("%d/%m/%Y - %H:%M"))                  
    r.add_field(:solution, (@ticket.solution || ''))

    r.add_table("OPERATORS", @ticket.operators) do | row, op |
      row["OPERATOR_NAME"] = "#{op.name} (#{op.department.short_name})"
    end
   
    r.add_table("FIELDS", @ticket.fields) do | row, field |
     
      if field.is_a?(String)
        row["FIELD_NAME"] = 'Materials'
        row["FIELD_VALUE"] = field
      else
        row["FIELD_NAME"] = field.name
        row["FIELD_VALUE"] = field.text_value || ''
      end
     
    end

  end

  report_file_name = report.generate

  send_file(report_file_name) 

end

The generate method will, er… generate the document in a temp dir and returns the full path of the generated file, so you can send it back to the user.

That’s all I have to say about that.

Generating a document in a standalone script

It’s just the same as in a Rails app, but you can inform the path where the file will be generated instead of using a temp dir.

report = ODFReport.new("ticket.odt") do |r|

... populates the report ...

end

report.generate("./documents/")

---

REQUIREMENTS

rubyzip: for manipulating the contents of the odt file, since it’s actually a zip file.

---

THE FUTURE

Well, this is my first attempt. This gem was extracted from an actual project we developed internally, to fulfill our specific needs.

That said, I would really appreciate any input you can come up with. Critics, suggestions, bug reports are welcome and will be thoroughly examined.