Parent

Ruport::Renderer

This class implements the core renderer for Ruport's formatting system. It is designed to implement the low level tools necessary to build report renderers for different kinds of tasks. See Renderer::Table for a tabular data renderer.

Public Class Methods

build(*args) click to toggle source

Creates a new instance of the renderer and sets it to use the specified formatter (by name). If a block is given, the renderer instance is yielded.

Returns the renderer instance.

# File lib/ruport/renderer.rb, line 420
def build(*args)
  rend = self.new

  rend.send(:use_formatter,args[0])
  rend.send(:options=, options.dup)
  if rend.class.const_defined? :Helpers
    rend.formatter.extend(rend.class.const_get(:Helpers))
  end
  if args[1].kind_of?(Hash)
    d = args[1].delete(:data)
    rend.data = d if d
    args[1].each {|k,v| rend.options.send("#{k}=",v) }
  end

  yield(rend) if block_given?
  return rend
end
finalize(stage) click to toggle source

Registers a hook to look for in the Formatter object when the render() method is called.

Usage:

 class MyRenderer < Ruport::Renderer
    # other details omitted...
    finalize :apple
 end

 class MyFormatter < Ruport::Formatter
    renders :example, :for => MyRenderer

    # other details omitted... 

    def finalize_apple
       # this method will be called when MyRenderer tries to render
       # the :example format
    end
 end  

If a formatter does not implement this hook, it is simply ignored.
# File lib/ruport/renderer.rb, line 244
def finalize(stage)
  if final_stage
    raise StageAlreadyDefinedError, 'final stage already defined'      
  end
  self.final_stage = stage
end
formats() click to toggle source

Lists the formatters that are currently registered on a renderer, as a hash keyed by format name.

Example:

>> Ruport::Renderer::Table.formats
=> {:html=>Ruport::Formatter::HTML, 
?>  :csv=>Ruport::Formatter::CSV, 
?>  :text=>Ruport::Formatter::Text, 
?>  :pdf=>Ruport::Formatter::PDF}
# File lib/ruport/renderer.rb, line 365
def formats
  @formats ||= {}
end
method_missing(id,*args,&block) click to toggle source

Provides a shortcut to render() to allow render(:csv) to become render_csv

# File lib/ruport/renderer.rb, line 497
def self.method_missing(id,*args,&block)
  id.to_s =~ /^render_(.*)/
  unless args[0].kind_of? Hash
    args = [ (args[1] || {}).merge(:data => args[0]) ]
  end
  $1 ? render($1.to_sym,*args,&block) : super
end
option(*opts) click to toggle source

Defines attribute writers for the Renderer::Options object shared between Renderer and Formatter.

usage:

class MyRenderer < Ruport::Renderer
   option :font_size, :font_style
   # other details omitted
end
# File lib/ruport/renderer.rb, line 323
def option(*opts)       
  opts.each do |opt|                                  
    o = opt 
    unless instance_methods(false).include?(o.to_s)   
      define_method(o) {
         options.send(o.to_s) 
      }     
    end
    opt = "#{opt}="
    define_method(opt) {|t| options.send(opt, t) }
  end
end
options() click to toggle source

Allows you to set class-wide default options.

Example:

options { |o| o.style = :justified }
# File lib/ruport/renderer.rb, line 407
def options
  @options ||= Ruport::Renderer::Options.new
  yield(@options) if block_given?

  return @options
end
prepare(stage) click to toggle source

Registers a hook to look for in the Formatter object when the render() method is called.

Usage:

 class MyRenderer < Ruport::Renderer
    # other details omitted...
    prepare :apple
 end

 class MyFormatter < Ruport::Formatter
    renders :example, :for => MyRenderer

    def prepare_apple
       # this method will be called when MyRenderer tries to render
       # the :example format
    end        

    # other details omitted...
 end  

If a formatter does not implement this hook, it is simply ignored.
# File lib/ruport/renderer.rb, line 273
def prepare(stage)
  if first_stage
    raise StageAlreadyDefinedError, "prepare stage already defined"      
  end 
  self.first_stage = stage
end
render(*args) click to toggle source

Builds up a renderer object, looks up the appropriate formatter, sets the data and options, and then does the following process:

* If the renderer contains a module Helpers, mix it in to the instance.
* If a block is given, yield the Renderer instance.
* If a setup() method is defined on the Renderer, call it.
* If the renderer has defined a run() method, call it. Otherwise,
  include Renderer::AutoRunner (you usually won't need a run() method).
* Call _run_ if it exists (this is provided by default, by AutoRunner).
* If the :file option is set to a file name, appends output to the file.
* Return the results of formatter.output

Note that the only time you will need a run() method is if you can't do what you need to via a helpers module or via setup()

Please see the examples/ directory for custom renderer examples, because this is not nearly as complicated as it sounds in most cases.

# File lib/ruport/renderer.rb, line 386
def render(*args)
  rend = build(*args) { |r|        
      yield(r) if block_given?   
    r.setup if r.respond_to? :setup
  }  
  if rend.respond_to? :run
    rend.run
  else
    include AutoRunner
  end
  rend._run_ if rend.respond_to? :_run_
  rend.formatter.save_output(rend.options.file) if rend.options.file
  return rend.formatter.output
end
required_option(*opts) click to toggle source

Defines attribute writers for the Renderer::Options object shared between Renderer and Formatter. Will throw an error if the user does not provide values for these options upon rendering.

usage:

class MyRenderer < Ruport::Renderer
   required_option :employee_name, :address
   # other details omitted
end
# File lib/ruport/renderer.rb, line 346
def required_option(*opts) 
  self.required_options ||= []
  opts.each do |opt|
    self.required_options << opt 
    option opt
  end
end
stage(*stage_list) click to toggle source

Registers hooks to look for in the Formatter object when the render() method is called.

Usage:

 class MyRenderer < Ruport::Renderer
    # other details omitted...
    stage :apple,:banana
 end

 class MyFormatter < Ruport::Formatter
    renders :example, :for => MyRenderer

    def build_apple
       # this method will be called when MyRenderer tries to render
       # the :example format
    end 

    def build_banana
       # this method will be called when MyRenderer tries to render
       # the :example format
    end    

    # other details omitted...
 end  

If a formatter does not implement these hooks, they are simply ignored.
# File lib/ruport/renderer.rb, line 307
def stage(*stage_list)
  self.stages ||= []
  stage_list.each { |stage|
    self.stages << stage.to_s 
  }
end

Public Instance Methods

data() click to toggle source

The data that has been passed to the active formatter.

# File lib/ruport/renderer.rb, line 462
def data
  formatter.data
end
data=(val) click to toggle source

Sets data attribute on the active formatter.

# File lib/ruport/renderer.rb, line 467
def data=(val)
  formatter.data = val.dup 
end
formatter(&block) click to toggle source

Returns the active formatter.

If a block is given, it is evaluated in the context of the formatter.

# File lib/ruport/renderer.rb, line 489
def formatter(&block)
  @formatter.instance_eval(&block) if block   
  return @formatter
end
io=(obj) click to toggle source

If an IO object is given, Formatter#output will use it instead of the default String. For Ruport's core renderers, we technically can use any object that supports the << method, but it's meant for IO objects such as File or STDOUT

# File lib/ruport/renderer.rb, line 482
def io=(obj)
  options.io=obj    
end
options() click to toggle source

Renderer::Options object which is shared with the current formatter.

# File lib/ruport/renderer.rb, line 472
def options
  yield(formatter.options) if block_given?
  formatter.options
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.