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
andcost_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 theJEKYLL_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 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.