Cheatsheet: rope (A Code Generation Tool for Ruby Reports)

Overview

The rope tool comprises a number of simple utilities that script away much of your boilerplate code, and also provide useful tools for development.

If you’re looking for something to help keep your project organized and help cut down on typing, you may find this tool helpful.

Starting a New rope Project


$ rope labyrinth
creating directories..
  labyrinth/test
  labyrinth/config
  labyrinth/output
  labyrinth/data
  labyrinth/data/models
  labyrinth/lib
  labyrinth/lib/reports
  labyrinth/lib/controllers
  labyrinth/sql
  labyrinth/util
creating files..
  labyrinth/lib/reports.rb
  labyrinth/lib/helpers.rb
  labyrinth/lib/controllers.rb
  labyrinth/lib/templates.rb
  labyrinth/lib/init.rb
  labyrinth/config/environment.rb
  labyrinth/util/build
  labyrinth/util/sql_exec
  labyrinth/Rakefile
  labyrinth/README

Successfully generated project: labyrinth

Once this is complete, you’ll have a large number of mostly empty folders laying around, along with some helpful tools at your disposal.

Utilities

Directories

Generating a Report Definition


 $ rake build report=ghosts
 report file: lib/reports/ghosts.rb
 test file: test/test_ghosts.rb
 class name: Ghosts

 $ rake
 (in /home/sandal/labyrinth)
 /usr/bin/ruby -Ilib:test
 "/usr/lib/ruby/gems/1.8/gems/rake-0.7.1/lib/rake/rake_test_loader.rb" 
 "test/test_ghosts.rb" 
 Loaded suite /usr/lib/ruby/gems/1.8/gems/rake-0.7.1/lib/rake/rake_test_loader
 Started
 F
 Finished in 0.001119 seconds.

   1) Failure:
   test_flunk(TestGhosts) [./test/test_ghosts.rb:6]:
   Write your real tests here or in any test/test_* file.

   1 tests, 1 assertions, 1 failures, 0 errors
   rake aborted!
   Command failed with status (1): [/usr/bin/ruby -Ilib:test
   "/usr/lib/ruby/ge...]

   (See full trace by running task with --trace)

You can now edit lib/reports/ghosts.rb as needed and write tests for it in test/test_ghosts.rb without having to hook up any underplumbing.

Project Configuration

Projects generated with rope will automatically make use of the configuration details in config/environment.rb, which can be used to set up database connections, Ruport’s mailer, and other project information.

The default file is shown below.


require "ruport" 

# Uncomment and modify the lines below if you want to use query.rb
#
# Ruport::Query.add_source :default, :user => "root",
#                                    :dsn  => "dbi:mysql:mydb"     

# Uncomment and modify the lines below if you want to use AAR
#  
# require "active_record" 
# require "ruport/acts_as_reportable" 
# ActiveRecord::Base.establish_connection(
#      :adapter  => 'mysql',
#      :host     => 'localhost',
#      :username => 'name',
#      :password => 'password',
#      :database => 'mydb'
# )

You’ll need to tweak this as needed to fit your database configuration needs. If you need to require any third party libraries which are shared across your project, you should do it in this file.

Custom Rendering with rope Generators


  $ rope my_reverser
  $ cd my_reverser
  $ rake build controller=reverser

Edit test/test_reverser.rb to look like the code below:


 require "test/unit" 
 require "lib/controllers/reverser" 

 class TestReverser < Test::Unit::TestCase
   def test_reverser
     assert_equal "baz", Reverser.render_text("zab")
   end
 end

Now edit lib/controllers/reverser.rb to look like this:


 require "lib/init" 

 class Reverser < Ruport::Controller
   stage :reverser
 end

 class ReverserFormatter < Ruport::Formatter

   renders :text, :for => Reverser

   build :reverser do
     output << data.reverse
   end
 end

The tests should pass. You can now generate a quick report using this controller.


$ rake build report=reversed_report

Edit test/test_reversed_report.rb as such:


 require "test/unit" 
 require "lib/reports/reversed_report" 

 class TestReversedReport < Test::Unit::TestCase
   def test_reversed_report
     report = ReversedReport.new
     report.message = "hello" 
     assert_equal "olleh", report.to_text
   end
 end

Edit lib/reports/reversed_report.rb as below and run the tests.


 require "lib/init"  
 require "lib/controllers/reverser" 
 class ReversedReport < Ruport::Report

   renders_with Reverser
   attr_accessor :message

   def renderable_data(format)
     message
   end
 end

ActiveRecord Integration the Lazy Way

Ruport has built in support for acts_as_reportable, which provides ActiveRecord integration with Ruport.

Setup Details

Edit the following code in config/environment.rb (change as needed to match your config information).


  ActiveRecord::Base.establish_connection(
    :adapter  => 'mysql',
    :host     => 'localhost',
    :username => 'name',
    :password => 'password',
    :database => 'mydb'
  )

Generating a Model

Here is an example of generating the model file:


$ util/build model my_model
model file: data/models/my_model.rb             
class name: MyModel

This will create a barebones model that looks like this:


class MyModel < ActiveRecord::Base

  acts_as_reportable

end

The data/models.rb file will require all generated models, but you can of course require specific models in your reports.

Related Resources / Digging Deeper

You’ll want to look at the documentation for Ruport::Report ( See Report cheatsheet.) and possibly acts_as_reportable (See acts_as_reportable cheatsheet.) to make the most out of rope.

Also, if you want to build your own custom rope-based generator, look into Ruport::Generator.

Overview

Generating a Report Definition

Project Configuration

Custom Rendering with rope Generators

ActiveRecord Integration the Lazy Way

Related Resources / Digging Deeper