pdf_tempura 0.0.2

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTExNjA1ZWY2NjkwZDA5YmY4Y2NhODhiMmRjMzZhZTJiY2IzN2M0OQ==
+  data.tar.gz: !binary |-
+    MDczNGQ5NzJkYmNjODA3YThkZWZlYTExNzU1OWI3NTU1ZGM0YTc4ZA==
+SHA512:
+  metadata.gz: !binary |-
+    ZGI2ZWZiNGJiMjNmMjUxOTJkOGYyOTBjYTkyMjFiYmVjOTM4Mjk1NzVlOWE2
+    MjdhNTg4MTQwZDcxNmQ4MjE3NDIxZDZkMDE1ZjI3MDNmYWRlZmU2NDZkM2Iy
+    ZjFjMTFjYTM5Zjk3ZWIwMGI5ZjNiZTA0YmRkYzZiZjMwYzYwYzc=
+  data.tar.gz: !binary |-
+    MzY4YjU3ZjFiMWU0ODBmYTA3NDNhZjc3N2NjMTVkYWIyODkwYjFhZjk3ZjM0
+    NWFjY2JiODI4ODA2ZDMwYTk2ZTYyM2ViYjY1ODhlOWUwZmU3MzUyYTg0ZDE1
+    Y2Q2N2NjMDdjMzhjZmFhYzBlNTlkNGE0YWEwN2Q5NjdkOGM5YzQ=

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.ruby-*

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+script: "bundle exec rspec"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pdf_tempura.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 PayrollHero
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,342 @@
+# PdfTempura
+
+[![Code Climate](https://codeclimate.com/github/payrollhero/pdf_tempura.png)](https://codeclimate.com/github/payrollhero/pdf_tempura)
+[![Build Status](https://travis-ci.org/payrollhero/pdf_tempura.png?branch=master)](https://travis-ci.org/payrollhero/pdf_tempura)
+[![Dependency Status](https://gemnasium.com/payrollhero/pdf_tempura.png)](https://gemnasium.com/payrollhero/pdf_tempura)
+
+
+A gem for overlaying text and other fields onto PDF templates using Prawn.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pdf_tempura'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pdf_tempura
+
+## Usage
+
+### Building your overlayed PDF template
+
+Inherit from `PdfTempura::Document` to start off your pdf.
+
+#### Specifying the template
+
+Specify your template using:
+
+```ruby
+  template "/some/path/to/template.pdf"
+```
+
+#### Specifying pages
+
+The `page` method can be used to specify a page. It takes number to specify the page, 
+and a block where you specify your fields.
+
+You may also specify default options for layout by passing them into the "page" method.
+They will be inherited into all the page elements unless overridden by the options
+of that element.
+
+```ruby
+page 1, alignment: "left" do
+  # fields ...
+end
+```
+
+#### Specifying fields
+
+Fields should be specified inside pages using the `page` method. Fields can be specified by using one of the following fields methods.
+
+##### Text fields
+
+You can specify a text field using the `text_field` method. It requires a name, an array of coordinates (x and y), and an array of dimensions (width and height).
+Coordinates and dimensions are numbers referencing PDF units, starting from bottom left.
+
+```ruby
+text_field(name, coordinates, dimensions, options)
+```
+
+It also takes an options hash where you can set the following options:
+
+Common Options:
+
+- **type**: "text", "checkbox" or "box-list".  Defines the type of the field and draws the appropriate type. A box-list will create a box field for each character of the passed text.  Default is "text".
+- **default_value**: The default value for the field. Default is nil.
+
+TextField options:
+
+- **font_size**: A number in pixels (i.e. 13), or auto to change the font to fit the field size. Default is 10px.
+- **font_name**: The name of the font to use. Default: "Helvetica"
+- **italic**: True or false. Makes the text italic when set to true. Default to false.
+- **bold**: True or false. Makes the text bold when set to true. Default is false.
+- **alignment**: "left", "center" or "right". Aligns the text in the boundaries of the field. Default is "left".
+- **multi_line**: True or false. Forces the text to wrap to the next line when it hits the boundaries of the field. Default is false.
+- **padding**: An array of 4 numbers, representing top, right, bottom, left. It adds padding in pdf units inside the field.
+- **valign**: Defines vertical alignment of the text in the box, top, center, or bottom.
+- **leading**: When multi_line is true, this will add top_margin to each wrapped line of text.
+
+```ruby
+page 1 do
+  text_field :country, [10, 20], [200, 400], default_value: "USA", font_size: 13, bold: true, alignment: left, multi_line:true
+end
+```
+
+##### Checkbox fields
+You can specify a checkbox field using the `checkbox_field` method. It requires a name, an array of coordinates (x and y), and an array of dimensions (width and height).
+Coordinates and dimensions are numbers referencing PDF units, starting from bottom left.
+
+```ruby
+checkbox_field(name, coordinates, dimensions, options)
+```
+
+It also takes an options hash where you can set the following options:
+
+- **default_value**: True or false. The default value for the checkbox. Default is false.
+
+```ruby
+page 1 do
+  checkbox_field :send_me_snacks, [10, 20], [20, 20], default_value: true
+end
+```
+
+##### Boxed Characters
+This is a field which helps you to display a field which needs to be printed
+in a boxed fashion.  E.g. [H][E][L][L][O]-[W][O][R][L][D].
+
+```ruby
+boxed_characters :name, [10,20], 20, box_spacing: 1, box_width: 10 do
+  characters 4
+  space 2
+  characters 4
+end
+```
+
+Boxed Characters options:
+
+- **box_spacing**: Required, amount of space between each individual box
+- **box_width**: Required, the width of each individual box
+- **other**: You may use any of the options that are also in use with text_field
+EXCEPT for alignment, and multi-line.
+
+##### Tables
+
+```ruby
+class MyDoc < PdfTempura::Document
+  page 1 do
+    table :stuff, [500,50], height: 300, number_of_rows: 10, row_height: 25, cell_padding: 1 do
+      text_column :pin, 50
+      space 5
+      checkbox_column :last_name, 100
+    end
+  end
+end
+```
+
+The table construct allows the creation of a repeating set of fields.
+
+Table options:
+
+- **height**: Optional, height of the overall table.
+- **number_of_rows**: The number of rows in the table, required
+- **row_height**: The height of each row
+- **cell_padding**: Padding between each cell, optional
+
+The `table` call takes a name, the x,y position of the top-left corner
+of the table, the number of rows, either row_height or height (or both), and
+cell padding.
+
+Inside the table block, you define columns or spaces.  Columns themselves have
+amalgamous names to those you may use in "page" to describe fields.  Use
+"text_column" for a column containing text, "checkbox_column" for a cell
+containing a checkbox.
+
+Space only takes one parameter, its width.
+
+Column mimicks 'field', except you only specify the width of the column,
+the rest is figured out by the table.
+
+Table data is assigned through assigning an array of hashes to the key
+named after the name of the table.
+
+eg:
+
+```ruby
+data = {
+ 1 => {
+   stuff: [
+     { pin: "12 3456789 6", last_name: "Doe"}
+   ]
+ }
+}
+```
+
+##### Field Sets
+A field set allows you to group pieces of data under a particular heading.  You
+define a field set simply by the name of the heading it will be contained under
+in the data.  This is to help you organize your data logically.
+
+You may also specify default options for layout by passing them into the `field_set` method.
+They will be inherited into all the page elements unless overridden by the options
+of that element.
+
+```ruby
+class MyPdf < PdfTempura::Document
+  ...
+
+  page 1 do
+    field_set "customer", font_size: 12 do
+      text_field "name", [0,0], [10,20]
+      text_field "address", [0,10], [10,20]
+    end
+  end
+
+end
+
+data = {
+  1 => {
+    "customer" => { "name" => "John Bazdaritch", "address" => "123 Hollywood Blvd" }
+  }
+}
+```
+
+##### Specifying default options for a few elements
+The `with_default_options` block can be used to provide default options for all elements
+within it's specified block. These default options will be merged with the default options
+of the enclosing page, field set or table. Elements can override these default options
+by explicitly passing the option to the element.
+
+```ruby
+page 1, alignment: "left" do
+  text_field :aligned_left, [10,20], [100,50]
+
+  with_default_options alignment: "right" do
+    text_field :aligned_right, [40,60], [100,50]
+    text_field :also_aligned_left, [70,80], [100,50], alignment: "right"
+  end
+end
+
+#### Specifying reusable groups
+
+If you have the same fields on multiple pages, you can use the `group` method to DRY your template.
+
+```ruby
+group :employee_details do
+  field :first_name, [10, 20], [100, 30]
+  field :surname, [120, 20], [200, 30], bold: true
+  field :company, [330, 20], [300, 30], alignment: right
+end
+```
+
+Then you can use the `include_group` method to add that group to pages.
+
+```ruby
+page 1 do
+  include_group :employee_details
+  field :address, [10, 20], [500, 60]
+  ...
+end
+
+page 2 do
+  include_group :employee_details
+  field :emergency_contact, [10, 20], [500, 60]
+  ...
+end
+```
+
+### Rendering your PDF
+
+#### Loading field data
+
+You can load the field data by creating a new instance of your overlayed template and passing a data hash.
+The data hash should be a hash of hashes, the keys at the first level matching the page numbers and groups of your template,
+and the keys inside the nested hashes matching the names of the fields in those pages.
+
+```ruby
+data_hash = {
+  :employee_details => {
+    :first_name => "Stan",
+    :surname => "Smith",
+    :company => "CIA"
+  },
+  1 => {
+    :address => "The Pentagon, Washington, DC"
+  },
+  2 => {
+    :emergency_contact => "Francine Smith"
+  }
+}
+
+my_pdf = MyPdf.new(data_hash)
+```
+
+You can override group values by including the key in a specific page's data hash. Keys can be either strings or symbols. 
+
+#### Rendering your overlayed PDF
+
+After loading the field data, you can then render the PDF using the `render` method. The render method takes a block,
+and provides the opened pdf file as an argument.  The pdf file will be closed when the block terminates and the value of the block
+will be returned.
+
+```ruby
+mypdf.render do |pdf|
+  # save PDF to file
+  File.new("/path/to/file". "w+") do |file|
+    file.write(pdf.read)
+  end
+end
+```
+
+### Repeating data
+If you would like the template you have specified to be repeated on matching pages
+then you need to use the "repeatable" option in your Document class.  If repeatable is set
+then if you specify pages 1,2 in your document, and then specify 1,2,3,4 in your data
+the produced page will reuse the template's page 1 for page 3 and page 2 for page 4, etc.
+```ruby
+class MyPdf < PdfTempura::Document
+
+  template "/some/path/to/template.pdf"
+  repeatable
+
+  ...
+
+end
+
+data = {1 => ... data for page 1,
+        2 => ... data for page 2,
+        3 => ... data for page 3,
+        4 => ... data for page 4}
+```
+
+### Debug mode
+
+You can set your template to debug mode to help you position your fields using the `debug` method. The debug options are:
+
+- **grid**: This will overlay a grid on the document, each box representing a 10x10 unit area.
+- **outlines**: This will outline each field with a black border.
+
+```ruby
+class MyPdf < PdfTempura::Document
+
+  template "/some/path/to/template.pdf"
+
+  debug :grid, :outlines
+
+  ...
+
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/example/my_pdf.rb

@@ -0,0 +1,37 @@
+class MyPdf < PdfTempura::Document
+  template "spec/assets/sample_pdf_form.pdf"
+
+  debug :outlines
+  debug :grid
+  repeatable
+
+  page 1 do
+    text_field "name", [193,641.5], [311.5,25], padding: [0,5,0,5]
+    text_field "email", [193,602], [311.5,25.25], padding: [0,5,0,5], bold: true, font_name: "Courier"
+    text_field "reason", [54,481], [502,311], padding: [5,5,5,5], multi_line: true, font_size: 18
+    checkbox_field "accept", [192,554], [22,22]
+
+    boxed_characters "pin", [139,146], 20, box_width: 19.75, box_spacing: 0 do
+      characters 2
+      space 8.5
+      characters 3
+      space 8
+      characters 2
+    end
+  end
+
+  page 2 do
+    with_default_options alignment: "center" do
+      table "table", [57,688], number_of_rows: 16, height: 550,cell_padding: 1 do
+        text_column "id",42
+        text_column "name",232, padding: [5,5,5,5]
+        text_column "email",224, padding: [5,5,5,5]
+      end
+    end
+
+    field_set "form" do
+      text_field "id", [122,60], [125,27], padding: [5,5,5,5], font_size: 2
+    end
+  end
+
+end