Though Satchmo includes a number of versatile product types, many projects have needs that are best met by creating a custom product module. A custom product module is a module with a product model which deviates from the normal behavior of Satchmo.
To work with custom product modules, you will need a basic understanding of Django apps, projects, and templates. You should understand the default behavior of Satchmo before trying to customize it.
In a custom product module, most of the work is done in the models.py and template files. You will also need an admin.py file and a config.py file. This section contains several example files that you can add to a new or existing app and extend.
A basic models.py file with a custom product model looks like this:
from django.db import models
from django.utils.translation import ugettext_lazy as _
from product.models import Product
class MyNewProduct(models.Model):
product = models.OneToOneField(Product, verbose_name=_('Product'),
primary_key=True)
def _get_subtype(self):
return 'MyNewProduct'
def __unicode__(self):
return u"MyNewProduct: %s" % self.product.name
class Meta:
verbose_name = _('My New Product')
verbose_name_plural = _('My New Products')
This is the corresponding admin.py file. This file is needed to make your models visible in Django’s admin app. Make sure that you replace my_app with the name of your app:
from django.contrib import admin
from models import MyNewProduct # TODO: Replace app name!
admin.site.register(MyNewProduct)
The config.py file tells Satchmo about your product model. Replace my_app here too:
from django.utils.translation import ugettext_lazy as _
from livesettings import config_get
PRODUCT_TYPES = config_get('PRODUCT', 'PRODUCT_TYPES')
# TODO: Replace app name!
PRODUCT_TYPES.add_choice(('my_app::MyNewProduct', _('My New Product')))
Once you’ve created the above three files in your app, you have all the code necessary to use your new product model in Satchmo. All that’s left is the configuration.
You can now use the new product model in the same way that you would use one of Satchmo’s default product types. You will find an “Add MyNewProduct” link in the “Product Subtypes” section of each product’s admin page.
A product model is a Django model with a OneToOneField to satchmo.product.models.Product and a _get_subtype method. You may add new fields and behavior as you would with any other Django model.
When Satchmo renders a product page, it looks for a template named product/detail_productname.html (in all lowercase). If the template is not found, Satchmo uses the base_product.html template.
As an example, say you are using MyNewProduct from the previous example and you want to extend it to display a special title on the product’s page. First, you would add a CharField named title to the existing model and to the table in your database (or just drop the table and run syncdb). Then, create a template named product/detail_mynewproduct.html with the following content:
{% extends "base_product.html" %}
{% block title %}{{ product.mynewproduct.title }}{% endblock title %}
If you create a MyNewProduct and view its page in the store, the page will have the title you assigned it in the admin app. Notice that the MyNewProduct is accessed as an attribute of product.
For more examples, look at product/models.py, templates/base_product.html, and templates/product/ in the Satchmo source code.
This document should get you started in customizing Satchmo through the product model. If you need help with something discussed here or with more advanced topics, feel free to ask the mailing list.
There is another possibility for extending the product model using model inheritance. You can find more information in the first installment of the Satchmo Diaries.
Finally, if you create a product model that others may find useful, please consider contributing it to the Satchmo community.