This guide presents accumulated wisdom from person-years of Spree use.
endprologue.
rake spree:upgrade
will copy in any new “infrastructure” files, e.g. new configuration or javascript or
style files. It saves you from needing to run the spree command to get an empty project and then copying
changes across.
NOTE. currently this over-writes existing files, so be careful if you have experimental changes. (IDEA: use -b flag on the copies? it does help)
NOTE. Try to avoid modifying config/boot.rb and config/environment.rb: use initializers instead.
Be aware that core changes might have an impact on the components you have over-ridden in your project.
You might need to patch your local copies, or ensure that such copies interact correctly with changed
code (e.g. using appropriate ids in Html to allow the javascript to work).
If you can help us to generalise the core code so that your preferred effect is achieved by altering
a few parameters, then this is more useful than duplicating several files. Ideas and suggestions always
welcome.
INFO. The Spree Wiki contains a few scripts to automate some of the checking.
Initializers are run during startup, and are the recommended way to execute certain settings. You can
put initializers in extensions, thus have a way to execute extension-specific configurations.
See the extensions guide for more information.
Use rake spec and rake test to test basic functioning after you’ve made changes.
If you’re testing on a server, whether in production or development mode, the following code in one
of your FOO_extension.rb files might save some time. It triggers local behaviour for users who have
an admin role. One useful consequence is that uncaught exceptions will show the detailed error page
instead of 404.html, so you don’t have to hunt through the server logs.
Spree::BaseController.class_eval do
def local_request?
ENV["RAILS_ENV] != “production” || current_user.present? && current_user.has_role?(:admin)
end
end
To avoid having to restart the web server to see changes to SASS stylesheets, use
a compass watcher:
compass —watch —sass-dir path/to/sass —css-dir ./path/to/compiled
The compass watcher will compile any changed files and write them to the css-dir.
When editing my site extension’s sass, I use these paths, if you use the gem spree boot mode
it may be different for you:
compass —watch —sass-dir vendor/extensions/site/public/stylesheets/sass —css-dir ./public/stylesheets/compiled
Suppose there’s a few details of Spree that you want to over-ride due to personal or client preference,
but which aren’t the usual things that you’d over-ride (like views) – so something like tweaks to the
models or controllers.
You could hide these away in your site extension, but they could get mixed up with your real site
customizations. Your could also fork Spree and run your site on this forked version, but this can
also be a headache to get right. There’s also the hassle of tracking changes to railsdog/master and
pulling them into your project at the right time.
So here’s a compromise: have an extra extension, say spree-tweaks, to contain your small collection
of modified files, which is loaded first in the extension order. The benefits are: it’s clear what you
are over-riding, and easier to check against core changes; you can base your project on an official
gem release or a railsdog/master commit stage; such tweaks can become part of your client site project
and be managed with SCM etc.
If you find yourself wanting extensive changes to core, this technique probably won’t work so well.
But then again, if this is the case, then you probably want to look seriously at splitting some
code off into stand-alone extensions and then see whether any of the other code should be contributed
to the core.
Some of us use Git submodules
to tie large projects together: the basic Spree shell plus the
site/ extension is the main repository, and everything else is loaded in as a submodule,
including Spree itself. See this Spree-demo fork
for an example.
The basic command to set up a submodule is this. Call it for each of the submodules you need.
For Spree, you want to use the path vendor/spree.
git submodule add some_repo [-b branch] vendor/extension/some_ext
If your project is public, then you probably want to give the public version of your repo so
other people can use it without change. When I need to change a submodule in place, I add a
new remote with the proper url for changes to be pushed to.
The branch option is recommended (and you probably want to specify “master” most of the time).
On the first run, the following command fetches the submodule repositories into the nominated
directories.
git submodule update —init
git submodule foreach is very useful for managing your submodules, e.g. you can update all of them
with git submodule foreach “git pull”, or check for modifications with this
(the echo ok gets round a return-code issue):
git submodule foreach “git status || echo ok”
When pushing modifications, remember to check each of your repositories (with foreach above),
and then check in the main repository. Git tracks the last commit in each submodule and includes
this information in the main repository, hence allowing the right versions to be checked out
later.
NOTE: git foreach seems to be a recent addition, so you might need to update your installation of git.