jekyll-spree-client

Create shopping carts with Jekyll and Spree :)

This plugin provides integration between a Jekyll site and the Spree API. It allows to manage products from Jekyll posts and it will create them on the Spree Store when they don't exist and keep prices and stock synchronized.

A note on money and currency formatting

Earlier versions of spree-api-client would be sending prices as strings, making Spree try to convert them from a localized version. Since it changed to sending data as JSON, Spree doesn't have to do this conversion unless you store prices as strings.

You can use Integer and Floats now!

Installation

Add this line to your site's Gemfile:

gem 'jekyll-spree-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-spree-client

Usage

Add the plugin to your _config.yml:

plugins:
- jekyll-spree-client
spree:
  sku_field: sku
  api_url: http://localhost:3000
  shipping_category_id: 1
  store: https://your.store

You can get the API key on your user profile. Pass it as the SPREE_API_KEY environment variable so you don't store it on your site.

SPREE_API_KEY="some random value generated by spree" bundle exec jekyll build

Since v0.1.4 you can pass the API URL too, and it'll take precedence over _config.yml:

SPREE_URL="https://your-store.tienda.sutty.nl"

Posts

Add the required fields in their frontmatter:

---
layout: post
title: A product
description: With a description
sku: A unique ID
price: 100.00
cost_price: 50.0
stock: 100
weight: 100
height: 100
width: 100
depth: 100
---

The layout doesn't matter, but we recommend to use a layout for products.

Layouts

You'll need four layouts and at least a corresponding post, one for each step of the buying process.

  • cart the cart, shows the order details
  • shipment shipping and billing addresses, shipping rates apply here
  • payment select payment methods
  • confirmation order confirmation page

They'll be available on Liquid under the site.STEP keys.

Hooks

If you need to do some data manipulation before and after synchronization is done, you can use hooks. In a _plugins/spree.rb file:

Jekyll::Hooks.register :spree, :pre_render do |spree|
  spree.local_products.each do |product|
    product.data['_description'] = product.data['description']
    product.data['description'] = product.data['productore']&.data&.dig('title')
  end
end

Jekyll::Hooks.register :spree, :post_render do |spree|
  spree.local_products.each do |product|
    product.data['description'] = product.data.delete '_description'

    product.data.delete 'description' unless product.data['description']
  end
end

This plugin gets the description value from another document (they're linked using jekyll-linked-posts, it's a real example!), and then recovers it.

  • pre_render runs just before starting synchronization
  • post_render run after synchronization and before writing changes

Building the site

During site build, the plugin will communicate with the Spree API and create products when they don't exist or locally update their price, current stock and the other values.

Some fields will appear on the frontmatter:

variant_id: 1
in_stock: true
errors:
  time: 2020-10-10 00:00:00 UTC
  messages:
  - Something went wrong

  • variant_id is the ID in the Spree database.

  • in_stock is true or false according to availability (Spree decides this).

  • errors if the synchronization fails there will be a timestamp and some messages here.

Notes

  • Synchronization follows this rules.

If the product doesn't exist on Spree, it's created.

If it does, the Jekyll document is updated with price, weight, dimensions and stock.

It means once the product is created on Spree, Spree manages this variables.

But Product properties like description and metadata are updated from Jekyll to Spree.

We want this to change in the near future but we need to think a way to prevent conflicts.

  • All products are created as "master variants" on Spree. There will be no pictures, taxonomies or other values, only basic product information.

  • The stock field is the initial stock, afterwards it will only be updated from the Spree store. If you want to add more stock, update the stock on the location, not on the post. We want this to change in the future.

  • Stock is added to the default stock location, meaning the first active one. The API doesn't show or allows to query the actual default.

  • price and cost_price are expressed in Spree's default currency.

  • If you install the jekyll-write-and-commit-changes plugin it will save the data back to disk when you build. Using the JEKYLL_ENV=production environment variable will also commit changes to git.

  • Check the shipping category ID on Spree, since there's no API for it, you need to provide it manually, default is 1.

Contributing

Bug reports and pull requests are welcome on 0xacab.org at https://0xacab.org/sutty/jekyll/jekyll-spree-client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Sutty code of conduct.

If you like our plugins, please consider donating!

License

The gem is available as free software under the terms of the GPL3 License.

Code of Conduct

Everyone interacting in the jekyll-spree-client project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.