How to Add a Powerful Blog to Your Ecommerce Site in Minutes

Spree Commerce is an e-commerce platform that provides a fully working interface for selling items online. It’s based on the Ruby programming language, and it comes with many features available out of the box.

In this article, I will show you how you can easily integrate your e-commerce platform built with Spree and a blog with the ButterCMS headless platform. Before we start, let me show you why you should consider such integration:

• With the usage of ButterCMS, you can provide your marketing team with an interface separate from the backend. 
• Using a headless CMS, you don’t have to worry about the database and the infrastructure behind your blog.
• You can easily migrate your blog to any other solution in the future without losing its contents or data.

I will start with creating a fresh installation of Spree Commerce and adding the code to hook up the ButterCMS API, and then start using the blog right away.

Step 1: Install Spree

I will use the Spree starter application, which is a minimal template with Spree Commerce pre-installed created with Docker. Before you continue, make sure that you have Docker installed in your system.

Download the archive from https://github.com/spree/spree_starter/archive/main.zip and unzip on your disk. Enter the directory with the files and run the following command to set up the application:

bin/setup

In most cases, the system needs 2 - 3 minutes to pull all the needed resources and install them in the system. Once this step is completed, you can load the test data using the following command:

docker-compose run web rake spree_sample:load

The platform is ready for testing. Visit http://localhost:3000 and click through the app and test products to ensure that everything is working as expected. After that, we can start integrating the ButterCMS API.

Step 2: Create a skeleton for the blog pages

We created a simple Ruby on Rails application with the Spree platform mounted as an engine in the previous step. Because of that architecture, we don’t have access to the views as we normally do in the Rails application. Before we modify the website layout and add the link to the blog, we have to generate the Spree views:

docker-compose run web bash
rails g spree:frontend:copy_storefront

The above command populated the app/views/spree directory with the platform views.

Creating the controller

Create the new controller file for our blog:

touch app/controllers/blogs_controller.rb

Our controller will consist of two actions: index and show. We will use the index action to display all blog posts and the show action to render specific blog posts.

Open the previously created controller file and put the following contents in there:

class BlogsController < Spree::StoreController
 def index

 end

 def show

 end
end

Notice that we inherit from the Spree::StoreController, not ApplicationController. Thanks to this, our blog page is an integral part of the platform.

I will start with the blank pages, add a link to the layout, and hook up ButterCMS when we ensure that the navigation works properly.

Creating views

The controller definition is ready, so we can add blank views:

mkdir app/views/blogs/
touch app/views/blogs/index.html.erb
touch app/views/blogs/show.html.erb

Updating routes

Our blog pages are not yet reachable, so we have to update the routes configuration. Open the config/routes.rb file and add the following line:

resources :blogs, only: %i[show index], path: 'blog'

The path “blogs” looks slightly weird, so I passed the path option with the custom singular name.

Now, we can access http://localhost:3000/blog and http://localhost:3000/blog/not-existing-post, and we will see blank pages in the platform layout. We are now ready to put some content there.

The last step regarding blog accessibility is to add a link in the menu. Open /app/views/spree/shared/_main_nav_bar.html.erb and add the new element to the menu list:

<li>
 <%= link_to "Blog", blogs_path, class: 'nav-link main-nav-bar-item main-nav-bar-category-button' %>
</li>

Step 3: Configure your ButterCMS account

Visit https://buttercms.com/ and create a new account if you don’t have one. Sign in and visit the settings page - https://buttercms.com/settings/.

The “Read API token” is the only thing we need to connect ButterCMS with our Spree platform effectively. Having that token, we can now install the ButterCMS gem in our application.

Step 4: Install the ButterCMS gem

Run the following command to add the gem to the Gemfile and install it in your system:

docker-compose run web bash
bundle add buttercms-ruby

We would need an initializer file that will save our ButterCMS API key at the application start. Create it:

touch config/initializers/butter_cms.rb

Put the following contents there:

ButterCMS::api_token = "YourToken"

Replace the “YourToken” placeholder with the API key present in the settings tab of your ButterCMS account. Remember not to store this token in the repository. It should be a secret credential not visible anywhere on the internet. One of the best ways to handle such sensitive data is to store them in the environment variables. For this article’s purpose, I will put the API key directly in the initializer.

We are now ready to add the blog listing page.

Step 5: Create blog listing page

Open BlogsController and add the following code to the index action so we can pull all posts from ButterCMS and pass them to the view:

@posts = ButterCMS::Post.all

Now, open app/views/blogs/index.html.erb and display the posts titles along with the link to the specific blog post:

<div class="container mb-3 d-md-flex">
 <div class="col-md-12 col-lg-9">
   <div class="row">
     <% @posts.each do |post| %>
       <div class="col-sm-4 col-6 mb-3 mb-md-4 pr-sm-0 pr-md-0 pl-md-4 pl-sm-4">
         <div class="product-component-name">
           <%= post.title %>
         </div>
         <div class="product-component-price">
           <%= link_to('Read more', blog_path(id: post.slug)) %>
         </div>
       </div>
     <% end %>
   </div>
 </div>
</div>

I reused styles from the product listing, but feel free to add your own styles to make the blog listing page look even better.

The last step is to implement a single blog post page.

Step 6: Create blog post page

Open the show action in the BlogsController and add the following line:

@post = ButterCMS::Post.find(params[:id])

We can now access the post object in the view and display it the same way we would show records in an ordinary Ruby on Rails application.

Open app/views/blogs/show.html.erb view and add the following code there:

<div class="container pt-4 product-details">
 <div class="row">
   <div class="col-12 col-md-5">
     <div id="product-description">
       <h1 class="mt-3 mt-md-0 text-center text-md-left product-details-title">
         <%= @post.title %>
       </h1>
     </div>
   </div>
   <div class="pb-4 pt-md-5 row">
     <%= @post.body.html_safe %>
   </div>
 </div>
</div>

To be more consistent with the platform style we can also add breadcrumbs at the top of the page:

<div class="container">
 <nav id="breadcrumbs" class="col-12 mt-1 mt-sm-3 mt-lg-4">
   <ol class="breadcrumb">
     <li class="breadcrumb-item">
       <%= link_to('/') do %>
         <span>Home</span>
       <% end %>
       <span itemprop="item" itemscope="itemscope" itemtype="https://schema.org/Thing" itemid="/"></span>
     </li>
     <li class="breadcrumb-item">
       <%= link_to(blogs_path) do %>
         <span>Blog</span>
       <% end %>
       <span itemprop="item" itemscope="itemscope" itemtype="https://schema.org/Thing" itemid="/"></span>
     </li>
     <li class="breadcrumb-item">
       <%= link_to(blog_path(id: @post.slug)) do %>
         <span><%= @post.title %></span>
       <% end %>
     </li>
   </ol>
</div>

Summary

We just created a fully working blog in minutes. Thanks to the headless CMS approach with ButterCMS, we could separate the logic between the blog engine and the e-commerce platform.

If you have a marketing team, they can work on the blog posts without worrying about access to the platform or asking developers for help. Such an approach saves time and it's very flexible.

Adding a blog is not the only possibility for extending your platform with an e-commerce CMS such as ButterCMS. You can easily add other pages, hook them up in seconds, and then forget about any of the technical stuff.