Object
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.
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
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
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
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
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
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
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
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
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
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
The data that has been passed to the active formatter.
# File lib/ruport/renderer.rb, line 462 def data formatter.data end
Sets data attribute on the active formatter.
# File lib/ruport/renderer.rb, line 467 def data=(val) formatter.data = val.dup end
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
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
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
Generated with the Darkfish Rdoc Generator 2.