shipping_materials 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 09d4424dc7c0604733b0a036401f36ce73e2c18c
+  data.tar.gz: 8775e800e7580de9203ad819bb4c8337d6444f7c
+SHA512:
+  metadata.gz: 001907c0d0a1ebda644b76221a44de39d5813a3fc542eaac733fc221dbd963d1d707ab6f812eda8f9ee8a2268327309ad4606146307c49d303c5b5ce06a176cd
+  data.tar.gz: f03e05bfec70bc67692286dcf4bfe0b681a23fa3090a4d0c3eb4e068c94a5093097777b22343eb2d57ab1cb5f913a1db5e452bdeeca4925df690791d42b87ac8

data/.gitignore

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

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Andrew Haust
+
+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,232 @@
+# Shipping Materials
+
+Shipping Materials provides a simple DSL for grouping and sorting a collection
+of orders and their items and creating print materials for them.  So far this
+includes packing slips and CSVs for label makers.
+
+## Installation
+
+    $ gem install shipping_materials
+
+## Dependencies
+
+`wkhtmltopdf` if used for PDF generation.  The call to it is made as a linux
+command therefore this plugin will not work on Windows yet.
+    
+`gzip` is used for the zip functionality.
+
+## Usage
+
+### Setup
+
+There is a little bit of configuration you are going to want to do first and
+that is to add a save_path.
+
+```ruby
+  ShippingMaterials.config do |config|
+    config.save_path = 'local/save/path'
+  end
+```
+
+If you would like to use S3, add the following:
+
+```ruby
+  ShippingMaterials.config do |config|
+    config.s3_bucket            = 'bucket.domain.com'
+    config.s3_access_key_id     = ENV['AWS_ACCESS_KEY']
+    config.s3_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  end
+```
+
+### The Packager
+
+The DSL is provided via the ShippingMaterials::Packager class.
+
+```ruby
+  packager = ShippingMaterials::Packager.new
+```
+
+The Packager's `#package` method takes a collection of objects of the same
+type.
+
+```ruby
+  orders = Order.where(state: 'placed')
+
+  packager.package :orders do
+    # ...
+  end
+```
+
+Because we are creating shipping materials here, at the very least, it is
+assumed you are going to want packing slips.  You may specify a global template
+with the `#pdf` method:
+
+```ruby
+  packager.package orders do
+    pdf 'path/to/template.mustache'
+  end
+```
+
+Now, at the simplest level, we can start breaking these objects down into
+groups.
+
+```ruby
+  packager.package orders do
+    pdf 'path/to/template.mustache'
+
+    group 'Canadian Standard Post' do
+      filter {
+        ship_method == 'std' && country == 'CA'
+      }
+    end
+    
+    group 'United States UPS Expedited' do
+      filter {
+        ship_method == 'UPSexp' && country == 'US'
+      }
+    end
+    
+    group 'International World Ship' do
+      filter {
+        ship_method == 'UPS' && !%w[ US CA ].include?(country)
+      }
+    end
+  end
+```
+
+PDFs (one per group) will now be created.  With groups named as above, you can
+expect the file names 'CanadianStandardPost.pdf', 'UnitedStatesUPSExpedite.pdf'
+and 'InternationalWorldShip.pdf'.
+
+### Templating
+
+Right now, templating is done with Mustache.  I plan on adding more in the
+future (or feel free to send me a pull request).  Here is an example template:
+
+```html
+  <html>
+    {{# objects }}
+      <div>
+        <p>{{ number }}</p>
+        {{# line_items }}
+          <p>{{ name }}: ${{ price }} x {{ quantity }} = {{ total }}</p>
+        {{/ line_items }}
+      </div>
+    {{/ objects }}
+  </html>
+```
+
+
+I chose the 'objects' as the default variable name, though you may change this
+in config:
+
+```ruby
+  ShippingMaterials.config do |config|
+    config.base_context = 'orders'
+  end
+```
+
+Each group will produce one PDF.
+
+### CSV (for shipping labels)
+
+Any label printer I know -- as well as things like UPS Worldship -- use CSVs,
+so Shipping Materials provides a little CSV templating DSL.  This is provided
+via the `Group#csv` method.
+
+The `#csv` method takes a block which exposes the `#row` method.  `#row` takes
+a hash or an array and may be called multiple times.
+
+Here is an example with hashes:
+
+```ruby
+  group 'Canadian Standard Post' do
+    csv(headers: true) {
+      row 'Code' => 'Q',
+          'Order Number' => :number,
+          'Name'     => [ :shipping_address, :name ]
+           # ...
+          'Country'  => [ :shipping_address, :country, :iso ]
+          
+      row line_items: [ 'H', :id, :name, :quantity, :price ]
+    }
+  end
+```
+
+In this example, the first call to row is evaluated in the context of each
+order.  Symbols are called as methods whereas string values are kept as-is.  In
+order to chain method calls, use an array of symbols as a value.  For example,
+`[ :shipping_address, :country, :iso ]` will call
+`order.shipping_method.country.iso`.
+
+Passing `headers: true` to the csv method will use the keys from the _first_
+call to row (if it is a hash) as the headers for the CSV.
+
+As demonstrated in the second call to row, you can evalute your row in the
+context of your line items (or other one-to-many relationship) using its method
+name as a key.
+
+### Sorting
+
+While most sorting should probably be done at the query level, Shipping
+Materials provides a sorting DSL for more complex sorts.  For example:
+
+```ruby
+  packager.package orders do
+    pdf 'path/to/template.mustache'
+      
+    sort do
+      # put orders containing only Vinyl at the top
+      rule {
+        return true unless line_items.detect {|li| type != 'Vinyl' }
+      }
+      
+      # next come orders that have both Vinyl and CDs and nothing else
+      rule {
+        line_items.select {|li| %w[ Vinyl CD ].include?(li.type) }.uniq.size == 2
+      }
+      
+      # get the picture?
+    end
+      
+    group # ...
+  end
+```
+
+A merge sort will be performed sorting the orders within each group according
+to each rule in the order they are defined.
+
+While it is definitely recommended to sort line items at the query level, you
+can operate in the context of line items by passing the name of the association
+to the sort method (ie: your association doesn't have to be called "line_items"
+specifically):
+
+```ruby
+  sort(:line_items) do
+    rule { type == 'Vinyl' }
+    rule { type == 'CD' }
+    rule { type == 'Cassette' }
+    rule { type == '8-Track' }
+  end
+```
+
+This will sort your line items within each packing slip.
+
+## Documentation
+
+Other than this README, there is no documentation yet.  There are a few other
+experimental and volatile features not mentioned here.  They are certainly
+going to change soon.
+
+## Contributing
+
+This is my first foray into the world of library authoring.  I welcome any and
+all advice and pull requests with open arms, but for the love of whoever or
+whatever you believe in: please follow [these
+guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+when writing your commit messages.
+
+## A note about the tests
+
+I am still learning to test properly.  Tests are passing _but_ some of them are
+writing to the filesystem.  These wrongs will be righted in due time.

data/Rakefile

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

data/examples/example.rb

@@ -0,0 +1,33 @@
+ShippingMaterials.config do |config|
+  config.save_path = MyProject::Config[:asset_storage_location]
+end
+
+packager = ShippingMaterials::Packager.new
+
+orders = Orders.where(state: 'placed')
+
+packager.package orders do
+  pdf 'path/to/template',
+
+  sort(:line_items) {
+    rule { type == 'Vinyl' }
+    rule { type == 'CD' }
+    rule { type == 'Cassette' }
+  }
+
+  sort {
+    rule { line_items.detect {|li| li.type == 'vinyl' } }
+  }
+
+  group 'canada_standard_shipping' do
+    filter { country == 'CA' && shipping_method == 'std' }
+
+    csv(extenstion: 'txt', headers: true) {
+      row code:     'Q',
+          order_id: :id,
+          hello:    :hello
+
+      row line_items: [ 'H', :id, :name, :price, :quantity ]
+    }
+  end
+end

data/lib/shipping_materials.rb

@@ -0,0 +1,19 @@
+require 'mustache'
+
+require 'shipping_materials/version'
+require 'shipping_materials/mixins/sortable'
+
+require 'shipping_materials/config'
+require 'shipping_materials/storage'
+require 'shipping_materials/packager'
+require 'shipping_materials/group'
+require 'shipping_materials/csv_dsl'
+require 'shipping_materials/packing_slips'
+require 'shipping_materials/sorter'
+require 'shipping_materials/s3'
+
+module ShippingMaterials
+  def self.config
+    yield Config
+  end
+end

data/lib/shipping_materials/config.rb

@@ -0,0 +1,35 @@
+module ShippingMaterials
+  class Config
+    class << self
+      attr_accessor :s3_bucket,
+                    :s3_access_key,
+                    :s3_secret,
+                    :gzip_file_name
+
+      def base_context
+        @base_context || :objects
+      end
+
+      def base_context=(bc)
+        @base_context = bc.to_sym
+      end
+
+      def save_path=(save_path)
+        @save_path = save_path.sub(/(\/)+$/, '')
+      end
+
+      def save_path
+        @default   ||= Time.now.to_i
+        @save_path || "/tmp/shipping_materials#{@default}"
+      end
+
+      def use_s3?
+        @s3_bucket
+      end
+
+      def use_gzip?
+        @gzip_file_name
+      end
+    end
+  end
+end

data/lib/shipping_materials/csv_dsl.rb

@@ -0,0 +1,82 @@
+module ShippingMaterials
+  class CSVDSL
+    require 'csv'
+
+    attr_accessor :objects, :row_maps
+
+    def initialize(objects, options={})
+      @objects  = objects
+      @row_maps = {}
+      @options  = options
+    end
+
+    # This method is on the complex side. It is a DSL method that
+    # performs type-checking and also sets the headers.
+    # Be sure to see headers=() defined below
+    def row(collection)
+      if collection.is_a? Array
+        @row_maps[:object] = collection
+      elsif collection.is_a? Hash
+        f = collection.first
+        if f[1].is_a? Array
+          @row_maps[f[0]] = f[1]
+        elsif f[1].is_a? Hash
+          self.headers = collection.first[1]
+          @row_maps[f[0]] = f[1].values
+        else
+          self.headers = collection
+          @row_maps[:object] = collection.values
+        end
+      end
+    end
+
+    def to_csv
+      CSV.generate do |csv|
+        csv << headers if headers?
+        @objects.each do |object|
+          @row_maps.each do |context, methods|
+            if context == :object
+              csv << get_row(object, methods)
+            else
+              object.send(context).each do |c|
+                csv << get_row(c, methods)
+              end
+            end
+          end
+        end
+      end
+    end
+
+    alias_method :to_s, :to_csv
+
+    def extension
+      @options[:extension] || 'csv'
+    end
+
+    def headers
+      @headers
+    end
+
+    def headers=(object)
+      @headers ||= object.keys.map {|h| h.to_s } if self.headers?
+    end
+
+    def headers?
+      @options[:headers]
+    end
+
+    private
+
+    def get_row(object, methods)
+      methods.map do |meth|
+        if meth.is_a? Symbol
+          object.send(meth)
+        elsif meth.is_a? Array
+          meth.reduce(object) {|obj, m| obj.send(m) }
+        elsif meth.is_a? String
+          meth
+        end
+      end
+    end
+  end
+end