clamsy 0.0.2 → 0.0.3

data/HISTORY.txt

@@ -1,3 +1,7 @@
+=== 0.0.3 (Apr 25, 2010)
+
+* support to replace pictures (useful for inserting digital signatures) [#ngty]
+
 === 0.0.2 (Apr 22, 2010)
 
 = 2nd official (yet still as embarrassing) release

data/README.rdoc

@@ -4,56 +4,204 @@ Ruby wrapper for generating a single pdf for multiple contexts from an odt templ
 
   clamsy = clumsy + shellish
             |        |
-            |        |-- under the hood, we are making system calls like ooffice,
-            |            ps2pdf & pdf2ps, etc.
+            |        |-- under the hood, we are making system calls to ooffice &
+            |            cups server needs to be running
             |
-            .-- setup isn't straight forward, need to install a couple of packages
+            |-- setup isn't straight forward, need to install a couple of packages
                 (how bad it is depends on ur platform) & even manual setting up of
-                cups printer is needed
+                cups-pdf printer is needed
 
-== Using It (sorry, still WIP for more decent examples)
+== 1. Basics
 
-#1. Generating single context pdf:
+A template odt is just an ordinary odt (http://en.wikipedia.org/wiki/OpenDocument).
+In order for it to function as a template, we just need to decorate it (just use
+openoffice, pls don't buy ms office for that) with placeholders & embedded ruby code.
+
+Under the hood, clamsy is using a slightly hacked version of the awesome tenjin
+template engine (http://www.kuwata-lab.com/tenjin) to do the rendering. The following
+is all u need to know to write odt templates:
+
+* '{? ... ?}' represents embedded Ruby statement (this differs from vanilla tenjin)
+* '#{ ... }' represents embedded Ruby expression
+* '${ ... }' represents embedded Ruby expression which is to be escaped
+  (eg. '& < > "' are escaped to '&amp; &lt; &gt; &quot;')
+
+== 2. Examples
+
+=== 2.1. Text Replacement Example
+
+Template Odt:
+
+  --------------------------------------------
+   #{@company_full_name}
+   #{@company_address_line_1}
+   #{@company_address_line_2}
+
+   S/N  Item Description       Amount (SGD)
+   {? @items.each_with_index do |item, i| ?}
+   #{i+1} #{item.description}  #{amount}
+   {? end ?}
+                        Total  #{total}
+  ----------------------------------- Page 1 -
+
+Code:
+
+  class Item
+    attr_reader :description, :amount
+    def initialize(description, amount)
+      @description, @amount = description, amount
+    end
+  end
+
+  items = [
+    Item.new('Shells (x2 Bags)', 10),
+    Item.new('Clams (x2 Bags)', 20)
+  ]
+
+  context = {
+    :company_full_name => 'Monster Inc',
+    :company_address_line_1 => 'Planet Mars, Street xyz,',
+    :company_address_line_2 => 'Postal Code 009900',
+    :items => items,
+    :total => items.inject(0) {|sum, item| sum + item.amount }
+  }
+
+  Clamsy.process(
+    context,
+    path_to_template_odt, # eg. '/tmp/invoice.odt'
+    path_to_final_pdf,    # eg. '/tmp/invoice.pdf'
+  )
+
+Generated Pdf:
+
+  --------------------------------------------
+   Monster Inc
+   Planet Mars, Street xyz,
+   Postal Code 009900
+
+   S/N  Item Description       Amount (SGD)
+
+   1    Shells (x2 Bags)       10
+   2    Clams (x2 Bags)        20
+
+                        Total  30
+  ----------------------------------- Page 1 -
+
+=== 2.2: Multiple Contexts Example
+
+Taking the above example one step further, if we have multiple contexts:
+
+  items << Item.new('Shrimps (x2 Bags)', 15)
+  items << Item.new('Prawns (x2 Bags)', 25)
+
+  contexts = [{
+    :company_full_name => 'Monster Inc',
+    :company_address_line_1 => 'Planet Mars, Street xyz,',
+    :company_address_line_2 => 'Postal Code 009900',
+    :items => items[0..1],
+    :total => items[0..1].inject(0) {|sum, item| sum + item.amount }
+  }, {
+    :company_full_name => 'Fisherman Inc',
+    :company_address_line_1 => 'Planet Jupiter, Street xyz,',
+    :company_address_line_2 => 'Postal Code 008800',
+    :items => items[2..3],
+    :total => items[2..3].inject(0) {|sum, item| sum + item.amount }
+  }]
 
   Clamsy.process(
-    {:someone => 'Peter', :mood => 'Happy'},
-    path_to_template_odt,
-    path_to_final_pdf
+    contexts,
+    path_to_template_odt, # eg. '/tmp/invoice.odt'
+    path_to_final_pdf     # eg. '/tmp/invoice.pdf'
   )
 
-#2. Generating multi-contexts pdf:
+Generated Pdf:
+
+  --------------------------------------------
+   Monster Inc
+   Planet Mars, Street xyz,
+   Postal Code 009900
+
+   S/N  Item Description       Amount (SGD)
+
+   1    Shells (x2 Bags)       10
+   2    Clams (x2 Bags)        20
+
+                        Total  30
+  ----------------------------------- Page 1 -
+  --------------------------------------------
+   Fisherman Inc
+   Planet Jupiter, Street xyz,
+   Postal Code 008800
+
+   S/N  Item Description       Amount (SGD)
+
+   1    Shrimps (x2 Bags)      15
+   2    Prawns (x2 Bags)       25
+
+                        Total  40
+  ----------------------------------- Page 1 -
+
+As you can see, (whether you like it or not) the pages are merely concatenated
+together to form a single pdf !!
+
+=== 2.3: Image Replacement Example
+
+It is possible to replace images in an odt file, a useful feature if u need to insert
+digital signature into the final pdf. To acheive this, u have to:
+* insert a placeholder image into the odt file,
+* resize & move it to your heart content
+* right click on the picture, under [Picture ...]/[Options], assign a unique value
+  for [Name]
+
+Template Odt:
+
+  --------------------------------------------
+        ~~~~~~~~~~~~~~~~~~
+    Hey | nice_guy_image |
+        ~~~~~~~~~~~~~~~~~~
+
+    This is a gentle reminder that i still
+      owe you some money ...
+
+    ~~~~~~~~~~~~~~~~~~~~~~
+    | my_signature_image |
+    ~~~~~~~~~~~~~~~~~~~~~~
+  ----------------------------------- Page 1 -
+
+Assuming 'nice_guy_image' & 'my_signature_image' as names of the images, the following
+code does the appropriate replacing of images:
 
   Clamsy.process(
-    [
-      {:someone => 'Peter', :mood => 'Happy'},
-      {:someone => 'Jane', :mood => 'Sad'}
-    ],
-    path_to_template_odt,
-    path_to_final_pdf
+    context = {:_pictures => {
+      :nice_guy_image => path_to_avatar_image,       # eg. '/tmp/handsome.png'
+      :my_signature_image => path_to_signature_image # eg. '/tmp/signature.png'
+    }},
+    path_to_template_odt # eg. '/tmp/confession.odt'
+    path_to_final_pdf    # eg. '/tmp/confession.pdf'
   )
 
-== Pre-requisites
+== 3. Pre-requisites
 
-#1. Archlinux
+=== 3.1. Archlinux
 
-   * Installing packages:
-     $ sudo pacman -S ghostscript cups cups-pdf go-openoffice
+  * Installing packages:
+    $ sudo pacman -S ghostscript cups cups-pdf go-openoffice
 
-   * Setting up the cups-pdf virtual printer by following instructions @
-     http://wiki.archlinux.org/index.php/CUPS#Configuring_CUPS-PDF_virtual_printer
+  * Setting up the cups-pdf virtual printer by following instructions @
+    http://wiki.archlinux.org/index.php/CUPS#Configuring_CUPS-PDF_virtual_printer
 
-   * Making sure cups is running:
-     $ sudo /etc/rc.d/cups start
+  * Making sure cups is running:
+    $ sudo /etc/rc.d/cups start
 
-#2. Ubuntu (to-be-updated)
+=== 3.2. Ubuntu (to-be-updated)
 
-#3. Mac (to-be-updated)
+=== 3.3. Mac (to-be-updated)
 
 == TODO
 
 * add support for configuration, eg. Clamsy.configure {|config| ... }
 
-* automate cups-pdf printer setup
+* automate cups-pdf printer setup or have ooffice directly export odt to pdf
 
 * avoid making system call to 'ooffice'
 

data/Rakefile

@@ -12,6 +12,7 @@ begin
     gem.authors = ["NgTzeYang"]
     gem.add_dependency "rubyzip", "= 0.9.4"
     gem.add_dependency "rghost", "= 0.8.7.2"
+    gem.add_dependency "nokogiri", "= 1.4.1"
     gem.add_development_dependency "bacon", ">= 1.1.0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/clamsy.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{clamsy}
-  s.version = "0.0.2"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["NgTzeYang"]
-  s.date = %q{2010-04-22}
+  s.date = %q{2010-04-25}
   s.description = %q{}
   s.email = %q{ngty77@gmail.com}
   s.extra_rdoc_files = [
@@ -28,12 +28,16 @@ Gem::Specification.new do |s|
      "lib/clamsy.rb",
      "lib/clamsy/tenjin.rb",
      "spec/clamsy_spec.rb",
+     "spec/data/clamsy.png",
+     "spec/data/clamsy2.png",
      "spec/data/embedded_ruby_example.odt",
      "spec/data/embedded_ruby_example.pdf",
      "spec/data/escaped_text_example.odt",
      "spec/data/escaped_text_example.pdf",
      "spec/data/multiple_contexts_example.odt",
      "spec/data/multiple_contexts_example.pdf",
+     "spec/data/picture_example.odt",
+     "spec/data/picture_example.pdf",
      "spec/data/plain_text_example.odt",
      "spec/data/plain_text_example.pdf",
      "spec/spec_helper.rb"
@@ -55,15 +59,18 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rubyzip>, ["= 0.9.4"])
       s.add_runtime_dependency(%q<rghost>, ["= 0.8.7.2"])
+      s.add_runtime_dependency(%q<nokogiri>, ["= 1.4.1"])
       s.add_development_dependency(%q<bacon>, [">= 1.1.0"])
     else
       s.add_dependency(%q<rubyzip>, ["= 0.9.4"])
       s.add_dependency(%q<rghost>, ["= 0.8.7.2"])
+      s.add_dependency(%q<nokogiri>, ["= 1.4.1"])
       s.add_dependency(%q<bacon>, [">= 1.1.0"])
     end
   else
     s.add_dependency(%q<rubyzip>, ["= 0.9.4"])
     s.add_dependency(%q<rghost>, ["= 0.8.7.2"])
+    s.add_dependency(%q<nokogiri>, ["= 1.4.1"])
     s.add_dependency(%q<bacon>, [">= 1.1.0"])
   end
 end

data/lib/clamsy.rb

@@ -1,6 +1,7 @@
 require 'ftools'
 require 'digest/md5'
 require 'tempfile'
+require 'nokogiri'
 require 'zip/zip'
 require 'clamsy/tenjin'
 require 'rghost'
@@ -47,9 +48,10 @@ module Clamsy
 
       def render(context)
         @context_id = Digest::MD5.hexdigest(context.to_s)
-        Zip::ZipFile.open(working_odt.path) do |zip|
-          zip.select {|entry| entry.file? && entry.to_s =~ /\.xml$/ }.each do |entry|
-            zip.get_output_stream(entry.to_s) {|io| io.write(workers[entry].render(context)) }
+        Zip::ZipFile.open(working_odt.path) do |@zip|
+          @zip.select {|entry| entry.file? && entry.to_s =~ /\.xml$/ }.each do |entry|
+            @zip.get_output_stream(entry.to_s) {|io| io.write(workers[entry].render(context)) }
+            replace_pictures(entry, context[:_pictures] || {})
           end
         end
         working_odt
@@ -57,6 +59,14 @@ module Clamsy
 
       private
 
+        def replace_pictures(entry, pictures)
+          xpaths = lambda {|name| %\//drawframe[@drawname="#{name}"]/drawimage/@xlinkhref\ }
+          doc = Nokogiri::XML(entry.get_input_stream.read.gsub(':','')) # Hack to avoid namespace error
+          pictures.each do |name, path|
+            (node = doc.xpath(xpaths[name])[0]) && @zip.replace(node.value, path)
+          end
+        end
+
         def working_odt
           (@working_odts ||= {})[@context_id] ||=
             begin

data/spec/clamsy_spec.rb

@@ -1,15 +1,17 @@
-require 'spec_helper'
+require File.join(File.dirname(__FILE__), 'spec_helper')
 
 describe "Clamsy" do
 
   behaves_like 'has standard files support'
 
   before do
-    @check_processing_yields_text = lambda do |contexts, example|
+    @check_processing_yields_content = lambda do |contexts, example|
       generated_pdf = tmp_file('clamsy_pdf').path
-      expected_content = comparable_content(expected_pdf(example))
       Clamsy.process(contexts, template_odt(example), generated_pdf)
-      comparable_content(generated_pdf).should.equal expected_content
+      expected_content = comparable_content(expected_pdf(example))
+      generated_content = comparable_content(generated_pdf)
+      generated_content.size.should.equal expected_content.size
+      (generated_content - expected_content).should.equal []
     end
   end
 
@@ -17,15 +19,22 @@ describe "Clamsy" do
     trash_tmp_files
   end
 
+  it 'should do picture replacement for matching <draw:frame draw:name="..." />' do
+    @check_processing_yields_content[
+      context = {:_pictures => {:to_be_replaced_pic => data_file('clamsy.png')}},
+      example = :picture
+    ]
+  end
+
   it 'should do #{...} plain text replacement' do
-    @check_processing_yields_text[
+    @check_processing_yields_content[
       context = {:someone => 'Peter', :mood => 'Happy'},
       example = :plain_text
     ]
   end
 
   it 'should do ${...} escaped (santized) replacement' do
-    @check_processing_yields_text[
+    @check_processing_yields_content[
       context = {:someone => '<Peter>', :mood => '<Happy>'},
       example = :escaped_text
     ]
@@ -38,14 +47,14 @@ describe "Clamsy" do
         @name, @mood = name, mood
       end
     end
-    @check_processing_yields_text[
+    @check_processing_yields_content[
       context = {:everyone => [@someone.new('Peter','Happy'), @someone.new('Jane','Sad')]},
       example = :embedded_ruby
     ]
   end
 
   it 'should concat multiple contexts processing to a single pdf' do
-    @check_processing_yields_text[
+    @check_processing_yields_content[
       contexts = [{:someone => 'Peter', :mood => 'Happy'}, {:someone => 'Jane', :mood => 'Sad'}],
       example = :multiple_contexts
     ]

data/spec/spec_helper.rb

@@ -10,25 +10,37 @@ require 'clamsy'
 
 shared 'has standard files support' do
   class << self
+
+    INSIGNIFICANT_AND_UNMATCHABLE_PATTERNS = [
+      /^q\[\-?\d+\.?\d*( \-?\d+\.?\d*){5}\]concat\n$/,
+      /^\d+\.?\d*( \d+\.?\d*){3} re\n$/
+    ]
+
     def data_file(file)
       File.join(File.dirname(__FILE__), 'data', file)
     end
+
     def template_odt(name)
       data_file("#{name}_example.odt")
     end
+
     def expected_pdf(name)
       data_file("#{name}_example.pdf")
     end
+
     def comparable_content(file)
       RGhost::Convert.new(file).to(:ps).read.grep(/^[^%][^%]?/).
-        reject {|line| line =~ /^q\[\-?\d+( \-?\d+){5}\]concat\n$/ }
+        reject {|line| INSIGNIFICANT_AND_UNMATCHABLE_PATTERNS.any? {|regexp| regexp =~ line } }
     end
+
     def trash_tmp_files
       (@trashable_tmp_files || []).select {|f| f.path }.map(&:unlink)
     end
+
     def tmp_file(file_name)
       ((@trashable_tmp_files ||= []) << Tempfile.new(file_name))[-1]
     end
+
   end
 end
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - NgTzeYang
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-22 00:00:00 +08:00
+date: 2010-04-25 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,9 +47,23 @@ dependencies:
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: bacon
+  name: nokogiri
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 4
+        - 1
+        version: 1.4.1
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bacon
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -59,7 +73,7 @@ dependencies:
         - 0
         version: 1.1.0
   type: :development
-  version_requirements: *id003
+  version_requirements: *id004
 description: ""
 email: ngty77@gmail.com
 executables: []
@@ -81,12 +95,16 @@ files:
 - lib/clamsy.rb
 - lib/clamsy/tenjin.rb
 - spec/clamsy_spec.rb
+- spec/data/clamsy.png
+- spec/data/clamsy2.png
 - spec/data/embedded_ruby_example.odt
 - spec/data/embedded_ruby_example.pdf
 - spec/data/escaped_text_example.odt
 - spec/data/escaped_text_example.pdf
 - spec/data/multiple_contexts_example.odt
 - spec/data/multiple_contexts_example.pdf
+- spec/data/picture_example.odt
+- spec/data/picture_example.pdf
 - spec/data/plain_text_example.odt
 - spec/data/plain_text_example.pdf
 - spec/spec_helper.rb