Starting a new store - real world project layout

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.

Added on October 6, 2008
22 Comments

Comments

#1

StJohn commented, on Oct. 22, 2008 at 8:49 a.m.:

Hi Bruce, following your tutorial above you say to create the directories and files for a new satchmo project as described. Under ‘configuring your urls’ you state ‘edit your /site/urls.py like so’ but your instructions do not say to create this file…. Have I missed something?

thanks, St.john

#2

Stjohn commented, on Oct. 22, 2008 at 11:22 a.m.:

Hi Bruce, if you create the files by hand what about the contents of manage.py?

many thanks, Stjohn

#3

sym links to django commented, on Oct. 22, 2008 at 11:37 a.m.:

Hi Bruce, running through your tutorial the way you suggested leaves you with a project that is not sym linked to python site packages and hence django i.e. the project is not on the python path and can not find django. Maybe this is just my setup but I thought I would let other people know who are following this and maybe having a problem.

Would it not be better to create the new store with django-admin.py and add all the other files and dirs as you suggested by hand?

many thanks, Stjohn

#4

StJohn commented, on Oct. 22, 2008 at 12:18 p.m.:

Hi Bruce, hope you don’t mind all the questions! Can I ask you about:

SATCHMO_DIRNAME = ‘/opt/framework/satchmo’

are you copying all the satchmo working files into this location and then sym linking them to ../site-packages?

many thanks, Stjohn

#5

StJohn commented, on Oct. 22, 2008 at 4:51 p.m.:

Hi Bruce, following your tutorial creating the ‘site/’ directory causes the project to stop working with the following message:

ImportError: No module named django.core.management

Any ideas why? Also should there also be a urls.py file in this directory?

many thanks, Stjohn

#6

wayne commented, on Oct. 25, 2008 at 9:46 a.m.:

hi, i was wondering what the exact contents (or what to put in them) of the following files should be:

urls.py

and the files mentioned in this statement:

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:

because when i run: python manage.py satchmo_check according to the official install directions: “Test and Install the Data” i get errors….

Any help would be greatly appreciated, thanks!

#7

david commented, on Oct. 30, 2008 at 11:55 a.m.:

For SATHCHMO_DIRNAME I do this:

from distutils.sysconfig import get_python_lib
SATCHMO_DIRNAME = os.path.join(get_python_lib(), ‘satchmo’)

This allows me to have different locations for site-packages between my development and production servers and avoid hard coding a value.

#8

Bruce commented, on Nov. 18, 2008 at 2:33 p.m.:

@david.

Good tip. Thanks

#9

Bruce commented, on Nov. 18, 2008 at 2:37 p.m.:

@wayne

If you don’t need to override anything yet, then the best thing to put in “urls.py” would be just the line:

from satchmo.urls import urlpatterns

That way you can easily add your own urlpatterns from there.

#10

Steve commented, on Nov. 26, 2008 at 4:23 p.m.:

In #7, for any of us new to python as well as new to satchmo, … the word ‘satchmo’ should be in single quote marks, not the ‘ character that david used. Great tip though!

from distutils.sysconfig import get_python_lib SATCHMO_DIRNAME = os.path.join(get_python_lib(), ‘satchmo’)

#11

zach commented, on Dec. 6, 2008 at 11:21 a.m.:

Thanks, I like the idea

#12

wayne commented, on Dec. 28, 2008 at 8:10 p.m.:

hi,

using your code given above in local_settings.py:

DIRNAME = os.path.dirname(__file__) SATCHMO_DIRNAME = ‘/opt/framework/satchmo’ TEMPLATE_DIRS = ( os.path.join(DIRNAME, “templates”), os.path.join(SATCHMO_DIRNAME, “templates”), )

should allow the app, like in the layout you suggested above, to reference the default satchmo template, and actually, the demo store template, from in the /opt/satchmo-trunk/satchmo directory even if the storename/template/storename is an empty directory, right?

i am running the satchmo demo shop on apache, and the demo shop page is showing but without any page layout, and i have used the directory setup you suggested above. i would figure that the code you gave above would work to allow the app to find the demo template, but it doesnt seem to.

so, now i ran “satchmo_copy_templates” and now the demo shop is showing laid out as it should be. But i shouldn’t have to run this command right?

also, as a separate issue, the images aren’t showing in the demo shop even when i run “python manage.py satchmo_copy_static” do you know what could be causing this?

the:

MEDIA_ROOT = os.path.join(DIRNAME, ‘static/’)

MEDIA_URL = ‘/static/’

thanks

#13

wayne commented, on Dec. 28, 2008 at 8:11 p.m.:

hi,

using your code given above in local_settings.py:

DIRNAME = os.path.dirname(__file__) SATCHMO_DIRNAME = ‘/opt/framework/satchmo’ TEMPLATE_DIRS = ( os.path.join(DIRNAME, “templates”), os.path.join(SATCHMO_DIRNAME, “templates”), )

should allow the app, like in the layout you suggested above, to reference the default satchmo template, and actually, the demo store template, from in the /opt/satchmo-trunk/satchmo directory even if the storename/template/storename is an empty directory, right?

i am running the satchmo demo shop on apache, and the demo shop page is showing but without any page layout, and i have used the directory setup you suggested above. i would figure that the code you gave above would work to allow the app to find the demo template, but it doesnt seem to.

so, now i ran “satchmo_copy_templates” and now the demo shop is showing laid out as it should be. But i shouldn’t have to run this command right?

also, as a separate issue, the images aren’t showing in the demo shop even when i run “python manage.py satchmo_copy_static” do you know what could be causing this?

the:

MEDIA_ROOT = os.path.join(DIRNAME, ‘static/’)

MEDIA_URL = ‘/static/’

thanks

#14

Bruce commented, on Dec. 30, 2008 at 9:30 a.m.:

OK, you have two issues:

  1. You need to make sure the MEDIA_URL is resolving. By default, Satchmo will turn on a local http server for your static files if you have LOCAL_DEV=True in your settings or local_settings file.
  2. You don’t have to copy all the templates, but to run the sample store, you’ll need to copy at least the contents of satchmo/static to your store’s static directory.
#15

Joe commented, on Jan. 13, 2009 at 3:59 p.m.:

Hi Bruce — I really like the idea of your more flexible layout. When I tried it, I ran into an issue: css and js files are loading from the MEDIA_ROOT just fine but images are not found because an absolute URL is being appended to the MEDIA_ROOT name.

Here’s the messages from the server…

[13/Jan/2009 15:53:37] “GET /store/ HTTP/1.1” 200 3561 [13/Jan/2009 15:53:37] “GET /static/css/style.css HTTP/1.1” 304 0 [13/Jan/2009 15:53:37] “GET /static//home/joe/Satchmo/kiosk/static/images/productimage-picture-default_t85.jpg HTTP/1.1” 404 1958

Any ideas?

Thanks!

#16

Joe commented, on Jan. 13, 2009 at 5:19 p.m.:

A little more info about my difficulty: i) the weird url doesn’t happen with the ‘official’ install ii) the weird url only appears when trying to load the ‘no image’ placeholder image. When I upload an image for the product, it displays just fine.

Should I file a ticket?

Thanks again.

#17

Terry L. commented, on Feb. 14, 2009 at 6:08 a.m.:

@Joe

Hi Joe… in case you check back here:

I had the same ‘problem’ with the Photo Not Available image not showing.

It was fixed by running _syncdb_ again. The db must have it’s url set at that stage for the placeholder.

#18

Stanislaus Madueke commented, on March 13, 2009 at 1:26 a.m.:

Since I don’t have satchmo installed in my python site-packages directory, get_python_lib() doesn’t work for me. Instead I do this:

import os
import satchmo

SATCHMO_DIR = os.path.abspath(os.path.dirname(satchmo.__file__))
TEMPLATE_DIRS = (..., os.path.join(SATCHMO_DIR, 'templates',))

Right now, I have satchmo checked out at d:\svnroot\satchmo, and I use a .pth file to point at this location. I find it’s easier to update this way (svn up satchmo).

Maybe someone else’ll find this useful…

#19

Dane Hesseldahl commented, on April 13, 2009 at 1:51 p.m.:

I would not use the name ‘site’ as your faux satchmo app name.

In Django 1.0.2 it caused me major problems for me - it should NOT be named “site” and it should be different than the base project name.

#20

Benjamin Bach commented, on April 27, 2009 at 7:30 a.m.:

Why does the satchmo world insist on calling it ‘static/’ ?? Everyone else calls it ‘media’. Please, it’s not a good idea to invent your own naming schemes, just for the heck of it.

And I don’t see the motivation for bin, etc and site directories. By eg. splitting templates from template tags, you get a new loading structure. And who wants to correct every other Django app out there to comply with this satchmo structure?

Satchmo came up with copy_static, copy_templates and delete_all_db commands… stuff that’s really dangerous and unnecessary. I don’t get it.

What I quickly started to think when I played around with the examples was, “boy, I need to keep this in a separate project”.. because it simply looks like an integration nightmare. Especially the part where your admin site runs wild with new models. Yup, a nice little sandbox for satchmo and no more worries. Then hopefully within a few releases, integration will be more straight-forward.

#21

H commented, on July 23, 2009 at 3:42 a.m.:

@Terry L thanks for that tip RE photo not available - i spent ages trying to figure out why this was happening!

#22

Babul commented, on Sept. 2, 2009 at 1:46 a.m.:

A much more sane description of how to do this http://www.saltycrane.com/blog/2008/12/card-store-project-3-installing-satchmo-part-2/

Also a quick script to help you install Satchmo (including dependencies) automatically http://groups.google.com/group/satchmo-users/browse_thread/thread/c86f2540ab14c49c

This PDF was good aid to help understand how to configure store/products http://cdn.bitbucket.org/chris1610/satchmo/downloads/Satchmo.pdf

Lastly, this article is 1 year old, is this still the best approach? Has someone not written a tool to create some default stores (ideally with a theme i.e. graphics/css/etc included) as most other ecommerce solutions have this e.g. I’ve now been looking into Magento (PHP) as a simpler to create/deploy/use solution and OFBiz (Java) as an alternative as it includes lots of backend accounting & inventory mgt tools and Satchmo has been a PAIN just to get built and started (and yes I am new to Django/Python but still managed to use other tools without one-tenth of the issues I face just to get Satchmo up).

Sorry for the rant, but IMHO serious focus needs to be applied to the documentation/usabilty of Satchmo.

Thx

Post a comment

Search


Resources

“The understanding and mastery that Bruce has of Satchmo and its underlying framework, Django is unparalleled. From server setup to expanding or adding new functionality in Satchmo, Bruce is your man!”
—Neum Schmickrath

Categories

Subscriptions