Welcome to django SHOP’s documentation!¶

Installation¶

• Install from pypi

pip install django-shop

• Add 'shop' to your INSTALLED_APPS
• Add the shop to your urls.py

(r'^shop/', include('shop.urls')),

Defining your products¶

The first thing a shop should do is define its products to sell. While some other shop solutions do not require you to, in django SHOP you must write a django model (or a set of django models) to represent your products.

Roughly, this means you’ll need to create a django model subclassing shop.models.Product, add a Meta class to it, and register it with the admin, just like you would do with any other django model.

More information can be found in the How to create a product section.

Shop rules: cart modifiers¶

Cart modifiers are simple python objects that encapsulate all the pricing logic from your specific shop, such as rebates, taxes, coupons, deals of the week...

Creating a new cart modifier is an easy task: simply create a python object subclassing shop.cart.cart_modifiers_base.BaseCartModifier, and override either its get_extra_cart_item_price_field() or its get_extra_cart_price_field(), depending on whether your “rule” applies to the whole cart (like taxes for example) or to a single item in your cart (like “buy two, get one free” rebates).

Theses methods receive either the cart object or the cart item, and need only return a tuple of the form (description, price_difference).

More in-depth information can be found in the How to create a Cart modifier section.

Shipping backends¶

Payment backends¶

More plugins?¶

You can find more plugins or share your own plugin with the world on the django SHOP website

Lots of functionality in django SHOP was left to implement as plugins and extensions, checking this resource for extra functionality is highly recommended before starting a new project!

Installation¶

Here’s the 1 minute guide to getting started with django SHOP.

1. Create a normal Django project (we’ll call it myshop for now):

   django-admin startproject example
   cd example; django-admin startapp myshop
   

2. You’ll want to use virtualenv:

   virtualenv . ; source bin/activate
   pip install south
   pip install django-shop
   pip install jsonfield
   

3. Go to your settings.py and configure your DB like the following, or anything matching your setup:

   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.sqlite3',
           'NAME': 'test.sqlite',
           'USER': '',
           'PASSWORD': '',
           'HOST': '',
           'PORT': '',
       }
   }
   

4. Add the following stuff to middlewares:

   MIDDLEWARE_CLASSES = [
       'django.middleware.common.CommonMiddleware',
       'django.contrib.sessions.middleware.SessionMiddleware',
       'django.middleware.csrf.CsrfViewMiddleware',
       'django.contrib.auth.middleware.AuthenticationMiddleware',
       'django.contrib.messages.middleware.MessageMiddleware',
   ] # <-- Notice how it's a square bracket (a list)? It makes life easier.
   

5. Obviously, you need to add shop and myshop to your INSTALLED_APPS too:

   INSTALLED_APPS = [
       'django.contrib.auth',
       'django.contrib.contenttypes',
       'django.contrib.sessions',
       'django.contrib.sites',
       'django.contrib.messages',
       # Uncomment the next line to enable the admin:
       'django.contrib.admin',
       # Uncomment the next line to enable admin documentation:
       'django.contrib.admindocs',
       'polymorphic', # We need polymorphic installed for the shop
       'south',
       'shop', # The django SHOP application
       'shop.addressmodel', # The default Address and country models
       'myshop', # the project we just created
   ]
   

6. Make the urls.py contain the following:

   from shop import urls as shop_urls # <-- Add this at the top
   
   # Other stuff here
   
   urlpatterns = patterns('',
       # Example:
       #(r'^example/', include('example.foo.urls')),
       # Uncomment the admin/doc line below to enable admin documentation:
       (r'^admin/doc/', include('django.contrib.admindocs.urls')),
       # Uncomment the next line to enable the admin:
       (r'^admin/', include(admin.site.urls)),
       (r'^shop/', include(shop_urls)), # <-- That's the important bit
       # You can obviously mount this somewhere else
   )
   

7. Most of the stuff you’ll have to do is styling and template work, so go ahead and create a templates directory in your project:

   cd example/myshop; mkdir -p templates/myshop
   

8. Lock and load:

   cd .. ; python manage.py syncdb --all ; python manage.py migrate --fake
   python manage.py runserver
   

9. Point your browser and marvel at the absence of styling:

   x-www-browser localhost:8000/shop
   

You now have a running but very empty django SHOP installation.

Adding a custom product¶

Having a shop running is a good start, but you’ll probably want to add at least one product class that you can use to sell to clients!

The process is really simple: you simply need to create a class representing your object in your project’s models.py. Let’s start with a very simple model describing a book:

from shop.models import Product
from django.db import models

class Book(Product):
    # The author should probably be a foreign key in the real world, but
    # this is just an example
    author = models.CharField(max_length=255)
    cover_picture = models.ImageField(upload_to='img/book')
    isbn = models.CharField(max_length=255)

    class Meta:
        ordering = ['author']

Like a normal Django model, you might want to register it in the admin interface to allow for easy editing by your admin users. In an admin.py file:

from django.contrib import admin

from models import Book

admin.site.register(Book)

That’s it!

Adding taxes¶

Adding tax calculations according to local regulations is also something that you will likely have to do. It is relatively easy as well: create a new file in your project, for example modifiers.py, and add the following:

import decimal

from shop.cart.cart_modifiers_base import BaseCartModifier

class Fixed7PercentTaxRate(BaseCartModifier):
    """
    This will add 7% of the subtotal of the order to the total.

    It is of course not very useful in the real world, but this is an
    example.
    """

    def get_extra_cart_price_field(self, cart, request):
        taxes = decimal.Decimal('0.07') * cart.subtotal_price
        to_append = ('Taxes total', taxes)
        return to_append

You can now use this newly created tax modifier in your shop! To do so, simply add the class to the list of cart modifiers defined in your settings.py file:

SHOP_CART_MODIFIERS = ['myshop.modifiers.Fixed7PercentTaxRate']

Restart your server, and you should now see that a cart’s total is dynamically augmented to reflect this new rule.

You can implement many other types of rules by overriding either this method or other methods defined in BaseCartModifier.

Cart¶

Renders information about the Cart object. This could be used (for example) to show the total amount of items currently in the cart on every page of your shop.

{% load shop_tags %}
{% cart %}

Order¶

Renders information about an Order object.

{% load shop_tags %}
{% order my_order %}

Product¶

Renders information about all active products in the shop. This is useful if you need to display your products on pages other than just product_list.html.

{% load shop_tags %}
{% products %}
{% products object_list %}

Filters¶

{{ product.get_price|priceformat }}

Order¶

The shop.order_signals module defines signals that are emitted during the checkout process

Running tests¶

It’s important to run tests before committing :)

pip install django django_polymorphic django-classy-tags

Community¶

Most of the discussion around django SHOP takes place on IRC (Internet Relay Chat), on the freenode servers in the #django-shop channel.

We also have a mailing list and a google group:

http://groups.google.com/group/django-shop

Code guidelines¶

• Like most projects, we try to follow PEP 8 as closely as possible
• Most pull requests will be rejected without proper unit testing
• Generally we like to discuss new features before they are merged in, but this is a somewhat flexible rule :)

Sending a pull request¶

We use github for development, and so all code that you would like to see included should follow the following simple workflow:

• Clone django-shop
• Checkout your fork
• Make a feature branch (to make pull requests easier)
• Hack hack, Test test, Commit commit, Test test
• Push your feature branch to your remote (your fork)
• Use the github interface to create a pull request from your branch
• Wait for the community to review your changes. You can hang out with us and ask for feedback on #django-shop (on freenode) in the mean time!
• If some changes are required, please commit to your local feature branch and push the changes to your remote feature branch. The pull request will be updated automagically with your new changes!
• DO NOT add unrelated commits to your branch, since they make the review process more complicated and painful for everybody.

More information can be found on Github itself: http://help.github.com/send-pull-requests/

Create a model¶

The first step for you is to create a model to use as a product. We will create an example Book model together:

from shop.models import Product
from django.db import models

class Book(Product):
    isbn = models.CharField(max_length=255)
    class Meta: pass

The following fields are already defined in the Product superclass:

class shop.models.Product¶

name¶

The name/title of the product

slug¶

The slug used to refer to this product in the URLs

active¶

Products flagged as not active will not show in the lists

date_added¶

The date at which the product was first created

last_modified¶

A timestamp of when the product was last modified

unit_price¶

The base price for one item

Create a template¶

Like other objects in Django, you will need to create a template to display your model’s contents to the world.

By default, your Product subclass will use the shop/product_detail.html template as a fallback, but will use your own template if you follow Django’s naming conventions: appname/book_detail.html.

That’s all there is to it :)

Using your newly created Product¶

Your product should behave like a normal Django model in all circumstances. You should register it in admin (and create an admin class for it) like a normal model.

Code wise, the following options are possible to retrieve your newly created model:

# This gets your model's instance the normal way, you get both your model's
# fields and the Product fields
o = MyProduct.objects.get(pk=...)

# This is also possible - You retrieve a MyProduct instance, using the
# Product manager
o = Product.objects.get(pk=...)

Product variations¶

By design, django SHOP does not include an out of the box solution to handling product variations (colors, sizes...) in order to let implementors create their own unrestricted solutions.

If you want such a pre-made solution for simple cases, we suggest you take a look at the shop_simplevariations “add-on” application.

Writing a simple cart modifier for the whole cart¶

Let’s assume you want to provide a discount of 10% off the cart’s total to clients that buy more than 500$ of goods.

This will affect the price of the whole cart. We will therefore override the get_extra_cart_price_field() method of shop.cart.cart_modifiers_base.BaseCartModifier:

from shop.cart.cart_modifiers_base import BaseCartModifier
from decimal import Decimal # We need this because python's float are confusing

class MyModifier(BaseCartModifier):
    """
    An example class that will grant a 10% discount to shoppers who buy
    more than 500 worth of goods.
    """
    def get_extra_cart_price_field(self, cart, request):
        ten_percent = Decimal('10') / Decimal('100')
        # Now we need the current cart total. It's not just the subtotal field
        # because there may be other modifiers before this one
        total = cart.current_total

        if total > Decimal('500'):
            rebate_amount = total * ten_percent
            rebate_amount = - rebate_amount # a rebate is a negative difference
            extra_dict = { 'Rebate': '%s %%' % ten_percent }
            return ('My awesome rebate', rebate_amount)
        else:
            return None # None is no-op: it means "do nothing"

    def get_extra_cart_item_price_field(self, cart, request):
        # Do modifications per cart item here
        label = 'a label'  # to distinguish, which modifier changed the price
        extra_price = Decimal(0)  # calculate addition cost here, can be a negative value
        extra_dict = {}  # an optional Python dictionary serializable as JSON
                         # which can be used to store arbitrary data
        return (label, extra_price, extra_dict)

Adding this cart modifier to your SHOP_CART_MODIFIERS setting will enable it, and you should be able to already test that your cart displays a rebate when the total for the order is over 500.

Shop interface¶

While we could solve this by defining a superclass for all payment backends, the better approach to plugins is to implement inversion-of-control, and let the backends hold a reference to the shop instead.

The reference interface for payment backends is located at

class shop.payment.api.PaymentAPI¶

Currently, the shop interface defines the following methods:

Backend interface¶

The payment backend should define the following interface for the shop to be able do to anything sensible with it:

Shop interface¶

While we could solve this by defining a superclass for all shipping backends, the better approach to plugins is to implement inversion-of-control, and let the backends hold a reference to the shop instead.

The reference interface for shipping backends is located at

class shop.shipping.api.ShippingAPI¶

Backend interface¶

The shipping backend should define the following interface for the shop to be able do to anything sensible with it:

Updating the whole cart¶

The normal form POST method is pretty straightforward - you simply POST to the cart’s update URL (shop/cart/update/ by default) and pass it parameters as: update_item-<item id>=<new quantity> Items corresponding to the ID will be updated with the new quantity

Emptying the cart¶

Posting to shop/cart/delete empties the cart (the cart object is the same, but all cartitems are removed from it)

@on_method decorator¶

This decorator can be wrapped around any other decorator. It should be used on functions that are members of classes and will ignore the first parameter self and regard the second parameter as the first instead. More information can be found here.

Usage:

from shop.util.decorators import on_method, shop_login_required

class PayOnDeliveryBackend(object):

    backend_name = "Pay On Delivery"
    url_namespace = "pay-on-delivery"

    [...]

    @on_method(shop_login_required)
    def simple_view(self, request):
        [...]

@shop_login_required decorator¶

This decorator does the same as Django’s @login_required decorator . The only difference is that it checks for the SHOP_FORCE_LOGIN setting. If that setting is False, login will not be required.

LoginMixin class¶

If you are using class based views for anything related to the shop you can use shop.util.login_mixin.LoginMixin to secure your views. More information on this can be found here. We are using a slightly modified version of that LoginMixin that makes sure to check for the SHOP_FORCE_LOGIN setting.

Usage:

class CheckoutSelectionView(LoginMixin, ShopTemplateView):
    template_name = 'shop/checkout/selection.html'

    [...]

Example¶

Extending the Product model in django SHOP works like this:

# In myproject.models
from shop.models_bases import BaseProduct
class MyProduct(BaseProduct):
    def extra_method(self):
        return 'Yay'

    class Meta:
        pass

# In your project's settings.py, add the following line:
SHOP_PRODUCT_MODEL = 'myproject.models.MyProduct'

From a django interactive shell, you should now be able to do:

>>> from shop.models import Product
>>> p = Product.objects.all()[0] # I assume there is already at least one
>>> p.extra_method()
Yay
>>> p.__class__
<class object's class>

Settings¶

All available settings to control model overrides are defined in General Settings

Deactivate the default addressmodel¶

Simple enough: just remove or comment the corresponding entry in your project’s INSTALLED_APPS:

INSTALLED_APPS = (
...
'shop', # The django SHOP
#'shop.addressmodel', # <-- Comment this out
...
)

Hook your own model to the shop¶

To achieve this, simply add a SHOP_ADDRESS_MODEL to your settings file, and give the full python path to your Address model as a value:

SHOP_ADDRESS_MODEL = 'myproject.somepackage.MyAddress'

Your custom model must unfortunately have the following two fields defined for the checkout views to work:

user_shipping = models.OneToOneField(User, related_name='shipping_address', blank=True, null=True)
user_billing = models.OneToOneField(User, related_name='billing_address', blank=True, null=True)

This is to ensure that the views take handle “attaching” the address objects to the User (or the session if the shopper is a guest).

We recommend adding the as_text() method to your address model. This ‘collects’ all fields and returns them in one string. This string will be saved to the order (to billing_address_text or shipping_address_text accordingly) during checkout view.

You are obviously free to subclass these views and hook in your own behavior.

Cart modifiers¶

Cart modifiers are plugins that modify the cart’s contents.

Rough categories could be discount modules or tax modules: rules for these modules are invariant, and should be “stacked”.

Example: “CDs are buy two get one free this month”, “orders over $500 get a 10% discount”

Shipping backends¶

Shipping backends differ from price modifiers in that there must be only one shipping backend selected per order (the shopper must choose which delivery method to use)

Shipping costs should be calculated on an Order object, not on a Cart object (Order instances are fully serialized in the database for archiving purposes).

Payment backends¶

Payment backends must also be selected by the end user (the shopper). Theses modules take care of the actual payment processing.

SHOP_PAYMENT_BACKENDS¶

A list (or iterable) of payment backend class paths. These classes will be used as the active payment backends by the checkout system, and so anything in this list will be shown to the customer for him/her to make a decision

SHOP_SHIPPING_BACKENDS¶

In a similar fashion, this must be a list of shipping backends. This list is used to display to the end customer what shipping options are available to him/her during the checkout process.

SHOP_CART_MODIFIERS¶

These modifiers function like the django middlewares. The cart will call each of these classes, in order, every time it is displayed. They are passed every item in the cart, as well as the cart itself.

SHOP_FORCE_LOGIN¶

If True, all views after the CartDetails view will need the user to be authenticated. An anonymous user will be redirected to your login url. Please read more on authentication in Django’s official authentication documentation . By default it’s set to False.

SHOP_PRICE_FORMAT¶

Used by the priceformat template filter to format the price. Default is '%0.2f'

SHOP_SHIPPING_FLAT_RATE¶

(Optional) The “flat rate” shipping module uses this to know how much to charge. This should be a string, and will be converted to a Decimal by the backend.

SHOP_CART_MODEL¶

(Optional) A python classpath to the class you want to replace the Cart model with. Example value: myproject.models.MyCartModel

SHOP_ADDRESS_MODEL¶

(Optional) A python classpath to the class you want to replace the shop.addressmodel.models.Address model with. See How to use your own addressmodel for a more complete example.

Example value: myproject.models.MyAddressModel

SHOP_ORDER_MODEL¶

(Optional) A python classpath to the class you want to replace the shop.models.Order model with.

Example value: myproject.models.MyOrderModel