documatic 0.1.0 → 0.2.0

data/README

@@ -17,11 +17,10 @@ Documatic can be installed via Rubygems.
 
 == Usage
 
-Documatic is a Ruport extension, so it is loaded like this:
+You can load Documatic as a gem when your program is initialised:
 
   require 'rubygems'
-  require 'ruport'
-  require 'ruport/extensions'
+  require 'documatic'
 
 Documatic will then be available as a formatter for your Ruport
 tables, groups and groupings.  Rendering using an OpenDocument text
@@ -43,7 +42,7 @@ tutorials to illustrate how text and spreadsheet rendering works.
 
 == Version
 
-0.1.0, released 02-SEP-2007.
+0.2.0, released 26-APR-2008.
 
 
 == Licence

data/lib/documatic/component.rb

@@ -3,12 +3,10 @@ require 'erb'
 module Documatic
   class Component
     include ERB::Util
-    include Documatic::OpenDocumentText::Helper
-    include Documatic::OpenDocumentSpreadsheet::Helper
-    
+
     attr_accessor :erb
     attr_accessor :erb_text
-    
+
     def initialize(erb_text)
       @erb_text = erb_text
       @erb = ERB.new(erb_text)
@@ -58,15 +56,12 @@ module Documatic
     # <office:automatic-styles> of this component.  This method isn't
     # intended to be called directly by client applications: it is
     # called automatically by Documatic::Template after processing.
-    def merge_partial_styles
-      cache = Documatic::OpenDocumentText::Partial.cache_by_prefix
-      if cache.length > 0
-        styles = self.xml.root.elements['office:automatic-styles']
-        if styles
-          cache.each_value do |partial|
-            partial.styles.each_element do |e|
-              styles << e
-            end
+    def merge_partial_styles(partials)
+      styles = self.xml.root.elements['office:automatic-styles']
+      if styles
+        partials.each do |partial|
+          partial.styles.each_element do |e|
+            styles << e
           end
         end
       end

data/lib/documatic/formatter/open_document.rb

@@ -1,7 +1,8 @@
 require 'fileutils'
 require 'ruport'
 
-module Documatic::Formatter
+module Documatic
+  module Formatter
 
   class OpenDocumentText < Ruport::Formatter
     class << self
@@ -9,21 +10,24 @@ module Documatic::Formatter
     end
 
     self.processor = Documatic::OpenDocumentText::Template
-    renders :odt_template, :for => [ Ruport::Renderer::Table, Ruport::Renderer::Group,
-                                     Ruport::Renderer::Grouping ]
+    renders :odt_template, :for => [ Ruport::Controller::Table,
+                                     Ruport::Controller::Group,
+                                     Ruport::Controller::Grouping ]
     
     def build
       self.class.processor.process_template(:data => data, :options => options)
     end
-    alias_method :build_table_body, :build  # for Ruport::Renderer::Table
-    alias_method :build_group_body, :build  # for Ruport::Renderer::Group
-    alias_method :build_grouping_body, :build # for Ruport::Renderer::Grouping
+    alias_method :build_table_body, :build  # for Ruport::Controller::Table
+    alias_method :build_group_body, :build  # for Ruport::Controller::Group
+    alias_method :build_grouping_body, :build # for Ruport::Controller::Grouping
   end
 
   class OpenDocumentSpreadsheet < OpenDocumentText
     self.processor = Documatic::OpenDocumentSpreadsheet::Template
-    renders :ods_template, :for => [ Ruport::Renderer::Table, Ruport::Renderer::Group,
-                                     Ruport::Renderer::Grouping ]
+    renders :ods_template, :for => [ Ruport::Controller::Table,
+                                     Ruport::Controller::Group,
+                                     Ruport::Controller::Grouping ]
   end    
-  
-end  # module Documatic::Formatter
+
+  end  # module Formatter
+end  # module Documatic

data/lib/documatic/init.rb

@@ -1,4 +1,2 @@
-class RuportDocumaticLoader < GemPlugin::Plugin "/ruport/documatic"
-  require 'documatic'
-  require 'documatic/formatter/open_document'
-end
+require 'documatic'
+

data/lib/documatic/open_document_spreadsheet/component.rb

@@ -0,0 +1,5 @@
+module Documatic::OpenDocumentSpreadsheet
+  class Component < Documatic::Component
+    include Documatic::OpenDocumentSpreadsheet::Helper
+  end
+end

data/lib/documatic/open_document_spreadsheet/template.rb

@@ -26,28 +26,15 @@ module Documatic::OpenDocumentSpreadsheet
     TYPE       = 2
     ERB_CODE   = 3
     ROW_END    = 4
-  
-    class << self
-
-      # Includes the number and text helpers from Rails' ActionPack.
-      # Requires that the Rails gems be installed.
-      def include_rails_helpers
-        require 'action_pack'
-        require 'action_controller'
-        require 'action_view'
-
-        require 'action_view/helpers/number_helper'
-        require 'action_view/helpers/text_helper'
-
-        self.class_eval do
-          include ActionView::Helpers::NumberHelper
-          include ActionView::Helpers::TextHelper
-        end
 
-      end
+    # Abbrevs
+    DSC = Documatic::OpenDocumentSpreadsheet::Component
+    
+    class << self
 
       def process_template(args, &block)
-        if args[:options] && args[:options].template_file && args[:options].output_file
+        if args[:options] && args[:options].template_file &&
+            args[:options].output_file
           output_dir = File.dirname(args[:options].output_file)
           File.directory?(output_dir) || FileUtils.mkdir_p(output_dir)
           FileUtils.cp(args[:options].template_file, args[:options].output_file)
@@ -60,7 +47,8 @@ module Documatic::OpenDocumentSpreadsheet
           end
           template.close
         else
-          raise ArgumentError, 'Need to specify both :template_file and :output_file in options'
+          raise ArgumentError,
+          'Need to specify both :template_file and :output_file in options'
         end
       end
             
@@ -76,14 +64,13 @@ module Documatic::OpenDocumentSpreadsheet
       # Compile this template, if not compiled already.
       self.jar.find_entry('documatic/master') || self.compile
       # Process the main (body) content.
-      @content = Documatic::Component.new( self.jar.read('documatic/master/content.erb') )
+      @content = DSC.new( self.jar.read('documatic/master/content.erb') )
       @content.process(local_assigns)
-      @content.merge_partial_styles
     end
 
     def save
-      # Gather all the styles from the partials, add them to the master's styles.
-      # Put the body into the document.
+      # Gather all the styles from the partials, add them to the
+      # master's styles.  Put the body into the document.
       self.jar.get_output_stream('content.xml') do |f|
         f.write self.content.to_s
       end
@@ -99,7 +86,8 @@ module Documatic::OpenDocumentSpreadsheet
       @content_erb = self.erbify(@content_raw)
 
       # Create 'documatic/master/' in zip file
-      self.jar.find_entry('documatic/master') || self.jar.mkdir('documatic/master')
+      self.jar.find_entry('documatic/master') ||
+      self.jar.mkdir('documatic/master')
       
       self.jar.get_output_stream('documatic/master/content.erb') do |f|
         f.write @content_erb
@@ -109,7 +97,8 @@ module Documatic::OpenDocumentSpreadsheet
 
     protected
 
-    # Change OpenDocument line breaks and tabs in the ERb code to regular characters.
+    # Change OpenDocument line breaks and tabs in the ERb code to
+    # regular characters.
     def unnormalize(code)
       code = code.gsub(/<text:line-break\/>/, "\n")
       code = code.gsub(/<text:tab\/>/, "\t")
@@ -120,7 +109,8 @@ module Documatic::OpenDocumentSpreadsheet
     def erbify(code)
       # First gather all the ERb-related derived styles
       remaining = code
-      styles = {'Ruby_20_Code' => 'Code', 'Ruby_20_Value' => 'Value', 'Ruby_20_Literal' => 'Literal'}
+      styles = {'Ruby_20_Code' => 'Code', 'Ruby_20_Value' => 'Value',
+        'Ruby_20_Literal' => 'Literal'}
       re_styles = /<style:style style:name="([^"]+)" style:parent-style-name="Ruby_20_(Code|Value|Literal)" style:family="table-cell">/
       
       while remaining.length > 0
@@ -147,9 +137,6 @@ module Documatic::OpenDocumentSpreadsheet
       # "?": optional, might not occur every time
       re_erb = /(<table:table-row[^>]*>)?<table:table-cell [^>]*table:style-name="(#{styles.keys.join '|'})"[^>]*><text:p>([^<]*)<\/text:p><\/table:table-cell>(((<table:covered-table-cell[^\/>]*\/>)|(<table:table-cell[^\/>]*\/>))*<\/table:table-row>)?/
 
-      # The text one:
-      # re_erb = /(<table:table-row[^>]*>)?<table:table-cell [^>]+>)?(<text:list-item>)?(<text:p [^>]+>)?(<\/text:span>)?<text:span text:style-name="(#{styles.keys.join '|'})">(([^<]*|<text:line-break\/>|<text:tab\/>)+)<\/text:span>(<text:span [^>]+>)?(<\/text:p>)?(<\/text:list-item>)?(<\/table:table-cell>(<table:covered-table-cell\/>)*<\/table:table-row>)?/
-
       # Then search for all text using those styles
       while remaining.length > 0
 
@@ -215,13 +202,15 @@ module Documatic::OpenDocumentSpreadsheet
     def regularise_styles(content_raw)
       doc = REXML::Document.new(content_raw)
 
-      # Get the default column types from all the sheets (tables) in the workbook
+      # Get the default column types from all the sheets (tables) in
+      # the workbook
       num_tables = doc.root.elements.to_a('//office:body/*/table:table').length
       (1 .. num_tables).to_a.each do |tnum|
         col_types = []
         cols = doc.root.elements.to_a("//table:table[#{tnum}]/table:table-column")
         cols.each do |col|
-          (0 ... (col.attributes['table:number-columns-repeated'] || 1).to_i).to_a.each do
+          (0 ... (col.attributes['table:number-columns-repeated'] ||
+                  1).to_i).to_a.each do
             col_types << col.attributes['table:default-cell-style-name']
           end
         end  # each column
@@ -231,20 +220,24 @@ module Documatic::OpenDocumentSpreadsheet
 
         # Go through each row and process its cells
         (1 .. num_rows).to_a.each do |rnum|
-          # The cells are both <table:table-cell> and <table:covered-table-cell>
+          # The cells are both <table:table-cell> and
+          # <table:covered-table-cell>
           cells = doc.root.elements.to_a(<<-END
 //table:table[#{tnum}]/table:table-row[#{rnum}]/(table:table-cell | table:covered-table-cell)
 END
                                          )
-          # Keep track of the column number, for formatting purposes (c.f. col_types)
+          # Keep track of the column number, for formatting purposes
+          # (c.f. col_types)
           col_num = 0
           cells.each do |cell|
             # Only need to explicitly format the <table:table-cell>s
             if cell.name == 'table-cell'
               cell.attributes['table:style-name'] ||= col_types[col_num]
             end
-            # Advance the column number, based on the columns spanned by the cell
-            col_num += (cell.attributes['table:number-columns-repeated'] || 1).to_i
+            # Advance the column number, based on the columns spanned
+            # by the cell
+            col_num += (cell.attributes['table:number-columns-repeated'] ||
+                        1).to_i
           end
 
         end  # each row
@@ -253,6 +246,5 @@ END
       return doc.to_s
     end
     
-    
   end
 end

data/lib/documatic/open_document_text/component.rb

@@ -0,0 +1,5 @@
+module Documatic::OpenDocumentText
+  class Component < Documatic::Component
+    include Documatic::OpenDocumentText::Helper
+  end
+end

data/lib/documatic/open_document_text/helper.rb

@@ -51,16 +51,31 @@ module Documatic
       # This method will add the provided partial to the
       # Documatic::Partial cache if it hasn't yet been loaded; or if it
       # has been loaded then the existing partial will be re-used.
-      def partial(filename, *assigns)
-        if Documatic::OpenDocumentText::Partial.cache.has_key?(filename)
-          p = Documatic::OpenDocumentText::Partial.cache[filename]
+      def partial(filename, assigns = {})
+        if template.partials.has_key?(filename)
+          p = template.partials[filename]
         else
           p = Documatic::OpenDocumentText::Partial.new(filename)
-          Documatic::OpenDocumentText::Partial.add_partial(filename, p)
+          template.add_partial(filename, p)
         end
-        p.process(*assigns)
+        assigns.merge!(:template => template, :master => master)
+        p.process(assigns)
       end
 
+      # Insert a reference to an image file with the minimal set of options
+      # (:width and :height in centimetres).
+      def image(full_path, opts = {})
+        image_name = template.add_image(full_path)
+        output = '<draw:frame text:anchor-type="as-char" '
+        opts[:width] && output << %Q(svg:width="#{opts[:width]}cm" )
+        opts[:height] && output << %Q(svg:height="#{opts[:height]}cm")
+        output << '>'
+        output << %Q(<draw:image xlink:href="Pictures/#{image_name}" )
+        output <<
+          'xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad"/>'
+        output << '</draw:frame>'
+      end
+      
     end
   end
 end

data/lib/documatic/open_document_text/partial.rb

@@ -36,7 +36,7 @@ module Documatic::OpenDocumentText
 
     def process(local_assigns = {})
       self.jar.find_entry('documatic/partial') || self.compile
-      @content = Documatic::Component.new( self.content_erb )
+      @content = Documatic::OpenDocumentText::Component.new( self.content_erb )
       @content.process(local_assigns)
     end
 
@@ -50,7 +50,8 @@ module Documatic::OpenDocumentText
         attr && style_names[attr.value] = attr
       end
 
-      # Replace all auto styles in the document's attributes with the prefixed form.
+      # Replace all auto styles in the document's attributes with the
+      # prefixed form.
       doc.each_element('//*') do |e|
         e.attributes.each_attribute do |attr|
           if style_names.has_key? attr.value
@@ -60,7 +61,8 @@ module Documatic::OpenDocumentText
       end
 
       # Create 'documatic/partial/' in zip file
-      self.jar.find_entry('documatic/partial') || self.jar.mkdir('documatic/partial')
+      self.jar.find_entry('documatic/partial') ||
+        self.jar.mkdir('documatic/partial')
       
       # Save the prefix in documatic/partial.txt
       self.jar.get_output_stream('documatic/partial/partial.txt') do |f|
@@ -73,18 +75,22 @@ module Documatic::OpenDocumentText
         f.write @styles.to_s
       end
 
-      # Get body text, erbify it, keep it in @content and save it in documatic/content.erb
+      # Get body text, erbify it, keep it in @content and save it in
+      # documatic/content.erb
       body_text = doc.root.elements['office:body/office:text']
       body_text.elements.delete('text:sequence-decls')
       body_text.elements.delete('office:forms')
-      @content_erb = self.erbify( (body_text.elements.to_a.collect do |e| e.to_s ; end ).join("\n") )
+      @content_erb = self.erbify( (body_text.elements.to_a.collect do |e|
+                                     e.to_s ;
+                                   end ).join("\n") )
       self.jar.get_output_stream('documatic/partial/content.erb') do |f|
         f.write @content_erb
       end
 
     end
 
-    # Partials aren't saved in the same way that templates are: this is a no-op.
+    # Partials aren't saved in the same way that templates are: this
+    # is a no-op.
     def save ; end
     
     def prefix
@@ -92,7 +98,8 @@ module Documatic::OpenDocumentText
         if self.jar.find_entry('documatic/partial/partial.txt')
           @prefix = self.jar.read('documatic/partial/partial.txt')
         else
-          @prefix = File.basename(self.filename, '.odt').gsub(/[^A-Za-z0-9_]/, '_')
+          @prefix = File.basename(self.filename, '.odt').gsub(/[^A-Za-z0-9_]/,
+                                                              '_')
         end
       end
       return @prefix

data/lib/documatic/open_document_text/template.rb

@@ -1,4 +1,3 @@
-#require 'rexml/text'
 require 'rexml/document'
 require 'rexml/attribute'
 require 'zip/zip'
@@ -8,9 +7,16 @@ require 'fileutils'
 module Documatic::OpenDocumentText
   class Template
     include ERB::Util
-    
+
+    # The template's content component.  This is an instance of
+    # Documatic::Component, instantiated from the compiled (embedded
+    # Ruby) version of 'content.xml'.
     attr_accessor :content
+    # The template's styles component.  This is an instance of
+    # Documatic::Component, instantiated from the compiled (embedded
+    # Ruby) version of 'styles.xml'.
     attr_accessor :styles
+    # The template's JAR file (i.e. an instance of Zip::ZipFile)
     attr_accessor :jar
     # The raw contents of 'content.xml'.
     attr_accessor :content_raw
@@ -47,33 +53,35 @@ module Documatic::OpenDocumentText
     INLINE_CODE = 3
     VALUE = 4
 
+    # Abbrevs
+    DTC = Documatic::OpenDocumentText::Component
+    
     class << self
-
-      # Includes the number and text helpers from Rails' ActionPack.
-      # Requires that the Rails gems be installed.
-      def include_rails_helpers
-        require 'action_pack'
-        require 'action_controller'
-        require 'action_view'
-
-        require 'action_view/helpers/number_helper'
-        require 'action_view/helpers/text_helper'
-
-        [self, Documatic::OpenDocumentText::Partial].each do |klass|
-          klass.class_eval do
-            include ActionView::Helpers::NumberHelper
-            include ActionView::Helpers::TextHelper
-          end
-        end
-      end
-
+      # Process a template and save it to an output file.
+      #
+      # The argument is a hash with the keys :options and :data.
+      # :options should contain an object that responds to
+      # #template_file and #output_file.  #template_file is the path
+      # and filename to the OpenDocument template to be used;
+      # #output_file is where the processed results will be stored.
+      # The #template_file must exist, and the #output_file path must
+      # either exist or the current process must be able to create it.
+      #
+      # An optional block can be provided to this method.  The block
+      # will be passed the template currently being processed (i.e. an
+      # instance of Documatic::OpenDocumentText::Template).  The block
+      # can peform manipulation of the template directly by
+      # e.g. accessing the template's JAR or the content or styles
+      # components.  The template will be saved after the block exits.
       def process_template(args, &block)
-        if args[:options] && args[:options].template_file && args[:options].output_file
+        if args[:options] && args[:options].template_file &&
+            args[:options].output_file
           output_dir = File.dirname(args[:options].output_file)
           File.directory?(output_dir) || FileUtils.mkdir_p(output_dir)
           FileUtils.cp(args[:options].template_file, args[:options].output_file)
           template = self.new(args[:options].output_file)
-          template.process :data => args[:data], :options => args[:options]
+          template.process :data => args[:data], :options => args[:options],
+          :template => template, :master => template
           template.save
           if block
             block.call(template)
@@ -98,12 +106,23 @@ module Documatic::OpenDocumentText
       self.jar.find_entry('documatic/master') || self.compile
       # Process the styles (incl. headers and footers).
       # This is conditional because partials don't need styles.erb.
-      @styles = Documatic::Component.new( self.jar.read('documatic/master/styles.erb') )
+      @styles = DTC.new(self.jar.read('documatic/master/styles.erb') )
       @styles.process(local_assigns)
       # Process the main (body) content.
-      @content = Documatic::Component.new( self.jar.read('documatic/master/content.erb') )
+      @content = DTC.new( self.jar.read('documatic/master/content.erb') )
       @content.process(local_assigns)
-      @content.merge_partial_styles
+      # Merge styles from any partials into the main template
+      if self.partials.keys.length > 0
+        @content.merge_partial_styles(self.partials.values)
+      end
+      # Copy any images into this jar
+      if images.length > 0
+        self.jar.find_entry('Pictures') || self.jar.mkdir('Pictures')
+        images.keys.each do |filename|
+          path = images.delete(filename)
+          self.jar.add("Pictures/#{filename}", path)
+        end
+      end
     end
 
     def save
@@ -143,7 +162,39 @@ module Documatic::OpenDocumentText
       end
     end
 
+    # Returns a hash of images added during the processing of the
+    # current template.  (This method is not intended to be called
+    # directly by application developers: it is used indirectly by
+    # the #image helper to add images from within an OpenDocument
+    # template.)
+    def images
+      @images ||= Hash.new
+    end        
+    
+    # Add an image to the current template.  The argument is the
+    # path and filename of the image to be added to the template.
+    # This can be an absolute path or a relative path to the current
+    # directory.  Returns the basename of file if it exists;
+    # otherwise an ArgumentError exception is raised.
+    def add_image(full_path)
+      if File.exists?(full_path)
+        image = File.basename(full_path)
+        self.images[image] = full_path
+        return image
+      else
+        raise ArgumentError, 'Attempted to add non-existent image to template'
+      end
+    end
 
+    def partials
+      @partials ||= Hash.new
+    end
+
+    def add_partial(full_path, partial)
+      self.partials[full_path] = partial
+    end
+    
+    
     protected
 
     def pretty_xml(filename)

data/lib/documatic.rb

@@ -1,9 +1,14 @@
+require 'ruport'
+
+require 'documatic/component'
 require 'documatic/open_document_text/helper'
+require 'documatic/open_document_text/component'
 require 'documatic/open_document_text/template'
-require 'documatic/open_document_spreadsheet/template'
-require 'documatic/open_document_spreadsheet/helper'
-require 'documatic/component'
 require 'documatic/open_document_text/partial'
+require 'documatic/open_document_spreadsheet/helper'
+require 'documatic/open_document_spreadsheet/component'
+require 'documatic/open_document_spreadsheet/template'
+require 'documatic/formatter/open_document'
 
 # The module "Documatic" is the namespace for the other modules and
 # classes in this project.  It also contains some convenience methods.
@@ -11,17 +16,30 @@ module Documatic
   class << self
 
     # Short-cut method for including a helper in
-    # Documatic::Component (the ERb processor).
+    # Documatic::OpenDocumentText::Component (the ERb processor).
+    # This is the 'old' method that pre-dates the spreadsheet
+    # component -- that's why it only adds the helper to the text
+    # component.
     def add_helper(helper_module)
-      Documatic::Component.class_eval do
-        include helper_module
-      end
+      Documatic::OpenDocumentText::Component.send(:include, helper_module)
+    end
+
+    # Short-cut method for including a helper in
+    # Documatic::OpenDocumentText::Component.
+    def text_helper(helper_module)
+      add_helper helper_module
+    end
+
+    # Short-cut method for including a helper in
+    # Documatic::OpenDocumentSpreadsheet::Component.
+    def spreadsheet_helper(helper_module)
+      Documatic::OpenDocumentSpreadsheet::Component.send(:include,
+                                                         helper_module)
     end
 
   end  # class << self
 end
 
-
 # Force REXML to use double-quotes (consistent with OOo).
 REXML::Attribute.class_eval do
   def to_string

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0
+rubygems_version: 0.9.4
 specification_version: 1
 name: documatic
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2007-09-02 00:00:00 +10:00
+  version: 0.2.0
+date: 2008-04-26 00:00:00 +10:00
 summary: Documatic is an OpenDocument extension for Ruby Reports (Ruport). It is a template-driven formatter that can be used to produce attractive printable documents such as database reports, invoices, letters, faxes and more.
 require_paths: 
 - lib
@@ -37,9 +37,11 @@ files:
 - lib/documatic/formatter/open_document.rb
 - lib/documatic/init.rb
 - lib/documatic/open_document_spreadsheet/
+- lib/documatic/open_document_spreadsheet/component.rb
 - lib/documatic/open_document_spreadsheet/helper.rb
 - lib/documatic/open_document_spreadsheet/template.rb
 - lib/documatic/open_document_text/
+- lib/documatic/open_document_text/component.rb
 - lib/documatic/open_document_text/helper.rb
 - lib/documatic/open_document_text/partial.rb
 - lib/documatic/open_document_text/template.rb
@@ -69,15 +71,6 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.9.1
     version: 
-- !ruby/object:Gem::Dependency 
-  name: gem_plugin
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Version::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 0.2.2
-    version: 
 - !ruby/object:Gem::Dependency 
   name: ruport
   version_requirement: 
@@ -85,5 +78,5 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.2.0
+        version: 1.6.0
     version: