One of the most common questions on the Satchmo-Users mailing list is “what layout should I use for my project files?”

Since Satchmo is so flexible, it can be installed in many ways, so there is no one perfect answer to this question. However, in my experience, 9 out of 10 new stores will benefit significantly in flexibility and upgradability by adopting the layout I’ll suggest in this article.

This is based on my real-world experience as a professional Satchmo developer. Every time I’ve been hired to come to the rescue of a site which can’t launch because it just isn’t working right, the problem has boiled down to an inflexible installation. In other words, this layout will save you time, frustration, and money.

The official Installation Instructions are accurate, and will definitely work to get a store running. However, I think it leads to an inflexible store, and one that is hard to upgrade properly.

Specifically, I skip every one of the steps suggested in the “Copy the rest of the required files” section. Copying the files means that you won’t get the benefit of updates without manually copying them again. This is not a good solution.

Definitely read those docs, but then come back here for a better 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
  local_settings.py
  manage.py
  settings.py
  bin/
    (here are various scripts you may use for testing or whatever) 
  etc/
    init.d/
      storename 
    sysconfig/ 
      storename 
  fixtures/
  site/
    __init__.py
    models.py
    templatetags/
      __init__.py 
  static/
    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 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 site app. Like so:

ROOT_URLCONF = ‘storename.site.urls’

Then, in your storename/site/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 use the “satchmo_copy_templates” command. I think that command is the single biggest mistake beginning Satchmo developers make. Why? Because it copies files as they were when you made the copy. If we later upgrade Satchmo or change the templatetags, you won’t get the benefit of those changes.

The better way to do it is to configure your template directories like this to your local_settings file.

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

You see? This way Django will look first in your storename/templates directory for templates, and then fall back to using the default Satchmo template. What this allows you to do is to copy only the templates you need to modify from the base Satchmo directory, and leave all the other ones alone. That way during an upgrade, you only need to modify/sync the ones you’ve copied.

Install the site 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 “site” 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.site #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.