The official Installation Instructions are accurate, and will definitely work to get a store running. However, I think that many developers would like some advice about how to best lay out the directories for ease of maintenance.

Go read those docs, but then come back here for a suggested layout.

Read it? Good, let’s get to my layout.

First, you need to make a basic project structure. I make one like so:

storename/
  __init__.py
  settings_local.py
  manage.py
  settings.py
bin/
  (here are various scripts you may use for testing or whatever)
etc/
   init.d/
       storename
       sysconfig/
           storename
fixtures/
localsite/
    __init__.py
    models.py
    templatetags/
        __init__.py
media/
    css/
    images/
    js/
templates/
    storename/

I don’t use any “manage.py” commands to make this outline. I just make the directories, copy the default satchmo settings.py and local_settings.py (renaming to settings_local.py, so that they sort nicely) to the base directory, and then use “touch” to make empty files for all the other files.

Configuring your urls

In your settings file, make your base urls file be the one in your localsite app. Like so:

ROOT_URLCONF = ‘storename.localsite.urls’

Then, in your storename/localsite/urls.py file, just import the base store urls like so:

from django.conf.urls.defaults import *
from satchmo.urls import urlpatterns

For now, that’s all you have to do, but later you’ll be able to add your own special site urls without any hassle or reconfiguration.

Configuring your templates

It is particularly important not to simply copy all of Satchmo’s templates into your template directory. I think that is the single biggest mistake beginning Satchmo developers make. Why? Because if we later upgrade Satchmo or change the templatetags, you won’t get the benefit of those changes.

Instead, simply copy the templates you need to override into your template directory, leaving all the rest to be found by Django’s template resolution functionality. See my article How to Skin a Satchmo Store – Overriding Templates for more details.

Install the localsite app

Having a custom app for any store is a great thing to do.

• It will allow you to have custom urls with ease
• You can add your own templatetags which are only useful for the particular store
• It provides a convenient place to register custom listeners for Satchmo signals.

Adding the “localsite” app is merely a matter of making the three files “__init__.py”, “models.py”, and “urls.py”, and then adding it to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = (
    [...]
    storename.localsite #should usually be last
)

Now you are ready

Now you are ready to continue with the official Satchmo install instructions, but your store will be much more flexible and ready to handle the real world.

Other tutorials

• SaltyCrane’s Satchmo Installation Notes

Updates

This article was written in 2008, but I am trying to keep this up to date, please comment below if you find something wrong or or which no longer makes sense.

10 July 2010: Updated, changing a few directory names, and updating links.

It is easy, dead easy, and requires just three lines of code and absolutely no hacking of the Satchmo core. It is all done through the magic of Django Signals.

In my Satchmo Video Presentation, I claimed that signals and templatetags were the key to extending Satchmo without having to build everything into the base store code. This is an example of doing just that.

The Signal

Satchmo sends a “satchmo.payment.signals.payment_form_init” signal when it is initializing payment forms. This gives any interested party the ability to modify the form before it ever gets sent to the template.

This signal can be used for all sorts of interesting purposes. For example, perhaps you want to removed “required” from some of the fields which are required by default. Or perhaps you want to hide certain fields (see payment.listeners.shipping_hide_if_one for an example of this). This signal is the key to doing anything like that.

The Listener

It isn’t a standard Django term, “listener,” but in Satchmo we generally call packages of functions which work with signals “listeners.” It makes sense, there is a signal, and a function who is interested in listening for that signal and acting upon it.

In satchmo.payment.listeners there is a function called “form_terms_listener.” This handy little function will add a new required “terms” field to any form. Exactly what we need!

Take a look at the function. It does require that you have a “shop_terms” named url somewhere in your urlconf. That’s the only prerequisite for its use.

Wiring them up

In my project layout article, I advise that you set up a “site” application for your shop. This is the most convenient place to wire custom signals to listeners. In your storename/site/models.py file, add the following:

from satchmo.payment.forms import SimplePayShipFormfrom satchmo.payment.listeners import form_terms_listenerfrom satchmo.payment.signals import payment_form_init

payment_form_init.connect(form_terms_listener, sender=SimplePayShipForm)

Adding the checkbox to the template

You’ll need to override the page where you are adding the checkbox. Refer to my how to skin a store article if you are unclear how to do this.

In your overridden form template, add the checkbox markup. Something like this:

{{ form.terms }} {{ form.terms.label }}{% if form.terms.error %}<br/>**{{ form.terms.error }}{% endif %}

Done!

Updated 10 July 2010: corrected imports for latest Satchmo

Basic Skinning

If you refer to my project layout article, you’ll see that I strongly suggest you set up a project directory with a “templates” directory in it. If you do that, then the key step is to make that directory the first priority when looking for a template file.

DIRNAME = os.path.dirname(__file__)

SATCHMO_DIRNAME = '/opt/framework/satchmo'TEMPLATE_DIRS = (os.path.join(DIRNAME, "templates"),os.path.join(SATCHMO_DIRNAME, "templates"),)

How it works

The way this works is that when Django goes looking for a template file, it looks in the template directories in the order you’ve given in that setting. Let’s say for example that you have two files: “product/product.html” and “base.html.”

If you have a project set up like this:

storename/templates/  (empty) satchmo/templates/  base.html  product/product.html

Django will look for product/product.html first at storename/templates/product. Since it isn’t there, it will look in satchmo/templates/product.html and find it. The product.html template extends base.html, so once again Django will look first in storename/templates, then successfully in satchmo/templates.

Overriding

Overriding the product template then becomes obvious. Just copy it to storename/templates/product and edit as you desire.

storename/templates/product/ product.htmlsatchmo/templates/  base.html  base_product.html

Once you’ve done this, Django will look in storename/templates/product and find product.html. It also needs base.html, and it will find it in satchmo/templates.

This works the same in every case. If you wanted to override the base account profile page, then you’d make a directory “contact” and copy or modify the default Satchmo file “contact/view_profile.html.”

Chris Moffitt and I made a technical presentation (view as a PDF) about Satchmo to a group of 50-70 developers on Saturday. It was videotaped for upload to YouTube, but doesn’t that the Google staff have uploaded it yet. I’ll be sure to make a post when that happens. (Update: Satchmo Video Presentation)

First Core Meeting

For the first time ever, the Satchmo core development team actually met face-to-face. The panels and discussions at DjangoCon made it completely worth my time and money to attend the convention, but even had they not been so useful, the trip would have been worth it just for the chance to meet and hang out with my fellow core developers.

We decided on our “Road to 0.8 release” strategy. We’re going to clean up the code & docs, closing as many tickets as possible in the next two or three weeks. In the meantime, Jag is going to be testing his shiny new Order Admin screens. When he’s ready, we’ll release!

The 0.8 release will be pinned to Django 1.0, making it much easier for us to tell people what version of Django to use. It is getting quite old to have to repeatedly specify “rev such-and-such” to new users on the Satchmo-Users list.

Initial 1.0 Discussion

Following 0.8, we’re going to work on a six-month release cycle, trying to fairly closely follow the Django Project’s newly announced intention to start doing timed releases.

We came up with quite a list of new or modified functionality we’d like to see in 1.0, but the primary driving force is going to be a very thorough and exciting refactor of the Product Model. Our intention is to make it much easier to allow store owners and developers to create products which exactly fit the specific needs of their store.