1. Django-SHOP Tutorial

This tutorial is aimed at people new to django-SHOP but already familiar with Django. If you aren’t yet, reading their excellent Django Tutorial is highly recommended.

Since django-SHOP relies on many features offered by django-CMS and Django REST Framework, you should familiarize yourself with these apps.

1.1. Introduction

Django-SHOP is an e-commerce framework rather than a turn-key solution. This means that the merchant is in charge of the project and that django-SHOP acts as one of the third party dependencies making up the whole project. We name this the merchant implementation.

The merchant implementation contains everything which makes up its fully customizable project, such as:

  • The main configuration file, settings.py.
  • The URL-routing entry point, usually urls.py.
  • Optionally, but highly recommended: Django models to describe the products sold by the merchant.
  • If required, extended models for the Cart and Order.
  • An administration interface to manage entities from all those models.
  • Special Cart modifiers to calculate discounts or additional costs.
  • Order workflows to handle all the steps how an order is processed.
  • Apphooks for integrating Django-Views into django-CMS.
  • Custom filters to restrict the rendered set of products according to their properties.
  • Form definitions, if they differ from the built-in defaults.
  • HTML snippets and their cascading style sheets, if they differ from the built-in defaults.

This approach allows a merchant to implement every desired extra feature, without having to modify any code in the django-SHOP framework itself. This however requires to add some custom code to the merchant implementation itself. Since we don’t want to do this from scratch, we can use a prepared cookiecutter template to bootstrap our first project. Please follow their instructions for setting up a running demo.

This cookiecutter template is shipped with 3 distinct product models, which are named commodity, smartcard and polymorphic. Depending on their need for internationalization, they are subdivided into a variant for a single language and one with support for translated product properties. Which one of them to use, depends on the merchant requirements. When answering the questions, asked by the cookiecutter wizard, consider to:

1.2. Installation

Before installing the files from the project, ensure that your operating system contains these applications:

Install some additional Python applications, globally or for the current user:

pip install --user pipenv cookiecutter autopep8

Then change into a directory, usually used for your projects and invoke:

cookiecutter https://github.com/awesto/cookiecutter-django-shop

You will be asked a few question. If unsure, just use the defaults. This creates a directory named my-shop, or whatever you have chosen. This generated directory is the base for adopting this project into your merchant implementation. For simplicity, in this tutorial, it is referred as my-shop. Change into this directory and install the missing dependencies:

cd my-shop
pipenv install --sequential
npm install

This demo shop must initialize its database and be filled with content for demonstration purpose. Each of these steps can be performed individually, but for simplicity we use a Django management command which wraps all these command into a single one:

pipenv run ./manage.py initialize_shop_demo

Finally we start the project, using Django’s built-in development server:

pipenv run ./manage.py runserver

Point a browser onto http://localhost:8000/ and check if everything is working. To access the backend at http://localhost:8000/admin/ , log in using username admin with password secret.


The first time, django-SHOP renders a page, images must be thumbnailed and cropped. This is an expensive operation which runs only once. Therefore please be patient, when loading a page for the first time.

1.3. Overview

What you see here is a content management system consisting of many pages. By accessing the Django administration backend at Home › django CMS › Pages, one gets an overview of the page-tree structure. One thing which immediately stands out is, that all pages required to build the shop, are actually pages, served by django-CMS. This means that the complete sitemap (URL structure) of a shop, can be reconfigured easily to the merchants needs.

1.4. Adding pages to the CMS

If we want to add pages to the CMS which have not been installed with the demo, we must sign in as a Django staff user. If our demo has been loaded through one of the prepared fixtures, use user admin with password secret. After signing in, a small arrow appears on the top right in our browser. Clicking on that arrow expands the Django-CMS toolbar.


Click on the menu item named example.com and select Pages …. This opens the Django-CMS Page Tree. In django-SHOP, every page, can be rendered by the CMS. Therefore, unless we need a special landing page, we can start immediately with the Catalog’s List View of our products.

Click on New Page to create a new Page. As its Title choose whatever seems appropriate. Then change into the Advanced Settings at the bottom of the page. In this editor window, locate the field Template and choose the default.

Change into Structure mode and locate the placeholder named Main Content, add a Container-plugin, followed by a Row-, followed by one or more Column-plugins. Choose the appropriate width for each column, so that for any given breakpoint, the widths units sum up to 12. Below that column, add whatever is appropriate for that page. This is how in django-CMS we add components to our page placeholders.

The default template provided with the demo contains other placeholders. One shall be used to render the breadcrumb. By default, if no Breadcrumb-plugin has been selected, it shows the path to the current page. By clicking on the ancestors, one can navigate backwards in the page-tree hierarchy.

1.5. Next Chapter

In the next chapter of this tutorial, we will see how to organize the Catalog Views