Tonka Park

Building Wordsmith, a Spree Extension

• short url: http://tonkapark.com/331 | 1 Comment »

Spree is an open source e-commerce solution written with ruby on rails. I recently chose Spree to use for a project building out a new website. Spree is robust in features and functionality but it does not cover everything. Several basic features I wanted to include were static content and a blog with comments. Spree claims to be a flexible and extensible platform and so far I believe that claim.

Here is a quick summary guide of how I built a new spree extension, Wordsmith. Wordsmith adds blogging functionality to your Spree site, with features such as comments and rss feeds.

Spree Wordsmith

There are options to use other rails projects or wordpress with Spree or even the existing spree-blog extension. I tried the existing extension but it was lacking functionality that I thought should be included. Rather than forking the existing extension I started from scratch building my own blog engine inside spree named Wordsmith.

Creating the Spree extension

There is great documentation offered up by the Spree developers on how to create the extension so I will just summarize the steps I took. The first step once Spree is installed is to run the extension generator to get the default folder structure in the extension directory.

script/generate extension

Creating a model or controller is just as easy. You can either copy your code over from a previous rails project or start from scratch with the extension generators.

script/generate extension_model  <extension-name> <model-name> column_name:data_type
script/generate extension_controller <extension-name> <controller-name>

Don’t forget to run rake db:migrate to get your database up to date after you edit your migration files.

Spree extension class

The trick to the setup takes place in the _extension.rb file found in the root of the extension folder. You can include your dependent gems, add links to the Admin toolbar, add fields to the user forms, make your helpers available to all views, set/create app configuration preferences, and extend controller and model classes. I found that with at least two different gems you sometimes will have to include the setup from the gem init.rb file in the activate method inside your extension class. Not sure what causes this to be required but it happened with the subdomain_fu and formtastic gems. You can read this thread regarding a gem failing to load in a spree extension.

Spree AppConfiguration

In Wordsmith I created new AppConfiguration preferences to be used by my new code. Settings such as posts per page, default post status and also the slug used for the blog home path. These preferences can even be changed from inside the app if you include a view. I have provided a view to display the preferences and allow editing of those that do not require an app restart.

Extension initializers

Just like with other rails projects you can include your own initializers files in the provided extension config/initializers directory. These will get picked up when your application is loaded.

Overriding Spree core

The most useful part of Spree extensions is you can quickly and easily override any existing functionality or views. Simple add in your extension the file with the same path and name as the file in the core you want to override. In most cases this will be for customizing views but you can also easily change behavior if you choose. For Spree Wordsmith I did not have to override anything, but I have been working on an override for the entire admin section that I may make public if it works out.

I was very brief in my walkthrough since the documentation is very capable of getting you through most the setup. You can view the source code for spree-wordsmith at my github repository. Read more about Spree extensions at the Spree documentation page.

An additional extension that I have found useful, and might integrate into Wordsmith is spree-static-content by Peter Berkenbosch.