business_catalyst 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3417d7cd299af29d9ef7c26b7fd7f4b6667c2ed5
+  data.tar.gz: 5574296fb9838e4fcbf76c4a89b2319866fb0b75
+SHA512:
+  metadata.gz: c83fe2e411426b7ab1fb19ed55a10265f33e66f264d75bbe33e821161bfb1896fbfb4ccb74541e34e11e8c36a6452dc68c69df500f6878bdca209b42e417c41a
+  data.tar.gz: 814db6e8948d5dde147520763164662b78dae8fed2e8dae662b1739e6641c5d4f225744856125c1dd9bad25d45f46d3827019ed6888d64af98ba83375396d5e9

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-version

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,11 @@
+bundler_args: --without guard
+script:
+  - "bundle exec rspec spec"
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0
+  - 1.9.3
+  - 1.8.7
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in business_catalyst.gemspec
+gemspec
+
+# Skip guard if we are on 1.8 (it won't work).
+# Guard also needs to be in its own group so Travis won't waste time installing it.
+if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new("1.9.3")
+  group :guard do
+    gem 'ruby_gntp'
+    gem 'guard-rspec'
+  end
+end

data/Guardfile

@@ -0,0 +1,13 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec,
+        :cmd => "bundle exec rspec",
+        :all_after_pass => true,
+        :all_on_start => true,
+        :failed_mode => :keep do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Tortus Technologies, Inc.
+
+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,104 @@
+# BusinessCatalyst
+
+Tools for building CSV's for Adobe Business Catalyst e-commerce platform in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'business_catalyst', '~> 0.1.0'
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+Start with subclassing any of the provided Row classes:
+
+* BusinessCatalyst::CSV::ProductRow
+* BusinessCatalyst::CSV::CatalogRow
+
+Then define methods to return values for the various BC columns.
+Use the #map method to ensure correct naming. (In general, it is just the
+underscored version of the BC column name, with '?' appended for
+boolean columns. The COLUMNS constant in the base class has the complete
+list, and I recommend referring to it extensively.)
+
+### Building a Product CSV
+
+```ruby
+class MyRow < BusinessCatalyst::CSV::ProductRow
+
+  default_currency "US" # optional, US is already the default
+
+  def initialize(product)
+    @product = product
+    super
+  end
+
+  map(:product_code) { @product.code }
+  map(:name)         { @product.name }
+  map(:catalog)      { ["Some", "Accessories"] }
+  map(:enabled?)     { @product.active }
+  map(:inventory_control?) { false }
+
+  # ... (other properties here)
+end
+
+# Later, with a CSV opened for writing:
+
+csv << MyRow.headers
+products.each do |product|
+  csv << MyRow.new(product).to_a
+end
+```
+
+### Returning Ruby data types in your methods
+
+In general, you can define your methods to return Ruby types such as Array,
+Float (try to use BigDecimal or FixNum for currency though), True/False, etc.,
+and the gem will turn it into the correct text for Business Catalyst for you,
+and handle all escaping.
+
+```ruby
+# Array:
+map(:catalog) { ["Value1", "Value2"] } # becomes: "Value1;Value2"
+
+# Numeric:
+map(:sell_price) { 10.0 } # becomes: "US/10.0"
+
+# boolean:
+map(:enabled?) { true } # becomes: "Y"
+```
+
+### If you have more than 10k product rows to import, use BusinessCatalyst::CSV::FileSplitter
+
+Business Catalyst limits the number of products you can import in a single
+CSV to 10000. However, you can get around this limit by importing multiple
+files. We have a class to help!
+
+```ruby
+# Simplest usage, assuming we already have some products to export:
+splitter = BusinessCatalyst::CSV::FileSplitter.new("output_base_name.csv", header_row: MyRow.headers)
+splitter.start do |splitter|
+  product_rows.each do |row|
+    splitter.start_row
+    splitter.current_file << row.to_a
+  end
+end
+```
+See the class definition for all available options.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run tests:
+
+    $ bundle install
+    $ bundle exec rspec
+
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/Rakefile

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

data/business_catalyst.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'business_catalyst/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "business_catalyst"
+  spec.version       = BusinessCatalyst::VERSION
+  spec.authors       = ["Tortus Tek, Inc."]
+  spec.email         = ["support@tortus.com"]
+  spec.description   = %q{Libraries to help with exporting product data to BC.}
+  spec.summary       = "business_catalyst-#{BusinessCatalyst::VERSION}"
+  spec.homepage      = "https://github.com/tortus/business_catalyst"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 10"
+  spec.add_development_dependency "rspec", "~> 2.14"
+end

data/lib/business_catalyst/csv/catalog_row.rb

@@ -0,0 +1,29 @@
+module BusinessCatalyst
+  module CSV
+    class CatalogRow < Row
+
+      COLUMNS = [
+        ["Catalog Name/Heirarchy", :catalog_name_hierarchy, nil, CatalogTransformer],
+        ["Description", :description],
+        ["Image", :image],
+        ["Weighting", :weighting],
+        ["Release Date", :release_date],
+        ["Expiry Date", :expiration_date],
+        ["Template ID", :template_id, 0, TemplateIDTransformer],
+        ["Enabled", :enabled?, true, BooleanTransformer],
+        ["Enable XML Feed", :enable_xml_feed?, true, BooleanTransformer],
+        ["Show Product Prices", :show_product_prices?, true, BooleanTransformer],
+        ["Catalog Title", :catalog_title],
+        ["Browse Panel Min Price", :browse_panel_min_price, nil, CurrencyTransformer],
+        ["Browse Panel Max Price", :browse_panel_max_price, nil, CurrencyTransformer],
+        ["Browse Panel Slots", :browse_panel_min_slots],
+        ["SEO Friendly URL", :seo_friendly_url, nil, SEOFriendlyUrlTransformer] # Must be globally unique
+      ]
+
+      def self.columns
+        COLUMNS
+      end
+
+    end
+  end
+end

data/lib/business_catalyst/csv/file_splitter.rb

@@ -0,0 +1,125 @@
+# encoding: utf-8
+require 'csv'
+require 'fileutils'
+
+module BusinessCatalyst
+  module CSV
+
+    # Business Catalyst can only import 10k product rows at a time.
+    # Use this class to help split up files.
+    #
+    # == Usage
+    #
+    #     headers = MyRowClass.headers
+    #     splitter = FileSplitter.new("output_base_name", max_rows_per_file: 10_000, header_row: headers)
+    #     splitter.start do |splitter|
+    #       product_rows.each do |row|
+    #         splitter.start_row
+    #         splitter.current_file << row.to_a
+    #       end
+    #     end
+    #
+    # If you want to watch for when a new file is opened and maybe
+    # do some logging, you can use the #on_file_change method:
+    #
+    #     splitter.on_file_change do |splitter|
+    #       puts "opened #{splitter.current_file.path}"
+    #     end
+    #
+    class FileSplitter
+
+      attr_accessor :base_name, :max_rows_per_file, :header_row, :verbose, :logger
+      attr_reader :current_row, :total_rows, :current_file, :all_files
+
+      alias_method :file_names, :all_files
+
+      def initialize(base_name, options = {})
+        @base_name = base_name
+        @max_rows_per_file = options.fetch(:max_rows_per_file) { 10_000 }
+        @header_row = options.fetch(:header_row) { nil }
+        @verbose = options.fetch(:verbose) { false }
+        @logger = options.fetch(:logger) { nil }
+
+        @current_row = 0
+        @total_rows = 0
+
+        @all_files = []
+        @current_file = nil
+      end
+
+      def start
+        begin
+          increment_file(1, max_rows_per_file) # will be off by one unless we set manually
+          yield self
+        ensure
+          close
+        end
+        rename_last_file
+      end
+
+      # Call before writing new row
+      def start_row
+        @current_row += 1
+        @total_rows += 1
+        if @current_row > max_rows_per_file
+          increment_file
+          @current_row = 1
+        end
+      end
+
+      def on_file_change(&block)
+        @on_file_change = Proc.new(&block)
+      end
+
+      def close
+        current_file.close if current_file
+      end
+
+    private
+
+      def increment_file(min_row = total_rows, max_row = total_rows + max_rows_per_file - 1)
+        @current_file.close if @current_file
+        new_file_name = file_name_with_range(base_name, min_row, max_row)
+        @all_files << new_file_name
+        log "writing to #{new_file_name}" if verbose
+        @current_file = ::CSV.open(new_file_name, 'wb')
+        if header_row
+          @current_file << header_row
+        end
+        trigger_on_file_change
+      end
+
+      def trigger_on_file_change
+        if @on_file_change.kind_of?(Proc)
+          if @on_file_change.arity >= 1
+            @on_file_change.call(self)
+          else
+            @on_file_change.call
+          end
+        end
+      end
+
+      def file_name_with_range(base_name, min, max)
+        "#{base_name}_#{min}-#{max}.csv"
+      end
+
+      def rename_last_file
+        last_file = @all_files.pop
+        if last_file
+          new_name = last_file.sub(/-\d+\.csv\z/i, "-#{total_rows}.csv")
+          FileUtils.mv last_file, new_name
+          @all_files << new_name
+        end
+      end
+
+      def log(msg)
+        if logger
+          logger.info msg
+        else
+          puts msg
+        end
+      end
+
+    end
+  end
+end

data/lib/business_catalyst/csv/product_attribute.rb

@@ -0,0 +1,129 @@
+# encoding: utf-8
+module BusinessCatalyst
+  module CSV
+
+    class ProductAttribute
+      Option = Struct.new(:name, :image, :price)
+
+      attr_accessor :name, :required, :keep_stock
+      attr_reader :display_as
+
+      def initialize(name, options = {})
+        @name = name
+        self.display_as = options.delete(:display_as) { nil }
+        @required = options.delete(:required) { false }
+        @keep_stock = options.delete(:keep_stock) { false }
+        unless options.empty?
+          raise ArgumentError, "unrecognized arguments: #{options.keys.inspect}"
+        end
+      end
+
+      def display_as=(value)
+        @display_as = self.class.normalize_display_as(value)
+      end
+
+      def options
+        @options ||= []
+      end
+
+      # Usage:
+      #
+      #     # Simplest:
+      #     add_option(name, image, price)
+      #
+      #     # Manually create ProductAttribute::Option instance:
+      #     add_option(ProductAttribute::Option.new(name, image, price))
+      #
+      def add_option(*args)
+        option = nil
+        if args.length == 1
+          arg = args.first
+          if arg.kind_of?(Option)
+            option = arg
+          elsif arg.kind_of?(Hash)
+            option = Option.new(arg.fetch(:name), arg.fetch(:image, nil), arg.fetch(:price, nil))
+          else
+            raise ArgumentError, "unrecognized argument: #{arg.inspect}"
+          end
+        else
+          name, image, price = *args
+          option = Option.new(name, image, price)
+        end
+        options << option
+        option
+      end
+
+      # Usage:
+      #
+      #     # List of names:
+      #     add_options("Name 1", "Name 2", ...)
+      #
+      #     # Arrays:
+      #     add_options([name, image, price], [name, image, price], ...)
+      #
+      #     # Hashes:
+      #     add_options({name: name, image: image, price: price}, ...)
+      #
+      #     # ProductAttribute::Option instances:
+      #     option_1 = ProductAttribute::Option.new(name, image, price)
+      #     add_options(option_1, ...)
+      #
+      def add_options(*args)
+        if args.length > 1
+          options = args.map {|arg| Array(arg)}
+        elsif args.first.respond_to?(:each)
+          options = args.first
+        else
+          raise ArgumentError, "options must be an Array of ProductAttribute::Option"
+        end
+
+        options.each do |option|
+          if option.kind_of?(Hash)
+            name = option.fetch(:name)
+            image = option.fetch(:image, nil)
+            price = option.fetch(:price, nil)
+            add_option(name, image, price)
+
+          elsif option.kind_of?(Array)
+            name, image, price = *option
+            add_option(name, image, price)
+
+          elsif option.kind_of?(Option)
+            add_option(option)
+
+          else
+            raise ArgumentError, "#{option} is not a valid ProductAttribute::Option"
+          end
+        end
+      end
+
+      # Convert display_as to integer for BC, raises ArgumentError
+      # if input cannot be mapped to a valid integer. The following
+      # symbols are accepted:
+      #
+      # * :dropdown = 5
+      # * :checkbox = 6
+      # * :radio    = 7
+      def self.normalize_display_as(display_as)
+        if display_as.kind_of?(Symbol)
+          case display_as
+          when :dropdown
+            5
+          when :checkbox
+            6
+          when :radio
+            7
+          else
+            raise ArgumentError, "display_as must be :dropdown, :checkbox, or :radio"
+          end
+        elsif ![5, 6, 7].include?(display_as)
+          raise ArgumentError, "display_as must be 5, 6, or 7"
+        else
+          display_as
+        end
+      end
+
+    end
+
+  end
+end

data/lib/business_catalyst/csv/product_row.rb

@@ -0,0 +1,110 @@
+# encoding: utf-8
+module BusinessCatalyst
+  module CSV
+
+    # Subclass and call #map to set values for columns. You may return
+    # arrays for columns that take multiple values, like catalog,
+    # and true/false for boolean columns.
+    #
+    # nil will always be interpreted as blank.
+    #
+    # == What method name to use?
+    #
+    # Refer to the COLUMNS constant, but in general use the
+    # underscored name of the column, with '?' appended to columns
+    # that expect a boolean.
+    #
+    # == Example
+    #
+    #   class MyRow < BusinessCatalyst::CSV::ProductRow
+    #
+    #     def initialize(product)
+    #       @product = product
+    #       super
+    #     end
+    #
+    #     map(:product_code) { @product.code }
+    #     map(:name)         { @product.name }
+    #     map(:catalog)      { ["Some", "Accessories"] }
+    #     map(:enabled?)     { @product.active }
+    #     map(:inventory_control?) { false }
+    #
+    #     # ... (other properties here)
+    #   end
+    #
+    # Later, with a CSV opened for writing:
+    #
+    #   csv << MyRow.headers
+    #   products.each do |product|
+    #     csv << MyRow.new(product).to_a
+    #   end
+    #
+    class ProductRow < Row
+
+      def self.columns
+        COLUMNS
+      end
+
+      # [Header, method, default, transformer]
+      COLUMNS = [
+        ["Product Code", :product_code, nil, ProductCodeTransformer],
+        ["Name", :name],
+        ["Description", :description],
+        ["Small Image", :small_image, nil, URITransformer],
+        ["Large Image", :large_image, nil, URITransformer],
+        ["Catalog", :catalog, [], CatalogTransformer], # Can be an array of path names, or an array of arrays of path names (multiple catalogs)
+        ["Sell Price", :sell_price, nil, CurrencyTransformer],
+        ["Recommended Retail Price", :recommended_retail_price, nil, CurrencyTransformer],
+        ["Tax Code", :tax_code],
+        ["SEO friendly URL", :seo_friendly_url],
+        ["Grouping Product Codes", :grouping_product_codes, nil, ArrayTransformer],
+        ["Grouping Product Descriptions", :grouping_product_descriptions, nil, ArrayTransformer],
+        ["Supplier CRM ID", :supplier_crm_id],
+        ["Supplier Commission Percentage", :supplier_commission_percentage],
+        ["Weighting/Order", :weighting_order],
+        ["Related Products", :related_products, [], ArrayTransformer],
+        ["Weight In KG/Pounds", :weight_in_kg_or_pounds],
+        ["Product Width (Previously Volume)", :product_width],
+        ["Keywords", :keywords],
+        ["Unit Type", :unit_type],
+        ["Min Units", :min_units],
+        ["Max Units", :max_units],
+        ["In Stock", :in_stock],
+        ["On Order", :on_order],
+        ["Re-order Threshold", :re_order_threshold],
+        ["Inventory Control", :inventory_control?, false, BooleanTransformer],
+        ["Can Pre-Order", :can_pre_order?, false, BooleanTransformer],
+        ["Custom 1", :custom_1],
+        ["Custom 2", :custom_2],
+        ["Custom 3", :custom_3],
+        ["Custom 4", :custom_4],
+        ["Poplets", :poplets, [], URIArrayTransformer],
+        ["Enabled", :enabled?, true, BooleanTransformer],
+        ["Capture Details", :capture_details?, false, BooleanTransformer],
+        ["Limit Download Count", :limit_download_count],
+        ["Limit Download IP", :limit_download_ip],
+        ["On Sale", :on_sale?, false, BooleanTransformer],
+        ["Hide if Out of Stock", :hide_if_out_of_stock?, false, BooleanTransformer],
+        ["Attributes", :attributes, nil, ProductAttributesTransformer],
+        ["Gift Voucher", :gift_voucher?, false, BooleanTransformer],
+        ["Drop Shipping", :drop_shipping?, false, BooleanTransformer],
+        ["Product Height", :product_height],
+        ["Product Depth", :product_depth],
+        ["Exclude From Search Results", :exclude_from_search_results?, false, BooleanTransformer],
+        ["Product Title", :product_title],
+        ["Wholesale Sale Price", :wholesale_sale_price, nil, CurrencyTransformer],
+        ["Tax Code", :tax_code],
+        ["Cycle Type", :cycle_type],
+        ["Cycle Type Count", :cycle_type_count],
+        ["Product URL", :product_url],
+        ["Product Affiliate URL", :product_affiliate_url],
+        ["Variations Enabled", :variations_enabled?, false, BooleanTransformer],
+        ["Variations Code", :variations_code],
+        ["Variation Options", :variations_options],
+        ["Role Responsible", :role_responsible],
+        ["Product Meta Description", :product_meta_description]
+      ]
+
+    end
+  end
+end