BusinessCatalyst
Tools for building CSV's for Adobe Business Catalyst e-commerce platform in Ruby. Use a Ruby DSL to turn your data into CSV's that can be imported in the BC admin. Supports product and catalog CSV's, and splitting large CSV's (over 10k products) into multiple files.
Compatible with Ruby 1.8.7 and Ruby 2.3+. Intended to be useful as a tool for migrating very old Rails sites, so we deliberately preserve Ruby 1.8 compatibility, even when it is a huge pain. Otherwise, we only maintain compatibility with the latest version because most sites that can run on 1.9 can be upgraded to 2.3 with much less effort.
Installation
Add this line to your application's Gemfile:
gem 'business_catalyst', '~> 0.1.2'
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. Refer to COLUMNS constant in the base class, or https://github.com/tortus/business_catalyst/wiki for a complete list of columns.)
Building a Product CSV
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
Refer to https://github.com/tortus/business_catalyst/wiki for the complete list of columns.
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.
# 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 10,000. However, you can get around this limit by importing multiple files. We have a class to help!
# 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.
Product Attributes
This gem has full support for multiple product attributes with multiple options. In your attributes column definition, create and return one or more instances of BusinessCatalyst::CSV::ProductAttribute.
class MyRow < BusinessCatalyst::CSV::ProductRow
map :attributes do
# Shorthand usage with no price differences or images
size = BusinessCatalyst::CSV::ProductAttribute.new("Size",
:display_as => :dropdown,
:required => true,
:keep_stock => false
)
size.add_options("Small", "Medium", "Large")
# Radio buttons with images and different prices for each option
color = BusinessCatalyst::CSV::ProductAttribute.new("Color",
:display_as => :radio,
:required => true,
:keep_stock => false
)
color.add_option("Red", "live/url/for/red.jpg", "US/25.0")
color.add_option("Green", "live/url/for/green.jpg", "US/22.0")
color.add_option("Blue", "live/url/for/blue.jpg", "US/26.0")
# Checkbox example without images
addon = BusinessCatalyst::CSV::ProductAttribute.new("Addon",
:display_as => :checkbox,
:required => false,
:keep_stock => false
)
addon.add_option("Some cool bling", nil, "US/5.00")
[size, color, addon]
end
end
Notes on Currency
You can always return prices as Ruby Numeric types, or a raw String in the format that BC understands: "US/10.00".
- If you ureturn a Ruby Numeric type, the "default currency" will be used.
- If you return a String, it will pass through "as-is".
- You can also return an array of Strings or numbers. These will be converted to the correct string format and joined with ";" allowing you to specify multiple prices.
# Be super-verbose if you want:
BusinessCatalyst::CSV::CurrencyTransformer.default_currency = "US"
# Or use the shorthand ProductRow class method:
default_currency "US"
map(:sell_price) { 10 }
# => "US/10.00"
map(:sell_price) { ["US/10", "EU/12"] }
# => "US/10.00;EU/12.00"
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Run tests:
bundle exec rspec spec
- Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request