Merge branch 'releases/0.2'

Conflicts:
	oscar/__init__.py

README.rst

@@ -10,12 +10,19 @@ core functionality can be customised to suit the needs of your project.  This
 allows it to handle a wide range of e-commerce requirements, from large-scale B2C
 sites to complex B2B sites rich in domain-specific business logic.
 
-Oscar is used in production by:
+Case studies
+------------
 
-* Tata - http://www.landmarkonthenet.com
-* Carlsberg - Their global "We deliver more" platform is powered by Oscar.
+Oscar is still in active development, but is used in production by a range of
+companies, from large multinationals to small, boutique stores:
+
+* Tata Group - http://www.landmarkonthenet.com
+* Carlsberg - Their global "We Deliver More" platform is powered by Oscar (but
+  is a B2B site so it not browsable by the public).
 * Dolbeau - http://www.dolbeau.ca/
-* The UK Labour party
+* The UK Labour party - http://shop.labour.org.uk (will be live in early June)
+
+Many more on the way.
 
 This README is just a stub - see the following links for more details
 information:
@@ -23,6 +30,7 @@ information:
 * `Official homepage`_ 
 * `Demo site`_ (experimental) 
 * `Documentation`_ on `readthedocs.org`_
+* `Google Group`_ - the mailing list is django-oscar@googlegroups.com
 * `Continuous integration homepage`_ on `travis-ci.org`_
 * `Twitter account for news and updates`_
 * `Twitter account of all commits`_
@@ -37,10 +45,14 @@ information:
 .. _`travis-ci.org`: http://travis-ci.org/
 .. _`Twitter account for news and updates`: https://twitter.com/#!/django_oscar
 .. _`Twitter account of all commits`: https://twitter.com/#!/oscar_django
+.. _`Google Group`: https://groups.google.com/forum/?fromgroups#!forum/django-oscar
 
 Oscar was written by `David Winterbottom`_ (`@codeinthehole`_) and is developed
 and maintained by `Tangent Labs`_, a London-based digital agency.
 
+Oscar is released under the permissive `New BSD license`_.
+
 .. _`David Winterbottom`: http://codeinthehole.com
 .. _`@codeinthehole`: https://twitter.com/codeinthehole
 .. _`Tangent Labs`: http://www.tangentlabs.co.uk
+.. _`New BSD license`: https://github.com/tangentlabs/django-oscar/blob/master/LICENSE

docs/source/components.rst

@@ -1,16 +0,0 @@
-==========
-Components
-==========
-
-This section provides high-level descriptions of the main components of django-oscar.
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   components/offers
-   components/checkout
-   components/shipping
-   components/analytics
-   components/promotions

docs/source/contributing.rst

@@ -2,15 +2,69 @@
 Contributing
 ============
 
-* New features should be discussed on the mailing list (or in the meetings) before serious work starts
-* Pull requests will be rejected if sufficient tests aren't provided
-* Please update the documentation when altering behaviour or introducing new features 
+Some ground rules:
 
-Contents:
+* To avoid disappointment, new features should be discussed on the mailing list
+  (django-oscar@googlegroups.com) before serious work starts.
 
-.. toctree::
-   :maxdepth: 2
+* Pull requests will be rejected if sufficient tests aren't provided.
 
-   contributing/installation
-   contributing/testing
-   contributing/conventions
+* Please update the documentation when altering behaviour or introducing new features.
+
+* Follow the conventions (see below).
+
+Installation
+============
+
+From zero to tests passing in 2 minutes (most of which is PIL installing)::
+
+    git clone git@github.com:<username>/django-oscar.git
+    cd django-oscar
+    mkvirtualenv oscar
+    ./setup.py develop
+    pip install -r requirements.txt
+    ./run_tests.py
+
+Writing docs
+============
+
+There's a helper script for building the docs locally::
+
+    cd docs
+    ./test_docs.sh
+
+Conventions
+===========
+
+General
+-------
+
+* PEP8 everywhere while remaining sensible
+
+URLs
+----
+
+* List pages should use plurals, eg ``/products/``, ``/notifications/``
+
+* Detail pages should simply be a PK/slug on top of the list page, eg
+  ``/products/the-bible/``, ``/notifications/1/``
+  
+* Create pages should have 'create' as the final path segment, eg
+  ``/dashboard/notifications/create/``
+
+* Update pages are sometimes the same as detail pages (ie when in the
+  dashboard).  In those cases, just use the detail convention, eg
+  ``/dashboard/notifications/3/``.  If there is a distinction between the detail
+  page and the update page, use ``/dashboard/notifications/3/update/``.
+
+* Delete pages, eg /dashboard/notifications/3/delete/
+
+View class names
+----------------
+
+Classes should be named according to::
+
+    '%s%sView' % (class_name, verb)
+
+For example, ``ProductUpdateView``, ``OfferCreateView`` and
+``PromotionDeleteView``.  This doesn't fit all situations but it's a good basis.

docs/source/getting_started.rst

@@ -1,76 +1,171 @@
-===============
-Getting started
+============================
+Start building your own shop
+============================
+
+For simplicity, let's assume you're building a new e-commerce project from
+scratch and have decided to use Oscar.  Let's call this shop 'frobshop'
+
+.. tip::
+
+    You can always review the set-up of the `Sandbox site`_ in case you have
+    trouble following the below instructions.
+
+.. _`Sandbox site`: https://github.com/tangentlabs/django-oscar/tree/releases/0.2/sandbox
+
+Install by hand
 ===============
 
-Install using::
+Install oscar (which will install Django as a dependency), then create the
+project::
 
     pip install django-oscar
+    django-admin.py startproject frobshop
+
+This will create a folder ``frobshop`` for your project.
+
+Settings
+--------
+
+Now edit your settings file ``frobshop.frobshop.settings.py`` to specify a
+database (we use sqlite for simplicity)::
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.sqlite3',
+            'NAME': 'db.sqlite3',
+            'USER': '',
+            'PASSWORD': '',
+            'HOST': '',
+            'PORT': '',
+        }
+    }
+
+then add ``oscar.apps.basket.middleware.BasketMiddleware`` to ``MIDDLEWARE_CLASSES``, and
+set ``TEMPLATE_CONTEXT_PROCESSORS`` to::
+
+    TEMPLATE_CONTEXT_PROCESSORS = (
+        "django.contrib.auth.context_processors.auth",
+        "django.core.context_processors.request",
+        "django.core.context_processors.debug",
+        "django.core.context_processors.i18n",
+        "django.core.context_processors.media",
+        "django.core.context_processors.static",
+        "django.contrib.messages.context_processors.messages",
+        'oscar.apps.search.context_processors.search_form',
+        'oscar.apps.promotions.context_processors.promotions',
+        'oscar.apps.checkout.context_processors.checkout',
+        'oscar.core.context_processors.metadata',
+    ) 
+
+Next, modify ``INSTALLED_APPS`` to be a list, add ``South`` and append Oscar's core apps::
 
-then add::
+    from oscar import get_core_apps
+    INSTALLED_APPS = [
+        'django.contrib.auth',
+        ...
+        'south',
+    ] + get_core_apps()
 
-    'oscar.apps.basket.middleware.BasketMiddleware'
+and set your auth backends to::
 
-to ``MIDDLEWARE_CLASSES``, and::
+    AUTHENTICATION_BACKENDS = (
+        'oscar.apps.customer.auth_backends.Emailbackend',
+        'django.contrib.auth.backends.ModelBackend',
+    )
 
-    'oscar.apps.promotions.context_processors.promotions',
-    'oscar.apps.checkout.context_processors.checkout',
+to allow customers to sign in using an email address rather than a username.
 
-to ``TEMPLATE_CONTEXT_PROCESSORS``.  Next, add the following apps
-to your ``INSTALLED_APPS``::
+Oscar currently uses Haystack for search so you need to specify::
 
-    'oscar',
-    'oscar.apps.analytics',
-    'oscar.apps.discount',
-    'oscar.apps.order',
-    'oscar.apps.checkout',
-    'oscar.apps.shipping',
-    'oscar.apps.order_management',
-    'oscar.apps.catalogue',
-    'oscar.apps.catalogue.reviews',
-    'oscar.apps.basket',
-    'oscar.apps.payment',
-    'oscar.apps.offer',
-    'oscar.apps.address',
-    'oscar.apps.partner',
-    'oscar.apps.customer',
-    'oscar.apps.promotions',
-    'oscar.apps.reports',
-    'oscar.apps.search',
-    'oscar.apps.voucher',
+    HAYSTACK_SITECONF = 'oscar.search_sites'
+    HAYSTACK_SEARCH_ENGINE = 'dummy'
 
-Add::
+The last addition to the settings file is to import all of Oscar's default settings::
 
     from oscar.defaults import *
 
-to your ``settings`` module and run::
+URLs
+----
+
+Alter your ``frobshop/urls.py`` to include Oscar's URLs::
+
+    from django.conf.urls import patterns, include, url
+    from oscar.app import shop
+
+    urlpatterns = ('',
+        (r'', include(shop.urls))
+    )
+
+Database
+--------
+
+Then create the database and the shop should be browsable::
+
+    python manage.py syncdb --noinput
+    python manage.py migrate
+
+You should now have a running Oscar install that you can browse.
+
+
+Install using Tangent's boilerplate django project
+==================================================
+
+The easiest way to get started is to use Tangent's `template django project`_
+although it is tailored to an Agency structure which may not suit everyone.
+
+.. `template django project`: https://github.com/tangentlabs/tangent-django-boilerplate
+
+Set up a virtualenv, and create a new project using the ``startproject``
+management command::
+
+    mkvirtualenv frobshop
+    pip install Django
+    django-admin.py startproject frobshop \
+        --template=https://github.com/tangentlabs/tangent-django-boilerplate/zipball/master 
 
-    python manage.py syncdb
+This will create a folder ``frobshop`` which is an entire templated project that
+follows Tangent's conventions.  The structure is:
 
-to create the database tables.
+    frobshop/
+        docs/
+        www/
+            conf/
+            deploy/
+            public/
+            static/
+            templates/
+            manage.py
+            settings.py
+            settings_test.py
+            urls.py
+            urls_oscar.py
+        README.rst
+        fabconfig.py
+        fabfile.py
+        deploy-to-test.sh
+        deploy-to-stage.sh
+        deploy-to-prod.sh
 
+Replace a few files with Oscar-specific versions::
 
-Demo shop
----------
+    mv frobshop/www/urls{_oscar,}.py
+    mv frobshop/www/deploy/requirements{_oscar,}.py
+    mv frobshop/www/conf/default{_oscar,}.py
 
-A demo shop is in preparation at the moment and will be available soon.
+Install dependencies::
 
-Real shop
----------
+    cd frobshop/www
+    pip install -r deploy/requirements.txt
 
-Sadly, setting up an e-commerce store is never trivial as you would like.  At a
-minimum, you'll have to consider the following questions:
+Create database::
 
-* How are shipping charges calculated?
-* How are products organised into categories?
-* How are stock messages determined?
-* How is payment taken at checkout?
-* How are orders fulfilled and managed?
-* How is stock and inventory updated?
+    python manage.py syncdb -noinput
+    python manage.py migrate
 
-Much of the documentation for oscar is organised as recipes that explain
-how to solve questions such as those above:
+And that should be it.
 
-* :doc:`recipes/how_to_customise_an_app`
-* :doc:`recipes/how_to_customise_models`
-* :doc:`recipes/how_to_override_a_core_class`
+Next steps
+==========
 
+The next step is to implement the business logic of your domain on top of
+Oscar.

docs/source/index.rst

@@ -2,38 +2,60 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-==================================================
-django-oscar - Domain-driven e-commerce for Django
-==================================================
+.. image:: http://img94.imageshack.us/img94/9094/oscarza.jpg
 
-django-oscar is an e-commerce framework for Django designed for building
+===================================
+Domain-driven e-commerce for Django
+===================================
+
+Oscar is an e-commerce framework for Django designed for building
 domain-driven applications.  It is structured so that the core business objects
-(eg the models for a product/basket/order etc) can be customised to suit the
-domain at hand.  In this way, your application can accurately model its domain,
-making feature development and maintenance much easier.
+can be customised to suit the domain at hand.  In this way, your application
+can accurately model its domain, making feature development and maintenance
+much easier.
 
-This is in contrast to alternative e-commerce frameworks which use meta-data and
-key-value tables to model a domain.
+Features:
 
-Oscar is developed by `Tangent Labs`_, a London-based digital agency.  It is used in
-production in several applications to sell everything from beer mats to ipads.
+* Any product type can be handled, including downloadable products,
+  subscriptions, variant products (eg a T-shirt in different sizes and colours).
 
-.. _`Tangent Labs`: http://www.tangentlabs.co.uk
+* Customisable products, such as T-shirts with personalised messages.
 
-The `source is on Github`_. 
+* Can be used for large catalogues - Oscar is used in production by sites with
+  more than 20 million products.
 
-.. _`source is on Github`: https://github.com/tangentlabs/django-oscar
+* Multiple fulfillment partners for the same product.
+
+* Range of merchandising blocks for promoting products throughuout your site.
+
+* Sophisticated offers that support virtually any kind of offer you can think
+  of - multibuys, bundles, buy X get 50% of Y etc
+
+* Vouchers
 
-Table of contents
------------------
+* Comprehensive dashboard
+
+* Support for split payment orders
+
+* Extension libraries available for PayPal, GoCardless, DataCash and more
+
+Oscar is developed by `Tangent Labs`_, a London-based digital agency.  It is
+used in production in several applications to sell everything from beer mats to
+ipads.  The `source is on Github`_. 
+
+.. _`Tangent Labs`: http://www.tangentlabs.co.uk
+.. _`source is on Github`: https://github.com/tangentlabs/django-oscar
 
 .. toctree::
    :maxdepth: 2
 
+   take_a_peek
    getting_started
-   customisation
+   key_questions
    recipes
+   design_decisions
    reference
+   contributing
 
 Indices and tables
 ==================

docs/source/introduction_to_ecommerce.rst

@@ -1,95 +0,0 @@
-================
-eCommerce domain
-================
-
-When building an e-commerce site, there are several components whose
-implementation is strongly domain-specific.  That is, every site will have
-different requirements for how such a component should operate.  As such, these components
-cannot easily be modelled using a generic system - no configurable system will be able
-to accurately capture all the domain-specific behaviour required.  
-
-The design philosophy of oscar is to not make a decision for you here, but to
-provide the environment where any domain logic can be implemented, no matter
-how complex.  This is achieved through the use of subclassable objects that can 
-be tailored to your domain. 
-
-This document lists the components which will require implementation according to the
-domain:
-
-Taxonomy
---------
-How are products organised within the site?  A common pattern is to have a single 
-"category tree" where each product belongs to one category which sits within a tree structure
-of other categories?
-
-However, there are lots of other options such as having several separate taxonomy trees (eg split by
-brand, by theme, by product type).
-
-* Can a product belong to more than one category?
-* Can a category sit in more than one place within the tree?  (eg a "children's fiction" category
-  might sit beneath "children's books" and "fiction").
-
-Payment flow
-------------
-* Will the customer be debited at point of checkout, or when the items are dispatched?
-* If charging after checkout, when are shipping charges collected?  
-* What happens if an order is cancelled after partial payment?
-
-Payment sources
----------------
-How are customers going to pay for orders?  
-
-Will it be a simple, single-payment source solution such as paying by bankcard or using 
-Google checkout?  Or something more complicated such as allowing payment to be split across
-multiple payment sources such as a bankcard and a giftcard?
-
-More commonly, multiple payment sources can be used - such as:
-
-* Bankcard
-* Google checkout
-* PayPal
-* Business account
-* Managed budget
-* No upfront payment but send invoices later
-* Giftcard
-
-The checkout app within django-oscar is suitable flexible that all of these methods (and in 
-any combination) is supported.  However, you will need to implement the logic for your domain
-by subclassing the relevant view/util classes. 
-
-Domain logic is often required to: 
-
-* Determine which sources are available to an order;
-* Determine if payment can be split across sources and in which combinations;
-* Determine the order in which to take payment
-
-Stock logic
------------
-* Does the site support pre-orders (ordering before the product is available to be shipped) or
-  back-orders (ordering when the product does not have stock)?  
-
-Availability
-------------
-* Based on the stock information from a fulfilment partner, what messaging should be 
-  displayed on the site?  Further, should
-
-Shipping
---------
-Every client has a different requirement for shipping charges.  At its core, shipping charges
-normall depend on the following:
-
-* Items in basket
-* Shipping method chosen (e.g., standard or courier delivery)
-* Dispatch method chosen (e.g., ship together or ship separately)
-* Shipping address (e.g., which country it is in)
-* Basket vouchers (e.g., a voucher which gives free delivery)
-
-Common questions:
-
-* Are items shipping together as one batch, or separately?
-
-Checkout
---------
-
-
-

docs/source/key_questions.rst

@@ -0,0 +1,167 @@
+==============================================
+Building an e-commerce site: the key questions
+==============================================
+
+When building an e-commerce site, there are several components whose
+implementation is strongly domain-specific.  That is, every site will have
+different requirements for how such a component should operate.  As such, these
+components cannot easily be modelled using a generic system - no configurable
+system will be able to accurately capture all the domain-specific behaviour
+required.
+
+The design philosophy of Oscar is to not make a decision for you here, but to
+provide the environment where any domain logic can be implemented, no matter how
+complex.
+
+This document lists the components which will require implementation according
+to the domain at hand.  These are the key questions to answer when building your
+application.  Much of Oscar's documentation is in the form of "recipes" that
+explain how to solve the questions listed here.  Each question links to the
+relevant recipes.
+
+Catalogue
+=========
+
+What are your product types?
+----------------------------
+
+Are you selling books, DVDs, clothing, downloads or fruit and veg?  You will
+need to capture the attributes of your product types within your models.  Oscar
+divides products into 'product classes' which each have their own set of
+attributes.  
+
+* :doc:`recipes/how_to_model_your_catalogue`
+* :doc:`recipes/importing_a_catalogue`
+
+How is your catalogue organised?
+--------------------------------
+
+How are products organised within the site?  A common pattern is to have a
+single category tree where each product belongs to one category which sits
+within a tree structure of other categories.  However, there are lots of other
+options such as having several separate taxonomy trees (eg split by brand, by
+theme, by product type).  Other questions to consider:
+
+* Can a product belong to more than one category?
+* Can a category sit in more than one place within the tree?  (eg a "children's fiction" category
+  might sit beneath "children's books" and "fiction").
+
+* :doc:`recipes/how_to_customise_an_app`
+* :doc:`recipes/how_to_customise_models`
+* :doc:`recipes/how_to_override_a_core_class`
+
+How are products managed?
+-------------------------
+
+Is the catalogue managed by a admin using a dashboard, or though an automated
+process, such as processing feeds from a fulfillment system?  Where are your
+product images going to be served from?
+
+* :doc:`recipes/how_to_disable_an_app`
+
+
+Pricing, stock and availability
+===============================
+
+How is tax calculated?
+----------------------
+
+What availability messages are shown to customers?
+--------------------------------------------------
+
+Based on the stock information from a fulfilment partner, what messaging should be
+displayed on the site?  
+
+* :doc:`recipes/how_to_configure_stock_messaging`
+
+Do you allow pre- and back-orders
+---------------------------------
+
+An pre-order is where you allow a product to be bought before it has been
+published, while a back-order is where you allow a product to be bought that is
+currently out of stock.
+
+
+Shipping
+========
+
+How are shipping charges calculated?
+------------------------------------
+
+There are lots of options and variations here.  Shipping methods and their
+associated charges can take a variety of forms, including:
+
+* A charge based on the weight of the basket
+* Charging a pre-order and pre-item charge
+* Having free shipping for orders above a given threshold
+
+Recipes:
+
+* :doc:`recipes/how_to_configure_shipping`
+
+Which shipping methods are available?
+-------------------------------------
+
+There's often also an issue of which shipping methods are available, as
+this can depend on:
+
+* The shipping address (eg overseas orders have higher charges)
+* The contents of the basket (eg free shipping for downloadable products)
+* Who the user is (eg sales reps get free shipping)
+
+Oscar provides classes for free shipping, fixed charge shipping, pre-order and
+per-product item charges and weight-based charges.  It is provides a mechanism
+for determing which shipping methods are available to the user.
+
+Recipes:
+
+* :doc:`recipes/how_to_configure_shipping`
+
+
+Payment
+=======
+
+How are customers going to pay for orders?
+------------------------------------------
+
+Often a shop will have a single mechanism for taking payment, such
+as integrating with a payment gateway or using PayPal.  However more
+complicated projects will allow users to combine several different payment
+sources such as bankcards, business accounts and giftcards.
+
+Possible payment sources include:
+
+* Bankcard
+* Google checkout
+* PayPal
+* Business account
+* Managed budget
+* Giftcard
+* No upfront payment but send invoices later
+
+The checkout app within django-oscar is suitable flexible that all of these
+methods (and in any combination) is supported.  However, you will need to
+implement the logic for your domain by subclassing the relevant view/util
+classes.
+
+Domain logic is often required to:
+
+* Determine which payment methods are available to an order;
+* Determine if payment can be split across sources and in which combinations;
+* Determine the order in which to take payment
+* Determine how to handle failing payments (this can get complicated when using
+  multiple payment sources to pay for an order).
+
+* :doc:`recipes/how_to_configure_shipping`
+
+When will payment be taken?
+---------------------------
+
+A common pattern is to 'pre-auth' a bankcard at the point of checkout then
+'settle' for the appropriate amouts when the items actually ship.  However,
+sometimes payment is taken up front.  Often you won't have a choice due to
+limitations of the payment partner you need to integrate with.
+
+* Will the customer be debited at point of checkout, or when the items are dispatched?
+* If charging after checkout, when are shipping charges collected?
+* What happens if an order is cancelled after partial payment?

docs/source/recipes.rst

@@ -1,5 +1,6 @@
+=======
 Recipes
-============
+=======
 
 Recipes are simple guides to solving common problems that occur when creating
 e-commerce projects.
@@ -7,19 +8,39 @@ e-commerce projects.
 Customisation
 -------------
 
-* :doc:`recipes/how_to_customise_an_app`
-* :doc:`recipes/how_to_customise_models`
-* :doc:`recipes/how_to_override_a_core_class`
+.. toctree::
+    :maxdepth: 1
+
+    recipes/how_to_customise_an_app
+    recipes/how_to_customise_models
+    recipes/how_to_override_a_core_class
+    recipes/how_to_customise_templates
+    recipes/how_to_disable_an_app
 
 Catalogue
 ---------
 
-* :doc:`recipes/how_to_create_categories`
+.. toctree::
+    :maxdepth: 1
+
+    recipes/how_to_create_categories
+    recipes/how_to_model_your_catalogue
+    recipes/importing_a_catalogue
+
+Pricing, stock and availability
+-------------------------------
 
-Checkout
+.. toctree::
+    :maxdepth: 1
+
+    recipes/enforcing_stock_rules
+    recipes/how_to_configure_stock_messaging
+
+Shipping
 --------
 
-* :doc:`recipes/how_to_configure_shipping`
-* :doc:`recipes/enforcing_stock_rules`
+.. toctree::
+    :maxdepth: 1
+
+    recipes/how_to_configure_shipping
 
-Lots more to come!

docs/source/recipes/how_to_configure_shipping.rst

@@ -56,9 +56,10 @@ with a custom repository.
 
 * ``oscar.apps.shipping.methods.Free``.  No shipping charges.
 
-* ``oscar.apps.shipping.methods.WeightBased``.  This uses a model ``WeightBand``
-  to provide charges for different weight bands.  By default, the method will calculate
-  the weight of a product by looking for a 'weight' attribute although this can be
+* ``oscar.apps.shipping.methods.WeightBased``.  This is a model-driven method
+  that uses two models: ``WeightBased`` and ``WeightBand`` to provide charges
+  for different weight bands.  By default, the method will calculate the weight
+  of a product by looking for a 'weight' attribute although this can be
   configured.  
 
 * ``oscar.apps.shipping.methods.FixedPrice``.  This simply charges a fixed price for 

docs/source/recipes/how_to_configure_stock_messaging.rst

@@ -0,0 +1,3 @@
+================================
+How to configure stock messaging
+================================

docs/source/recipes/how_to_customise_templates.rst

@@ -0,0 +1,82 @@
+==========================
+How to customise templates
+==========================
+
+Assuming you want to use oscar's templates in your project, there are two
+options.  You don't have to though - you could write all your own templates if
+you like.  If you do this, it's probably best to start with a straight copy of
+all of oscar's templates so you know all the files that you need to
+re-implement.
+
+Anyway - here are the two options for customising.
+
+Method 1 - Forking
+------------------
+
+One option is always just to fork the template into your local project so that
+it comes first in the include path.
+
+Say you want to customise ``base.html``.  First you need a project-specific
+templates directory that comes first in the include path.  You can set this up
+as so::
+
+    TEMPLATE_LOADERS = (
+        'django.template.loaders.filesystem.Loader',
+        'django.template.loaders.app_directories.Loader',
+    )
+
+    import os
+    location = lambda x: os.path.join(os.path.dirname(os.path.realpath(__file__)), '..', x)
+    TEMPLATE_DIRS = (
+        location('templates'),
+    )
+
+Next copy oscar's ``base.html`` into your templates directory and customise it
+to suit your needs.
+
+The downsides of this method are that it involves duplicating the file from
+oscar in a way that breaks the link with upstream.  Hence, changes to oscar's
+``base.html`` won't be picked up by your project as you will have your own
+version.
+
+Method 2 - Subclass parent but use same template path
+-----------------------------------------------------
+
+There is a trick you can perform whereby oscar's templates can be accessed via
+two paths.  This is outlined in the `django wiki`_.
+
+.. _`django wiki`: https://code.djangoproject.com/wiki/ExtendingTemplates
+
+This basically means you can have a ``base.html`` in your local templates folder
+that extends oscar's ``base.html`` but only customises the blocks that it needs
+to.
+
+Oscar provides a helper variable to make this easy.  First, set up your
+template configuration as so::
+
+    TEMPLATE_LOADERS = (
+        'django.template.loaders.filesystem.Loader',
+        'django.template.loaders.app_directories.Loader',
+    )
+
+    import os
+    location = lambda x: os.path.join(os.path.dirname(os.path.realpath(__file__)), '..', x)
+    from oscar import OSCAR_PARENT_TEMPLATE_DIR
+    TEMPLATE_DIRS = (
+        location('templates'),
+        OSCAR_PARENT_TEMPLATE_DIR,
+    )
+
+The ``OSCAR_PARENT_TEMPLATE_DIR`` points to the directory above oscar's normal
+templates directory.  This means that ``path/to/oscar/template.html`` can also
+be reached via ``templates/path/to/oscar/template.html``.
+
+Hence to customise ``base.html``, you can have an implementation like::
+
+    # base.html
+    {% extends 'templates/base.html' %}
+
+    ...
+
+No real downsides to this one other than getting your front-end people to
+understand it.

docs/source/recipes/how_to_disable_an_app.rst

@@ -0,0 +1,6 @@
+=====================
+How to disable an app
+=====================
+
+...
+

docs/source/recipes/how_to_model_your_catalogue.rst

@@ -0,0 +1,10 @@
+===========================
+How to model your catalogue
+===========================
+
+
+
+Related recipes:
+
+* :doc:`recipes/how_to_customise_an_app`
+* :doc:`recipes/how_to_customise_models`

docs/source/recipes/importing_a_catalogue.rst

@@ -0,0 +1,6 @@
+=====================
+Importing a catalogue
+=====================
+
+...
+

docs/source/reference.rst

@@ -8,3 +8,4 @@ Contents:
    :maxdepth: 2
 
    reference/settings
+   reference/signals

docs/source/reference/signals.rst

@@ -0,0 +1,23 @@
+=======
+Signals
+=======
+
+Oscar defined a number of custom signals that provide useful hook-points for
+adding functionality.
+
+order_placed
+------------
+
+.. data:: oscar.apps.order.order_placed
+    :class:
+
+Raised by the :class:`oscar.apps.order.OrderCreator` class when creating an order.
+
+Arguments sent with this signal:
+
+``order``
+    The order created
+
+``user``
+    The user creating the order (not necessarily the user linked to the order
+    instance!)

docs/source/take_a_peek.rst

@@ -0,0 +1,80 @@
+===========
+Take a peek
+===========
+
+There are several ways to get a feel for Oscar and what it can do.
+
+Browse the sandbox site
+=======================
+
+There is a demo Oscar site, built hourly from HEAD of the master branch (unstable):
+http://sandbox.oscar.tangentlabs.co.uk
+
+It is intended to be a vanilla install of oscar, using the default templates and
+styles.  This is the blank canvas upon which you an build your application.
+
+It only has two customisations on top of oscar's core:
+
+* Two shipping methods are specified so that the shipping method step of
+  checkout is not skipped.  If there is only one shipping method (which is true of core
+  oscar) then the shipping method step is skipped as there is no choice to be
+  made.
+
+* A profile class is specified which defines a few simple fields.  This is to
+  demonstrate the account section of Oscar, which introspects the profile class
+  to build a combined User and Profile form.
+
+Running the sandbox locally
+===========================
+
+It's pretty straightforward to get the sandbox site running locally so you can
+play around with the sourcecode.
+
+Install Oscar and its dependencies within a virtualenv::
+
+    git clone git://github.com/tangentlabs/django-oscar.git
+    cd django-oscar
+    mkvirtualenv oscar
+    python setup.py develop
+    pip install -r requirements.txt
+
+Create a SQLite database and load some sample products and required fixtures::
+
+    cd sandbox
+    ./manage.py syncdb --noinput
+    ./manage.py migrate 
+    ./manage.py oscar_import_catalogue data/books-catalogue.csv 
+    ./manage.py oscar_import_catalogue_images data/books-images.tar.gz 
+    ./manage.py loaddata countries.json fixtures/pages.json 
+
+Now you can browse a sample Oscar site using Django's development server::
+
+    ./manage.py runserver
+
+Note that some things are deliberately not implemented within core Oscar
+as they are domain-specific.  For instance:
+
+* All tax is set to zero
+* The two shipping methods are both free
+* No payment is required to submit an order
+
+I've found a problem!
+---------------------
+
+Please `report them in Github's issue tracker`_.
+
+.. _`report them in Github's issue tracker`: https://github.com/tangentlabs/django-oscar/issues
+
+Browse some real Oscar implementations
+======================================
+
+There are several Oscar implementations in production, although several are B2B
+and hence can't be browsed by the public.  Here's a few public ones to have a
+look at:
+
+* http://www.landmarkonthenet.com - Landmark is part of Tata Group.  This site
+  has a catalogue size of more than 20 million products and integrates with many
+  partners such as Gardners, Ingram, Nielsen, Citibank, Qwikcilver and SAP.
+
+* http://www.dolbeau.ca/ - "Dolbeau delivers weekly limited editions of
+  handcrafted luxury menswear"

docs/test_docs.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+make html
+open build/html/index.html &

oscar/apps/analytics/reports.py

@@ -6,43 +6,57 @@ from django.template.defaultfilters import date
 from oscar.core.loading import get_class
 
 ReportGenerator = get_class('dashboard.reports.reports', 'ReportGenerator')
+ReportCSVFormatter = get_class('dashboard.reports.reports', 'ReportCSVFormatter')
+ReportHTMLFormatter = get_class('dashboard.reports.reports', 'ReportHTMLFormatter')
 ProductRecord = get_model('analytics', 'ProductRecord')
 UserRecord = get_model('analytics', 'UserRecord')
 
 
-class ProductReportGenerator(ReportGenerator):
-    
-    filename_template = 'product-analytics.csv'
-    code = 'product_analytics'
-    description = 'Product analytics'
-    
-    def generate(self, response):
+class ProductReportCSVFormatter(ReportCSVFormatter):
+    filename_template = 'conditional-offer-performance.csv'
+
+    def generate_csv(self, response, products):
         writer = csv.writer(response)
         header_row = ['Product',
                       'Views',
                       'Basket additions',
                       'Purchases',]
         writer.writerow(header_row)
-        
-        records = ProductRecord._default_manager.all()
-        for record in records:
-            row = [record.product, record.num_views, record.num_basket_additions, record.num_purchases]
+
+        for record in products:
+            row = [record.product,
+                   record.num_views,
+                   record.num_basket_additions,
+                   record.num_purchases]
             writer.writerow(row)
-            
+
+
+class ProductReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/product_report.html'
+
+
+class ProductReportGenerator(ReportGenerator):
+
+    code = 'product_analytics'
+    description = 'Product analytics'
+
+    formatters = {
+      'CSV_formatter': ProductReportCSVFormatter,
+      'HTML_formatter': ProductReportHTMLFormatter
+    }
+
+    def generate(self):
+        records = ProductRecord._default_manager.all()
+        return self.formatter.generate_response(records)
+
     def is_available_to(self, user):
         return user.is_staff
-    
-    def filename(self):
-        return self.filename_template
-    
 
-class UserReportGenerator(ReportGenerator):
-    
+
+class UserReportCSVFormatter(ReportCSVFormatter):
     filename_template = 'user-analytics.csv'
-    code = 'user_analytics'
-    description = 'User analytics'
-    
-    def generate(self, response):
+
+    def generate_csv(self, response, users):
         writer = csv.writer(response)
         header_row = ['Name',
                       'Date registered',
@@ -55,22 +69,37 @@ class UserReportGenerator(ReportGenerator):
                       'Date of last order',
                       ]
         writer.writerow(header_row)
-        
-        records = UserRecord._default_manager.select_related().all()
-        for record in records:
-            row = [record.user.get_full_name(), 
+
+        for record in users:
+            row = [record.user.get_full_name(),
                    self.format_date(record.user.date_joined),
-                   record.num_product_views, 
-                   record.num_basket_additions, 
+                   record.num_product_views,
+                   record.num_basket_additions,
                    record.num_orders,
                    record.num_order_lines,
                    record.num_order_items,
                    record.total_spent,
                    self.format_datetime(record.date_last_order)]
             writer.writerow(row)
-            
+
+
+class UserReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/user_report.html'
+
+
+class UserReportGenerator(ReportGenerator):
+
+    code = 'user_analytics'
+    description = 'User analytics'
+
+    formatters = {
+        'CSV_formatter': UserReportCSVFormatter,
+        'HTML_formatter': UserReportHTMLFormatter
+    }
+
+    def generate(self):
+        users = UserRecord._default_manager.select_related().all()
+        return self.formatter.generate_response(users)
+
     def is_available_to(self, user):
         return user.is_staff
-    
-    def filename(self):
-        return self.filename_template

oscar/apps/basket/reports.py

@@ -4,19 +4,16 @@ from django.db.models import get_model
 
 from oscar.core.loading import get_class, get_classes
 ReportGenerator = get_class('dashboard.reports.reports', 'ReportGenerator')
+ReportCSVFormatter = get_class('dashboard.reports.reports', 'ReportCSVFormatter')
+ReportHTMLFormatter = get_class('dashboard.reports.reports', 'ReportHTMLFormatter')
 Basket = get_model('basket', 'Basket')
 OPEN, SUBMITTED = get_classes('basket.models', ['OPEN', 'SUBMITTED'])
 
 
-class OpenBasketReportGenerator(ReportGenerator):
-    """
-    Report of baskets which haven't been submitted yet
-    """
+class OpenBasketReportCSVFormatter(ReportCSVFormatter):
     filename_template = 'open-baskets-%s-%s.csv'
-    code = 'open_baskets'
-    description = 'Open baskets'
-    
-    def generate(self, response):
+
+    def generate_csv(self, response, baskets):
         writer = csv.writer(response)
         header_row = ['User ID',
                       'Name',
@@ -29,31 +26,53 @@ class OpenBasketReportGenerator(ReportGenerator):
                       'Time since creation',
                      ]
         writer.writerow(header_row)
-        
-        baskets = Basket._default_manager.filter(status=OPEN)
+
         for basket in baskets:
             if basket.owner:
                 row = [basket.owner_id, basket.owner.get_full_name(), basket.owner.email,
                        basket.status, basket.num_lines,
-                       basket.num_items, basket.total_incl_tax, 
-                       self.format_datetime(basket.date_created), 
+                       basket.num_items, basket.total_incl_tax,
+                       self.format_datetime(basket.date_created),
                        basket.time_since_creation]
             else:
                 row = [basket.owner_id, None, None, basket.status, basket.num_lines,
-                       basket.num_items, basket.total_incl_tax, 
+                       basket.num_items, basket.total_incl_tax,
                        self.format_datetime(basket.date_created), basket.time_since_creation]
             writer.writerow(row)
 
+    def filename(self, **kwargs):
+        return self.filename_template % (kwargs['start_date'], kwargs['end_date'])
 
-class SubmittedBasketReportGenerator(ReportGenerator):
+
+class OpenBasketReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/open_basket_report.html'
+
+
+class OpenBasketReportGenerator(ReportGenerator):
     """
-    Report of baskets that have been submitted
+    Report of baskets which haven't been submitted yet
     """
+    code = 'open_baskets'
+    description = 'Open baskets'
+
+    formatters = {
+        'CSV_formatter': OpenBasketReportCSVFormatter,
+        'HTML_formatter': OpenBasketReportHTMLFormatter
+    }
+
+    def generate(self):
+        additional_data = {
+            'start_date': self.start_date,
+            'end_date': self.end_date
+        }
+        baskets = Basket._default_manager.filter(status=OPEN)
+        return self.formatter.generate_response(baskets, **additional_data)
+
+
+class SubmittedBasketReportCSVFormatter(ReportCSVFormatter):
     filename_template = 'submitted_baskets-%s-%s.csv'
-    code = 'submitted_baskets'
-    description = 'Submitted baskets'
-    
-    def generate(self, response):
+
+    def generate_csv(self, response, baskets):
         writer = csv.writer(response)
         header_row = ['User ID',
                       'User',
@@ -65,8 +84,7 @@ class SubmittedBasketReportGenerator(ReportGenerator):
                       'Time between creation and submission',
                      ]
         writer.writerow(header_row)
-        
-        baskets = Basket._default_manager.filter(status=SUBMITTED)
+
         for basket in baskets:
             row = [basket.owner_id,
                    basket.owner,
@@ -77,3 +95,31 @@ class SubmittedBasketReportGenerator(ReportGenerator):
                    self.format_datetime(basket.date_created),
                    basket.time_before_submit]
             writer.writerow(row)
+
+    def filename(self, **kwargs):
+        return self.filename_template % (kwargs['start_date'], kwargs['end_date'])
+
+
+class SubmittedBasketReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/submitted_basket_report.html'
+
+
+class SubmittedBasketReportGenerator(ReportGenerator):
+    """
+    Report of baskets that have been submitted
+    """
+    code = 'submitted_baskets'
+    description = 'Submitted baskets'
+
+    formatters = {
+        'CSV_formatter': SubmittedBasketReportCSVFormatter,
+        'HTML_formatter': SubmittedBasketReportHTMLFormatter
+    }
+
+    def generate(self):
+        additional_data = {
+            'start_date': self.start_date,
+            'end_date': self.end_date
+        }
+        baskets = Basket._default_manager.filter(status=SUBMITTED)
+        return self.formatter.generate_response(baskets, **additional_data)

oscar/apps/basket/tests.py

@@ -1,5 +1,6 @@
 from decimal import Decimal as D
 import httplib
+import datetime
 
 from django.conf import settings
 from django.contrib.auth.models import User
@@ -111,14 +112,22 @@ class BasketThresholdTest(TestCase):
 class BasketReportTests(TestCase):
 
     def test_open_report_doesnt_error(self):
-        generator = OpenBasketReportGenerator()
-        response = HttpResponse()
-        generator.generate(response)
+        data = {
+            'start_date': datetime.date(2012, 5, 1),
+            'end_date': datetime.date(2012, 5, 17),
+            'formatter': 'CSV'
+        }
+        generator = OpenBasketReportGenerator(**data)
+        generator.generate()
 
     def test_submitted_report_doesnt_error(self):
-        generator = SubmittedBasketReportGenerator()
-        response = HttpResponse()
-        generator.generate(response)
+        data = {
+            'start_date': datetime.date(2012, 5, 1),
+            'end_date': datetime.date(2012, 5, 17),
+            'formatter': 'CSV'
+        }
+        generator = SubmittedBasketReportGenerator(**data)
+        generator.generate()
 
 
 class SavedBasketTests(TestCase):
@@ -178,5 +187,3 @@ class SavedBasketTests(TestCase):
         # we can't add more than stock level into basket
         self.assertEqual(Basket.open.get(id=basket.id).lines.get(product=product).quantity, 1)
         self.assertRedirects(response, reverse('basket:summary'))
-
-

oscar/apps/dashboard/reports/forms.py

@@ -6,16 +6,16 @@ GeneratorRepository = get_class('dashboard.reports.utils', 'GeneratorRepository'
 
 class ReportForm(forms.Form):
     generators = GeneratorRepository().get_report_generators()
-    
+
     type_choices = []
     for generator in generators:
         type_choices.append((generator.code, generator.description))
     report_type = forms.ChoiceField(widget=forms.Select(), choices=type_choices)
     date_from = forms.DateField()
     date_to = forms.DateField()
-    
+    download = forms.BooleanField(required=False)
+
     def clean(self):
         if 'date_from' in self.cleaned_data and 'date_to' in self.cleaned_data and self.cleaned_data['date_from'] > self.cleaned_data['date_to']:
             raise forms.ValidationError("Your start date must be before your end date")
         return self.cleaned_data
-   

oscar/apps/dashboard/reports/reports.py

@@ -1,38 +1,61 @@
 from django.template.defaultfilters import date
+from django.http import HttpResponse
 
 
 class ReportGenerator(object):
     """
-    Top-level class that needs to be subclassed to provide a 
+    Top-level class that needs to be subclassed to provide a
     report generator.
     """
     filename_template = 'report-%s-to-%s.csv'
     mimetype = 'text/csv'
     code = ''
     description = '<insert report description>'
-    
+
     def __init__(self, **kwargs):
         if 'start_date' in kwargs and 'end_date' in kwargs:
             self.start_date = kwargs['start_date']
             self.end_date = kwargs['end_date']
-    
+
+        self.formatter = self.formatters['%s_formatter' % kwargs['formatter']]()
+
     def generate(self, response):
         pass
- 
+
     def filename(self):
         """
         Returns the filename for this report
         """
-        return self.filename_template % (self.start_date, self.end_date)
-    
+        return self.formatter.filename()
+
     def is_available_to(self, user):
         """
         Checks whether this report is available to this user
         """
         return user.is_staff
 
+
+class ReportFormatter(object):
     def format_datetime(self, dt):
         return date(dt, 'DATETIME_FORMAT')
 
     def format_date(self, d):
-        return date(d, 'DATE_FORMAT')
+        return date(d, 'DATE_FORMAT')
+
+    def filename(self):
+        return self.filename_template
+
+
+class ReportCSVFormatter(ReportFormatter):
+
+    def generate_response(self, objects, **kwargs):
+        response = HttpResponse(mimetype='text/csv')
+        response['Content-Disposition'] = 'attachment; filename=%s' % self.filename(**kwargs)
+        self.generate_csv(response, objects)
+        return response
+
+
+class ReportHTMLFormatter(ReportFormatter):
+
+    def generate_response(self, objects, **kwargs):
+        return objects

oscar/apps/dashboard/reports/utils.py

@@ -8,7 +8,7 @@ VoucherReportGenerator = get_class('voucher.reports', 'VoucherReportGenerator')
 
 
 class GeneratorRepository(object):
-    
+
     generators = [OrderReportGenerator,
                   ProductReportGenerator,
                   UserReportGenerator,
@@ -19,11 +19,11 @@ class GeneratorRepository(object):
 
     def get_report_generators(self):
         return self.generators
-    
+
     def get_generator(self, code):
         for generator in self.generators:
             if generator.code == code:
                 return generator
         return None
-    
-    
+
+

oscar/apps/dashboard/reports/views.py

@@ -1,31 +1,48 @@
-from django.http import HttpResponse, HttpResponseForbidden, Http404
+from django.http import HttpResponseForbidden, Http404
 from django.template.response import TemplateResponse
-from django.views.generic import TemplateView
+from django.views.generic import ListView
 
 from oscar.core.loading import get_class
 ReportForm = get_class('dashboard.reports.forms', 'ReportForm')
 GeneratorRepository = get_class('dashboard.reports.utils', 'GeneratorRepository')
 
 
-class IndexView(TemplateView):
+class IndexView(ListView):
     template_name = 'dashboard/reports/index.html'
-    
+    paginate_by = 25
+    context_object_name = 'objects'
+
     def get(self, request, *args, **kwargs):
         if 'report_type' in request.GET:
             form = ReportForm(request.GET)
             if form.is_valid():
                 generator = _get_generator(form)
                 if not generator.is_available_to(request.user):
-                    return HttpResponseForbidden("You do not have access to this report")
-                
-                response = HttpResponse(mimetype=generator.mimetype)
-                response['Content-Disposition'] = 'attachment; filename=%s' % generator.filename()
-                generator.generate(response)
-                return response
+                    return HttpResponseForbidden("You do not have access"
+                                                 " to this report")
+
+                report = generator.generate()
+
+                if form.cleaned_data['download']:
+                    return report
+                else:
+                    self.set_list_view_attrs(generator, report)
+                    context = self.get_context_data(object_list=self.queryset)
+                    context['form'] = form
+                    context['description'] = '%s between %s and %s' % (
+                        generator.description,
+                        form.cleaned_data['date_from'],
+                        form.cleaned_data['date_to'],
+                    )
+                    return self.render_to_response(context)
         else:
             form = ReportForm()
         return TemplateResponse(request, self.template_name, {'form': form})
 
+    def set_list_view_attrs(self, generator, report):
+        self.template_name = generator.filename()
+        self.object_list = self.queryset = report
+
 
 def _get_generator(form):
     code = form.cleaned_data['report_type']
@@ -34,5 +51,10 @@ def _get_generator(form):
     generator_cls = repo.get_generator(code)
     if not generator_cls:
         raise Http404()
-    return generator_cls(start_date=form.cleaned_data['date_from'], 
-                         end_date=form.cleaned_data['date_to'])
+
+    download = form.cleaned_data['download']
+    formatter = 'CSV' if download else 'HTML'
+
+    return generator_cls(start_date=form.cleaned_data['date_from'],
+                         end_date=form.cleaned_data['date_to'],
+                         formatter=formatter)

oscar/apps/offer/reports.py

@@ -1,28 +1,60 @@
 import csv
+from decimal import Decimal as D
 
 from django.db.models import get_model
 
 from oscar.core.loading import get_class
 ReportGenerator = get_class('dashboard.reports.reports', 'ReportGenerator')
+ReportCSVFormatter = get_class('dashboard.reports.reports', 'ReportCSVFormatter')
+ReportHTMLFormatter = get_class('dashboard.reports.reports', 'ReportHTMLFormatter')
 ConditionalOffer = get_model('offer', 'ConditionalOffer')
+OrderDiscount = get_model('order', 'OrderDiscount')
 
 
-class OfferReportGenerator(ReportGenerator):
-    
+class OfferReportCSVFormatter(ReportCSVFormatter):
     filename_template = 'conditional-offer-performance.csv'
-    code = 'conditional-offers'
-    description = 'Offer performance'
-    
-    def generate(self, response):
+
+    def generate_csv(self, response, offers):
         writer = csv.writer(response)
         header_row = ['Offer',
                       'Total discount',
                      ]
         writer.writerow(header_row)
-        
-        for offer in ConditionalOffer._default_manager.all():
+
+        for offer in offers:
             row = [offer, offer.total_discount]
             writer.writerow(row)
 
-    def filename(self):
-        return self.filename_template
+
+class OfferReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/offer_report.html'
+
+
+class OfferReportGenerator(ReportGenerator):
+    code = 'conditional-offers'
+    description = 'Offer performance'
+
+    formatters = {
+        'CSV_formatter': OfferReportCSVFormatter,
+        'HTML_formatter': OfferReportHTMLFormatter,
+    }
+
+    def generate(self):
+        discounts = OrderDiscount._default_manager.filter(
+            order__date_placed__gte=self.start_date,
+            order__date_placed__lt=self.end_date
+        )
+        offer_discounts = {}
+        for discount in discounts:
+            if discount.offer_id not in offer_discounts:
+                try:
+                    offer = ConditionalOffer._default_manager.get(id=discount.offer_id)
+                except ConditionalOffer.DoesNotExist:
+                    continue
+                offer_discounts[discount.offer_id] = {
+                    'offer': offer,
+                    'total_discount': D('0.00')
+                }
+            offer_discounts[discount.offer_id]['total_discount'] += discount.amount
+
+        return self.formatter.generate_response(offer_discounts.values())

oscar/apps/order/reports.py

@@ -4,20 +4,15 @@ from django.db.models import get_model
 
 from oscar.core.loading import get_class
 ReportGenerator = get_class('dashboard.reports.reports', 'ReportGenerator')
+ReportCSVFormatter = get_class('dashboard.reports.reports', 'ReportCSVFormatter')
+ReportHTMLFormatter = get_class('dashboard.reports.reports', 'ReportHTMLFormatter')
 Order = get_model('order', 'Order')
 
 
-class OrderReportGenerator(ReportGenerator):
-    
+class OrderReportCSVFormatter(ReportCSVFormatter):
     filename_template = 'orders-%s-to-%s.csv'
-    code = 'order_report'
-    description = "Orders placed"
-    
-    def generate(self, response):
-        orders = Order._default_manager.filter(
-            date_placed__gte=self.start_date
-        ).filter(date_placed__lt=self.end_date)
-        
+
+    def generate_csv(self, response, orders):
         writer = csv.writer(response)
         header_row = ['Order number',
                       'User',
@@ -30,6 +25,36 @@ class OrderReportGenerator(ReportGenerator):
                    order.total_incl_tax,
                    self.format_datetime(order.date_placed)]
             writer.writerow(row)
-            
+
+    def filename(self, **kwargs):
+        return self.filename_template % (kwargs['start_date'], kwargs['end_date'])
+
+
+class OrderReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/order_report.html'
+
+
+class OrderReportGenerator(ReportGenerator):
+
+    code = 'order_report'
+    description = "Orders placed"
+
+    formatters = {
+        'CSV_formatter': OrderReportCSVFormatter,
+        'HTML_formatter': OrderReportHTMLFormatter,
+    }
+
+    def generate(self):
+        orders = Order._default_manager.filter(
+            date_placed__gte=self.start_date
+        ).filter(date_placed__lt=self.end_date)
+
+        additional_data = {
+            'start_date': self.start_date,
+            'end_date': self.end_date
+        }
+
+        return self.formatter.generate_response(orders, **additional_data)
+
     def is_available_to(self, user):
-        return user.is_staff and user.has_perm('order.can_view')
+        return user.is_staff and user.has_perm('order.can_view')

oscar/apps/voucher/reports.py

@@ -3,17 +3,17 @@ import csv
 from django.db.models import get_model
 
 from oscar.core.loading import get_class
+
 ReportGenerator = get_class('dashboard.reports.reports', 'ReportGenerator')
+ReportCSVFormatter = get_class('dashboard.reports.reports', 'ReportCSVFormatter')
+ReportHTMLFormatter = get_class('dashboard.reports.reports', 'ReportHTMLFormatter')
 Voucher = get_model('voucher', 'Voucher')
 
 
-class VoucherReportGenerator(ReportGenerator):
-    
+class VoucherReportCSVFormatter(ReportCSVFormatter):
     filename_template = 'voucher-performance.csv'
-    code = 'vouchers'
-    description = 'Voucher performance'
-    
-    def generate(self, response):
+
+    def generate_csv(self, response, vouchers):
         writer = csv.writer(response)
         header_row = ['Voucher code',
                       'Added to a basket',
@@ -21,11 +21,29 @@ class VoucherReportGenerator(ReportGenerator):
                       'Total discount',
                      ]
         writer.writerow(header_row)
-        
-        vouchers = Voucher._default_manager.all()
+
         for voucher in vouchers:
-            row = [voucher.code, voucher.num_basket_additions, voucher.num_orders, voucher.total_discount]
+            row = [voucher.code,
+                   voucher.num_basket_additions,
+                   voucher.num_orders,
+                   voucher.total_discount]
             writer.writerow(row)
 
-    def filename(self):
-        return self.filename_template
+
+class VoucherReportHTMLFormatter(ReportHTMLFormatter):
+    filename_template = 'dashboard/reports/partials/voucher_report.html'
+
+
+class VoucherReportGenerator(ReportGenerator):
+
+    code = 'vouchers'
+    description = 'Voucher performance'
+
+    formatters = {
+        'CSV_formatter': VoucherReportCSVFormatter,
+        'HTML_formatter': VoucherReportHTMLFormatter
+    }
+
+    def generate(self):
+        vouchers = Voucher._default_manager.all()
+        return self.formatter.generate_response(vouchers)

oscar/templates/catalogue/browse.html

@@ -49,7 +49,9 @@
     {% if category.description %}
         <div class="row-fluid">
             <div class="span9"><p>{{ category.description }}</p></div>
-            <div class="span3"><img src="{{ category.image.url }}" alt="{{ summary }}" /></div>
+			{% if category.image %}
+				<div class="span3"><img src="{{ category.image.url }}" alt="{{ summary }}" /></div>
+			{% endif %}
         </div>
     {% endif %}
 

oscar/templates/dashboard/catalogue/product_update.html

@@ -34,6 +34,9 @@ Update product | {{ block.super }}
         <div class="sub-header">
             <h3 class="app-ico ico_expand icon">Product information</h3>
         </div>
+		<div class="control-group fields-full">
+			Product class: <strong>{{ product.product_class }}</strong>
+		</div>
         {% for field in form %}
             {% if forloop.counter > 4 %}
                 <div class="form-inline pull-left">

oscar/templates/dashboard/reports/index.html

@@ -31,5 +31,13 @@ Reports | {{ block.super }}
     </div>
 </form>
 
+{% if description %}
+<div class="sub-header">
+	<h3>{{ description }}</h3>
+</div>
+{% endif %}
+{% block report %}
+{% endblock %}
+
 {% endblock dashboard_content %}
 

oscar/templates/dashboard/reports/partials/offer_report.html

@@ -0,0 +1,24 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+{% if objects %}
+	<table class="table table-striped table-bordered">
+		<tr>
+			<th>Offer</th>
+			<th>Total discount</th>
+		</tr>
+		{% for offer_discount in objects %}
+		<tr>
+			<td>{{ offer_discount.offer.name }}</td>
+			<td>{{ offer_discount.total_discount|currency }}</td>
+		</tr>
+		{% endfor %}
+	</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% else %}
+	<p>No results found.</p>
+{% endif %}
+{% endblock %}

oscar/templates/dashboard/reports/partials/open_basket_report.html

@@ -0,0 +1,30 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+<table class="table table-striped table-bordered">
+    <tr>
+        <th>Email</th>
+        <th>Name</th>
+        <th>Num lines</th>
+        <th>Num items</th>
+        <th>Value</th>
+        <th>Date of creation</th>
+        <th>Time since creation</th>
+    </tr>
+    {% for basket in objects %}
+    <tr>
+        <td>{{ basket.owner.email }}</td>
+        <td>{{ basket.owner.get_full_name|default:"-" }}</td>
+        <td>{{ basket.num_lines }}</td>
+        <td>{{ basket.num_items }}</td>
+        <td>{{ basket.total_incl_tax|currency }}</td>
+        <td>{{ basket.date_created }}</td>
+        <td>{{ basket.time_since_creation }}</td>
+    </tr>
+    {% endfor %}
+</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% endblock %}

oscar/templates/dashboard/reports/partials/order_report.html

@@ -0,0 +1,32 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+{% if objects %}
+	<table class="table table-striped table-bordered">
+		<tr>
+			<th>Order number</th>
+			<th>User</th>
+			<th>Total incl. tax</th>
+			<th>Date placed</th>
+			<th></th>
+		</tr>
+		{% for order in objects %}
+		<tr>
+			<td>{{ order.number }}</td>
+			<td>{{ order.user }}</td>
+			<td>{{ order.total_incl_tax|currency }}</td>
+			<td>{{ order.date_placed }}</td>
+			<td>
+				<a class="btn btn-info" href="{% url dashboard:order-detail order.number %}">View</a>
+			</td>
+		</tr>
+		{% endfor %}
+	</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% else %}
+	<p>No results found.</p>
+{% endif %}
+{% endblock %}

oscar/templates/dashboard/reports/partials/product_report.html

@@ -0,0 +1,24 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+<table class="table table-striped table-bordered">
+    <tr>
+        <th>Product</th>
+        <th>Views</th>
+        <th>Basket additions</th>
+        <th>Purchases</th>
+    </tr>
+    {% for product in objects %}
+    <tr>
+        <td>{{ product.product }}</td>
+        <td>{{ product.num_views }}</td>
+        <td>{{ product.num_basket_additions }}</td>
+        <td>{{ product.num_purchases }}</td>
+    </tr>
+    {% endfor %}
+</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% endblock %}

oscar/templates/dashboard/reports/partials/submitted_basket_report.html

@@ -0,0 +1,30 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+<table class="table table-striped table-bordered">
+    <tr>
+        <th>Email</th>
+        <th>Name</th>
+        <th>Num lines</th>
+        <th>Num items</th>
+        <th>Value</th>
+        <th>Date created</th>
+        <th>Time between creation and submission</th>
+    </tr>
+    {% for basket in objects %}
+    <tr>
+        <td>{{ basket.owner.email }}</td>
+        <td>{{ basket.owner.get_full_name|default:"-" }}</td>
+        <td>{{ basket.num_lines }}</td>
+        <td>{{ basket.num_items }}</td>
+        <td>{{ basket.total_incl_tax|currency }}</td>
+        <td>{{ basket.date_created }}</td>
+        <td>{{ basket.time_before_submit }}</td>
+    </tr>
+    {% endfor %}
+</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% endblock %}

oscar/templates/dashboard/reports/partials/user_report.html

@@ -0,0 +1,36 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+<table class="table table-striped table-bordered">
+    <tr>
+        <th>Email</th>
+        <th>Name</th>
+        <th>Date registered</th>
+        <th>Product views</th>
+        <th>Basket additions</th>
+        <th>Orders</th>
+        <th>Order lines</th>
+        <th>Order items</th>
+        <th>Total spent</th>
+        <th>Date of last order</th>
+    </tr>
+    {% for user in objects %}
+    <tr>
+        <td>{{ user.user.email }}</td>
+        <td>{{ user.user.get_full_name|default:"-" }}</td>
+        <td>{{ user.user.date_joined }}</td>
+        <td>{{ user.num_product_views }}</td>
+        <td>{{ user.num_basket_additions }}</td>
+        <td>{{ user.num_orders }}</td>
+        <td>{{ user.num_order_lines }}</td>
+        <td>{{ user.num_order_items }}</td>
+        <td>{{ user.total_spent|currency }}</td>
+        <td>{{ user.date_last_order|default:"-" }}</td>
+    </tr>
+    {% endfor %}
+</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% endblock %}

oscar/templates/dashboard/reports/partials/voucher_report.html

@@ -0,0 +1,24 @@
+{% extends 'dashboard/reports/index.html' %}
+{% load currency_filters %}
+
+{% block report %}
+<table class="table table-striped table-bordered">
+    <tr>
+        <th>Voucher code</th>
+        <th>Added to a basket</th>
+        <th>Used in an order</th>
+        <th>Total discount</th>
+    </tr>
+    {% for voucher in objects %}
+    <tr>
+        <td>{{ voucher.code }}</td>
+        <td>{{ voucher.num_basket_additions }}</td>
+        <td>{{ voucher.num_orders }}</td>
+        <td>{{ voucher.total_discount|currency }}</td>
+    </tr>
+    {% endfor %}
+</table>
+    {% if page_obj %}
+        {% include "catalogue/partials/pagination.html" %}
+    {% endif %}
+{% endblock %}

release.sh

@@ -5,10 +5,6 @@ git tag | grep $RELEASE_NUM > /dev/null && \
 	echo "New version number required ($RELEASE_NUM already used)" && exit 1
 
 # Push to PyPi
-:xa
-
-
-
 ./setup.py sdist upload
 
 # Tag in Git