Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updated documentation - still not complete but much better

  • Loading branch information...
commit 9727c7063a018fb10da4d0783c6ad0c4139a3ec8 1 parent fe4bcd5
David Winterbottom codeinthehole authored
20 README.rst
View
@@ -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
16 docs/source/components.rst
View
@@ -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
72 docs/source/contributing.rst
View
@@ -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.
0  docs/source/customisation.rst → docs/source/design_decisions.rst
View
File renamed without changes
197 docs/source/getting_started.rst
View
@@ -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.
56 docs/source/index.rst
View
@@ -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
==================
95 docs/source/introduction_to_ecommerce.rst
View
@@ -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
---------
-
-
-
167 docs/source/key_questions.rst
View
@@ -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?
39 docs/source/recipes.rst
View
@@ -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!
7 docs/source/recipes/how_to_configure_shipping.rst
View
@@ -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
3  docs/source/recipes/how_to_configure_stock_messaging.rst
View
@@ -0,0 +1,3 @@
+================================
+How to configure stock messaging
+================================
82 docs/source/recipes/how_to_customise_templates.rst
View
@@ -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.
6 docs/source/recipes/how_to_disable_an_app.rst
View
@@ -0,0 +1,6 @@
+=====================
+How to disable an app
+=====================
+
+...
+
10 docs/source/recipes/how_to_model_your_catalogue.rst
View
@@ -0,0 +1,10 @@
+===========================
+How to model your catalogue
+===========================
+
+
+
+Related recipes:
+
+* :doc:`recipes/how_to_customise_an_app`
+* :doc:`recipes/how_to_customise_models`
6 docs/source/recipes/importing_a_catalogue.rst
View
@@ -0,0 +1,6 @@
+=====================
+Importing a catalogue
+=====================
+
+...
+
1  docs/source/reference.rst
View
@@ -8,3 +8,4 @@ Contents:
:maxdepth: 2
reference/settings
+ reference/signals
23 docs/source/reference/signals.rst
View
@@ -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!)
80 docs/source/take_a_peek.rst
View
@@ -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"
3  docs/test_docs.sh
View
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+make html
+open build/html/index.html &
4 oscar/__init__.py
View
@@ -3,8 +3,8 @@
# Use 'final' as the 4th element to indicate
# a full release
-VERSION = (0, 2, 0, 'RC', 2)
-
+VERSION = (0, 2, 0, 'final')
+
def get_short_version():
return '%s.%s' % (VERSION[0], VERSION[1])
Please sign in to comment.
Something went wrong with that request. Please try again.