thousand_island 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 389fb55f938dbc9612ecbdab028eb4c6f7a1ba6b
+  data.tar.gz: ef8e4cb13f7628a49c8f61af335686b6bf9596e6
+SHA512:
+  metadata.gz: a720ae6858b1a2716f90b110aa5686023302add7de08f1e0929ca1e0da7b98877ac1c8d58dd6d10c7e0ea07530da3a3c5798fd9359dc64d9863e9bd2a9ba17a5
+  data.tar.gz: 12528531c5d4239969608d7ca0e0d6480494d84234293515a3ac587e16996b780ae2cd28fed86d85098209f48e58f1c3d8eed77ad275db5ab3939e0184f25355

data/.gitignore

@@ -0,0 +1,19 @@
+*.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-gemset
+.ruby-version

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+- 2.1.2
+- 2.0.0
+- 1.9.3
+script: bundle exec rspec spec
+env:
+  global:
+    secure: eswj1U2HJcBv8pIbk8TkBiry8GXQvFhIqaz/XYkvAC5pPDJrzTK9GpSjo2AkvRgck+H99ukzNmwd6Sn1cnnTE/9lsbSogXvBj588KOxivlQ03bZay2g0aeL35qtSnhmJ1e7G4+B3GRyqEYxHboIOKaKBNP93d9+0VVgmm+wfPPw=

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,23 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rsspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separetly)
+#  * 'just' rspec: 'rspec'
+guard :rspec, cmd: 'bundle exec rspec -f doc' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/thousand_island/(.+)\.rb$})     { |m| "spec/thousand_island/#{m[1]}_spec.rb" }
+  watch(%r{^lib/thousand_island/utilities/(.+)\.rb$})     { |m| "spec/thousand_island/utilities/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Turnip features and steps
+  # watch(%r{^spec/acceptance/(.+)\.feature$})
+  # watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Colin Weight
+
+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,363 @@
+# Thousand Island
+### Dressing for Prawn
+
+[![GitHub version](https://badge.fury.io/gh/colinweight%2Fthousand_island.svg)](http://badge.fury.io/gh/colinweight%2Fthousand_island) [![Code Climate](https://codeclimate.com/github/colinweight/thousand_island/badges/gpa.svg)](https://codeclimate.com/github/colinweight/thousand_island) [![Test Coverage](https://codeclimate.com/github/colinweight/thousand_island/badges/coverage.svg)](https://codeclimate.com/github/colinweight/thousand_island) [![Build Status](https://travis-ci.org/colinweight/thousand_island.svg?branch=master)](https://travis-ci.org/colinweight/thousand_island) [![Inline docs](http://inch-ci.org/github/colinweight/thousand_island.png?branch=master)](http://inch-ci.org/github/colinweight/thousand_island)
+
+
+[Prawn](https://github.com/prawnpdf/prawn) is awesome. It has some amazing functionality, and you can get anything that's in your head onto a PDF document with some Ruby code. For me though, as wonderful as that is, I normally only need a repeating header and footer, and then some text and maybe a table in between them. This is where **Thousand Island** comes in. A few simple commands should get you set up with a template that you can use application wide, and then all you need to worry about is getting the right content into the document.
+
+> Note: ThousandIsland is not meant to be a substitute for learning Prawn, you will get more out of it if you do. The excellent [Prawn Manual](http://prawnpdf.org/manual.pdf) is a great place to start.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'thousand_island'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install thousand_island
+
+## Usage
+
+ThousandIsland uses the following classes to get the job done:
+
+**ThousandIsland::Template** - The common layout and formatting for your pdfs live in here
+
+**ThousandIsland::Builder** - Subclass the Builder for your actual business logic for the pdf itself
+
+**ThousandIsland::StyleSheet** - A mixin for defining common styles to be used by your Template
+
+A suggested directory structure for a Rails app is as follows, but it's entirely up to you:
+
+```
+app/
+└── pdf_builders/
+	├── my_builder.rb
+    └── templates/
+		├── my_template.rb  
+		├── my_style_sheet.rb
+```
+For a non-Rails application, the `lib` directory can be used instead of the `app` directory, but it's all up to you.
+
+### Creating a Template
+
+The Template class is where you can define elements that may be common to all (or some) documents within your application. It is likely that a common style will be required, so defining it in a Template and then using that Template subclass in any custom Builders DRYs up your pdf generation, as well as allowing for easy restyling across the whole application.
+
+Typically, the Template subclass would define the settings for the Prawn Document, as well as the settings for the header and footer. Add your own or override any existing settings in the `settings` method. Any options passed into the constructor as a Hash will be merged with these settings, and the defaults.
+
+Content for the header and footer will be defined in the methods `header_content` and `footer_content`. These methods are passed as a block when the pdf is rendered. Any standard Prawn methods may be used (including bounding boxes or any other layout tools). In addition, any of the styles from the `StyleSheet` can be applied as helper methods. For instance, the default style sheet has a `h1_style` method that returns a  ThousandIsland::StyleHash, so in your code you can use:
+```ruby
+  h1 "My Document Header"
+```
+and Prawn will render the text in the style set in the `h1_style` ThousandIsland::StyleHash.
+In addition to the supplied style methods, you can create a custom method:
+```ruby
+  def magic_style
+    ThousandIsland::StyleHash.new({
+      size: 15
+      style: bold
+    })
+  end
+```
+As long as the method ends in the word "_style" and returns a Hash, you magically get to do this:
+
+```ruby
+  magic "My magic text is bold and size 15!!"
+```
+
+The method may return a standard Hash, but it is safer to return a ThousandIsland::StyleHash, as this dynamically duplicates a few keys to accommodate using the style in normal Prawn text methods as well as formatted text boxes, which use a slightly different convention. You don't have to worry about that if you use the ThousandIsland::StyleHash.
+
+Alternatively, your method could do this:
+```ruby
+  def magic_style
+    h1_style.merge({
+      size: 15
+      style: bold
+    })
+  end
+```
+The following is an example of a custom template that subclasses
+ThousandIsland::Template -
+```ruby
+  class MyTemplate < ThousandIsland::Template
+    include MyCustomStyleSheet # optional
+
+    # settings here are merged with and override the defaults
+    def settings
+      {
+        header: {
+          height: 55,
+          render:true,
+          repeated: true
+        },
+        footer: {
+          render:true,
+          height: 9,
+          numbering_string: 'Page <page> of <total>',
+          repeated: true
+        }
+      }
+    end
+
+    def header_content
+      # Standard Prawn syntax
+      pdf.image "#{pdf_images_path}/company_logo.png", height: 30
+    end
+
+    def footer_content
+      # Using the magic method we get from the footer_style
+      footer "www.mycompanyurl.com"
+    end
+
+    def pdf_images_path
+      # How you go about this sort of thing is entirely up to you
+	  "#{Rails.root}/app/assets/pdf_images"
+    end
+  end
+```
+>Note: The Footer is a three column layout, with the numbering on the right column and the content defined here in the middle. More flexibility will be added in a later version.
+
+Optional:
+Add a `body_content` method to add content before whatever the Builder defines in it's method of the same name.
+
+### StyleSheets
+
+The StyleSheet is designed to be a mixin to the Template class. It may also be included into other modules to define custom StyleSheets.
+
+Methods should return a StyleHash object rather than a vanilla Hash, as it has some customisation to help it work with Prawn. The default_style is used as the starting point for all other styles. For instance, the `default_style[:size]` value is multiplied in the heading styles, so changing the default style size value will have a cascading effect. Check the source for the default values and override as preferred.
+
+An example of a custom StyleSheet:
+```ruby
+  module MyStyleSheet
+    include ThousandIsland::StyleSheet
+    
+    def default_style
+      super.merge({
+        size: 12,
+        color: '222222'
+      })
+    end
+    
+    def h1_style
+      super.merge({ align: :center })
+    end
+  end
+```
+
+### Creating a Builder
+
+Your Builder class is where you will put the necessary logic for rendering the final pdf. It's up to you how you get the data into the Builder. It will depend on the complexity. You might just pass an Invoice object (`MyBuilder.new(invoice))`) or you may have a bunch of methods that are called by an external object to get the data where it needs to be.
+
+You must declare which Template class you will be using. Failing to do so will raise a `TemplateRequiredError` when you call the build method. Declare the template with the following in the main class body:
+```ruby
+  uses_template MyTemplate
+```
+
+Your Builder can have a `filename` method, which will help a Rails Controller or other class determine the name to use to send the file to the browser or save to the filesystem (or both). Without this method it will have a default name, so you may choose to put the naming logic for your file elsewhere, it's up to you.
+
+You must have a `body_content` method that takes no arguments (or the pdf will be empty!). This is the method that is passed around internally in order for Prawn to render what is in the method. You can use raw Prawn syntax, or any of the style magic methods to render to the pdf. You may also call other methods from your `body_content` method, and use Prawn syntax and magic methods in those too. 
+
+A Builder example might be:
+```ruby
+  class MyBuilder < ThousandIsland::Builder
+    uses_template MyTemplate
+  
+    attr_reader :data
+    
+    def initialize(data={})
+      @data = data
+      # do something with the data...
+    end
+    
+    def filename
+      "Document#{data.id_number}"
+    end
+    
+    def body_content
+      # call custom methods, magic methods or call Prawn methods directly:
+      h1 'Main Heading'
+      display_info
+      body 'Main text in here...'
+    end
+    
+    # Custom method called by body_content
+    def display_info
+      body "Written by: #{data.author}"
+      pdf.image data.avatar, height: 20
+    end
+  end
+```
+
+Finally, to get the finished pdf from your Builder, call the `build` method like so:
+```ruby
+  pdf = my_builder.build
+```
+
+Optional:
+
+Define a `header_content` method to add content below whatever is defined in the Template. This will be repeated according to the header settings in the Template.
+
+Define a `footer_content` method to add content above whatever is defined in the Template. This will be repeated according to the footer settings in the Template.
+
+Define a `settings` method that returns a Hash. This will be passed to the Template class and will override any of the Template default settings.
+
+#### Using the Builder in a Rails Application
+
+Your Controller can look something like this:
+
+```ruby
+def show
+    @thing = Thing.find(params[:id])
+    respond_to do |format|
+      format.html
+      format.pdf do
+        data = { thing: @thing }  # How you structure this is up to you, it's your Class!!
+        builder = MyBuilder.new(data)
+        send_data builder.build, filename: builder.filename,
+          type: "application/pdf",
+          disposition: "inline" # Leave blank to render as a download
+      end
+    end
+  end
+```
+
+If your controller for getting the data for a PDF is that simple, then you're pretty lucky. Normally we're going to want a PDF file to render a few things at once, so you might build a service object that formats the data, and use as follows:
+
+```ruby
+def show
+    respond_to do |format|
+      format.html do
+        @thing_for_html_view = Thing.find(params[:id])
+      end
+      format.pdf do
+      	# Tell the service object to do it's thing and return the Builder
+        builder = ThingPdfServiceObject.new(params)
+        send_data builder.build,
+              filename: builder.filename,
+              type: "application/pdf",
+              disposition: "inline" # Leave blank to render as a download
+      end
+    end
+  end
+```
+
+These are only suggestions, as you can probably tell there is nothing tying you down to a particular way of building and delivering the document. You might even want to save it to the file system, or upload to S3. You could override the build method if you wanted to:
+```ruby
+  def build
+  	pdf = super
+    # Save, upload, send or do whatever....
+  end
+```
+However, that kind of logic seems beyond the scope of the Builder, and should proabably be in the consumer of your Builder class, rather than the builder itself.
+
+## Default Styles
+Out of the box, ThousandIsland gives you some generic styles with default values. Override any of the values in your custom Stylesheet, or your Template. Create your own entirely new style in either of those places too, and get the magic method for free.
+
+The default styles are:
+##### body
+```ruby
+{
+  :size => 10, # Inherited from default_style
+  :style => :normal, # Inherited from default_style
+  :align => :left, # Inherited from default_style
+  :leading => 1, # Inherited from default_style
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### h1
+```ruby
+{
+  :size => 18, # Calcuated as 1.8 * default_style[:size]
+  :style => :bold,
+  :align => :left, # Inherited from default_style
+  :leading => 8,
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### h2
+```ruby
+{
+  :size => 15, # Calcuated as 1.5 * default_style[:size]
+  :style => :bold,
+  :align => :left, # Inherited from default_style
+  :leading => 4,
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### h3
+```ruby
+{
+  :size => 14, # Calcuated as 1.4 * default_style[:size]
+  :style => :bold,
+  :align => :left, # Inherited from default_style
+  :leading => 4,
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### h4
+```ruby
+{
+  :size => 11, # Calcuated as 1.1 * default_style[:size]
+  :style => :bold_italic,
+  :align => :left, # Inherited from default_style
+  :leading => 4,
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### h5
+```ruby
+{
+  :size => 10, # Calcuated as 1 * default_style[:size]
+  :style => :normal, # Inherited from default_style
+  :align => :left, # Inherited from default_style
+  :leading => 4,
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### h6
+```ruby
+{
+  :size => 8.5, # Calcuated as 0.85 * default_style[:size]
+  :style => :italic,
+  :align => :left, # Inherited from default_style
+  :leading => 4,
+  :inline_format => true, # Inherited from default_style
+  :color => "000000" # Inherited from default_style
+}
+```
+##### footer
+```ruby
+{
+  :size => 0.8, # Calcuated as 0.8 * default_style[:size]
+  :style => :normal,
+  :align => :left, # Inherited from default_style
+  :leading => 1, # Inherited from default_style
+  :inline_format => true, # Inherited from default_style
+  :color => "666666"
+}
+```
+
+## To come...
+- Easy (and repeatable) Table formatting
+- Easy list rendering and styling (including nested lists)
+- More flexibility in the Footer layout
+- (Possibly) Command line functions to create common subclass files 
+
+## 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