Foxycart Helpers

Several helpers for working with FoxyCart in plain Ruby (several Rails helpers are included too but Rails isn't required):

• Webhook endpoint for Datafeeds - https://wiki.foxycart.com/v/2.0/transaction_xml_datafeed
• HMAC Product Verification - https://wiki.foxycart.com/v/2.0/hmac_validation
• Link href builder (with support for Product Verification)
• Generation of the store loader.js Javascript URL and HTML.

Add this line to your application's Gemfile:

gem 'foxycart_helpers'

And then execute:

$ bundle

Or install it yourself as:

$ gem install foxycart_helpers

The datafeed endpoint defaults to '/foxycart_processor'. If your app is at https://example.com/ then you should set your datafeed URL in FoxyCart to https://example.com/foxycart_processor

ENV['FOXYCART_API_KEY'] should be set to your FoxyCart API key (available from the FoxyCart Admin area).

ENV['FOXYCART_URL'] should be set to your store URL.

Or you can override/set these in configuration:

# In an appropriate initializer e.g. /config/initializers/foxycart.rb
FoxycartHelpers.configure do |config|
  config.mount_point = '/some/other/path'
  config.api_key = 'foobarbat'
  config.url = 'https://example.foxycart.com/'
  config.auto_encode_hrefs = true # automatically use product verification on generated hrefs
end

This helper creates a Rack endpoint to receive a POSTed XML data feed, it:

• Automatically URL decodes the POST.
• Decrypts with your API key ENV['FOXYCART_API_KEY']
• Parses the XML and presents it as a hash.

Rack/Sinatra:

  # config.ru
  require 'foxycart_helpers/middleware'
  use Foxycart::Middleware

Rails: This middleware is registered automatically.

Then:

FoxycartHelpers.subscribe do |payload|
  puts payload
  # Do something with payload
  # You probably want to fire a background task
end

In Rails this could live at config/initalizers/foxycart.rb

This helper HMAC encodes values for use with the Product Verification feature of FoxyCart, it:

• Encodes with your API key ENV['FOXYCART_API_KEY']

• Can return both full string for direct replacement of existing names and values or just the hash.

• Includes Rails view helpers.

• code = Product code (sku123)

• name = Value of name field in the HTML (name)

• value = Value (or initial value) of the input etc (Cool Example)

See the FoxyCart docs for more information on code, name and value.

Standalone:

FoxycartHelpers::ProductVerification.encode code, name, value
# => "54a534ba0afef1b4589c2f77f9011e27089c0030a8876ec8f06fca281fedeb89"
FoxycartHelpers::ProductVerification.encoded_name code, name, value
# => "name||54a534ba0afef1b4589c2f77f9011e27089c0030a8876ec8f06fca281fedeb89"

Rails:

In your views:

<%= foxycart_encode 'sku123', 'name', 'Cool Example' %>
# => "54a534ba0afef1b4589c2f77f9011e27089c0030a8876ec8f06fca281fedeb89"
<%= foxycart_encoded_name 'sku123', 'name', 'Cool Example' %>
# => "name||54a534ba0afef1b4589c2f77f9011e27089c0030a8876ec8f06fca281fedeb89"

Creates cart HREFs (encoded or plain) given for a store URL ENV['FOXYCART_URL'].

Params are:

• name (required always)
• price (required always)
• code (required if product validation is used)
• opts a hash, supported values here: https://wiki.foxycart.com/v/2.0/cheat_sheet

Standalone:

# plain
FoxycartHelpers::Link.href 'Cool Example', '10', nil, { color: 'red' }
# => "https://example.foxycart.com/cart?name=Cool+Example&price=10&color=red"

# encoded (switched on in config)
FoxycartHelpers::Link.href 'Cool Example', '10', 'sku123', { color: 'red' }
=> "https://example.foxycart.com/cart?name=Cool%20Example||54a534ba0afef1b4589c2f77f9011e27089c0030a8876ec8f06fca281fedeb89&price=10||a36dd6bcf3587676c9926d389c87cda3bf0033e6c40e0cc7124edc38409f16a9&code=sku123||dc2a524b987ee5e18af483c1a9e2d333f50eae7d8ed417b8b39442dff4c3ab82&color=red||a81b7a17e4f142ae99678fba7e479734785914953a07a42a0dbd44e145775ae9"

Rails:

In your views:

<%= foxycart_url_for('Cool Example', '10', 'sku123') %>
# => "https://example.foxycart.com/cart?name=Cool+Example&price=10&color=red"
<%= link_to 'Click the Link', foxycart_url_for('Cool Example', '10', 'sku123') %>
# => "<a href=\"https://example.foxycart.com/cart?name=Cool+Example&price=10&color=red\">Click the Link</a>"

FoxyCart's required Javascript. Always linked as HTTPS. Available as just the URL and HTML element. Inferred from your configured store URL.

Standalone:

FoxycartHelpers::Javascript.url
# => "https://cdn.foxycart.com/example/loader.js"

FoxycartHelpers::Javascript.html_element
# => "<script src=\"https://cdn.foxycart.com/example/loader.js\" async defer></script>"

Rails:

Helper for use in your layout or relevant pages:

<%= foxycart_loader_js %>
# => "<script src=\"https://cdn.foxycart.com/example/loader.js\" async defer></script>"

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/rjocoleman/foxycart_helpers.

The gem is available as open source under the terms of the MIT License.