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.

Related posts:

1. Wordsmith 2.0 released
2. Deploying Spree using Heroku
3. Getting Started with Spree 0.30.1 Customizations

Here is a guide on how I got a fresh install of Spree running on Heroku rails hosting.

Setting the stage

I will assume ruby, rails, gems and git are all installed.

gem install spree
spree <app-name>
cd <app-name>
git init
git add .
git commit -m "initial commit"
heroku create

References: Heroku QuickStart | Spree Getting Started

I created a .gitignore file, it is not a requirement, to exclude certain local files that are created during development, such as sqlite3 or db files, log and tmp directories and even the product images.

Heroku gem manifest

Heroku has many gems already installed on their servers and is even more up to date than other hosts. However, Spree has many gem dependencies. To resolve this you create a gem manifest that is placed in the RAILS_ROOT, name the file .gems. I have gone ahead and copied my gem manifest that is necessary for Spree 0.9.2 gem to gist and is pasted below.

# .gems
activemerchant --version 1.4.1
activerecord-tableless --version '>= 0.1.0'
calendar_date_select --version 1.15
chronic --version '>= 0.2.3'
tlsmail --version 0.0.1
rspec --version '>= 1.2.9'
rspec-rails --version '>= 1.2.0'
will_paginate --version '>= 2.3.11'
authlogic --version '>= 2.0.11'
compass --version 0.8.17
stringex
whenever
spree --version 0.9.2

Based on the manifest I have created and the events over the summer of github no longer hosting gems we need to edit the environment.rb file. Three lines in question need the gem name and source changed to match the new gemcutter.org hosting.

#config/environment.rb
config.gem 'stringex', :lib => 'stringex', :source => "http://gemcutter.org"
config.gem 'whenever', :lib => false, :source => 'http://gemcutter.org'
config.gem 'will_paginate', :version => '~> 2.3.11', :lib => 'will_paginate', :source => 'http://gemcutter.org'

Heroku read only

Heroku is a read-only filesystem. This means that many new gems and other application features are limited. One such case is the use of SASS for stylesheets. In Spree the stylesheets are now compiled at runtime. Instead of looking at reworking Spree there is an easier option. The engineers at Heroku responded in the last few months with a plugin to allow SASS to work on Heroku. Simply add this to your spree application.

script/plugin install git://github.com/heroku/sass_on_heroku.git

The Heroku read only filesystem comes into play again. Spree uses the rails :cache feature for javascript and stylesheets. This is talked about some on the Spree-user google group. The simplest solution is to remove the :cache from the tags in the layouts.

Additionally Heroku allows commands such as heroku rake db:migrate to be run. This is very helpful but there are limitations. Heroku does not allow rake commands that require user input. This is covered in the Heroku Rake Docs. For Spree this is a problem because of the rake db:admin:create or rake db:bootstrap tasks used to setup the database. I came up with a solution to create a new task.

Both the :cache tag and the db:admin:create issues are addressed by a forked version of the extension spree-heroku. See the spree heroku extension code on my github repository. You can install it as an extension or take the ideas and add them to your site extension.

script/extension install git://github.com/tonkapark/spree_heroku.git

A admin_user.yml file is created in the extension config directory. You can leave it be or edit it for the different environments. It doesn’t matter because Spree allows users to change their email and passwords once logged in.

Spree Heroku extension disclosure

I want to disclose that I know my version of the heroku extension is incomplete for full production use. My version does not address the image storage issue that is covered in the original version of the extension. There are two reasons really. First I believe there is a solution that is more Spree extension like than previously done. And second I have not yet setup Amazon S3 account. I will address this shortly but wanted to get this information out right away.

In case you are interested the method for the image override belongs in your site_extension or heroku_extension.rb file. Here is a sample of how to override the default styles and sizes for paperclip in a spree extension inside the def activate block.

Image.attachment_definitions[:attachment][:styles] = {
:mini => '48x48>', :small => '100x100>', :grid => '268x268>',:product => '240x240>', :large => '600x600>'}

Preparing to deploy spree to heroku

Spree comes with a few default preferences. One is to set SSL on in production. In Heroku you have to add SSL as an add-on. There is actually a free option but you have to submit your credit card for verification of identity and to allow you to upscale if needed. So be default Heroku won’t have SSL. This is a quick fix, with 3 lines added to the site_extension.rb file in vendor/extensions/site/ in the activate method.

#site_extension.rb
def activate
  AppConfiguration.class_eval do
    preference :allow_ssl_in_production, :boolean, :default => false
  end
end

Deploy to Heroku

git add . && git commit -m "heroku setup"
git push heroku master
heroku rake db:migrate
heroku rake db:seed

These quick steps will add all the files to your local git repository, push them to your new heroku app, create the production database and seed the default values in the database.

Next is the custom task created in the spree-heroku extension that will create your admin user.

heroku rake heroku:db:admin:create

Finally you are ready to launch your application.

heroku open

I am going to continue working on this and should have an update to the heroku extension that addresses the image storage as I believe it should be. Also I will be working to deploy some other extensions and will possibly write up any future complications.

Related posts:

1. Building Wordsmith, a Spree Extension
2. Stuck a fork in Clearance by Thoughtbot
3. Getting Started with Spree 0.30.1 Customizations

Creating a theme

A big part of the redesign with wordpress is simply creating a custom theme. There are hundreds of howto’s when it comes to wordpress theme development, I will not attempt to go into details here.

The key points in the theme development are creating individual page templates. This can be done by creating files with the name format of page-templatename.php.

<?php
/*
Template Name: GrowthHome
*/
?>

A page template can then be assigned when creating a new page in wordpress. This allows the Portfolio page to look different than the services page or the about page. I am actually using a Page template for my blog index page instead of the index.php default page.

Different Sinlge Page by Category

Another trick many developers are using with wordpress is to add a conditional statement to the single.php file in the theme. This file then selects a custom named file of your liking to display.

<?php
$post = $wp_query->post;
if ( in_category('29') ) {
include(TEMPLATEPATH . '/single-portfolio.php');
} else {
include(TEMPLATEPATH . '/single-blog.php');
}
?>

This simple block allows my portfolio item posts to be displayed completely different than my individual blog posts. A handy trick indeed when working with WordPress as a CMS.

Short Urls

Something new I added to the site was a feature that several other websites now have and is becoming more common due to services like twitter. Many of the times when using twitter you have to shorten a url to fit your character limit. I have used bit.ly for url shortening but I don’t like having to use a third party domain to mask the actual endpoint when my domain is the one in question. I want to build name recognition and have trust in my links. So rather than using a plugin or a fancy solution to create my short urls and use hashes I took a simple approach that I believe to be pratical and elegant.

I changed the WordPress permalink structure from the previous /%year%/%month%/%postname%/ to /%post_id%/%postname%/. This change required no coding on my part, the previous links continued to redirect to the new structure and I get my short urls by cutting off the postname. I am not sure if there are any flaws to this approach yet but my existing links on twitter, my new links and my short urls all work. Using the All in One SEO plugin each of my pages is given a canonical link tag in the head section so the search engines will be able to index the full url even if the short url is used to link to my pages.

Giving WordPress its Own Directory

Finally to have the root of my website clear of all the wordpress php files I left the wordpress install in a folder (/blog) and followed the easy steps to copy the htaccess and index.php to the root so that you can have the front page outside of the wordpress directory. The steps are on the wordpress codex pages and linked from within the WordPress Admin General Options

So those are the basic steps I took to setup wordpress to take over control of my website. I am sure there are plenty more steps I can take but for what I need this works.

Related posts:

1. Easy steps to deploy WordPress using Capistrano
2. Creating a Big Cartel and WordPress Integration Plugin
3. Deployed Client WordPress Site to Production