It took a while but it’s finally here: welcome to Oscar 0.6!

These release notes cover the new features as well as backwards incompatible changes that you’ll want to be aware of when upgrading from Oscar 0.5 or earlier. This release contains some major changes to core APIs which means many old APIs are scheduled to be dropped - see the deprecation plan to avoid any nasty surprises.

When upgrading your Oscar site, make sure you study both the backwards incompatible changes and the deprecated features. If you encounter any undocumented issues, please let us know on the mailing list.

Table of contents:

Also, to help justify Tangent’s sponsorship of Oscar, a simple tracking mechanism has been introduced to keep track of which sites use Oscar.

New helper methods in the EventHandler class for order processing.

Customer wishlists . Customers can how add products to wishlists and manage them within their account section.

A feature-rich demo site that illustrates how Oscar can be customised. It uses several of Oscar’s many extensions such as django-oscar-paypal , django-oscar-datacash and django-oscar-stores . It is intended as a reference site for Oscar.

Oscar also supports Django 1.6 although this is considered experimental at this stage. It’s possible there are still some incompatibilities that haven’t been teased out just yet.

Oscar now supports Django 1.5 and its custom user model. This has been only tested in the context of starting a new Oscar project with a custom model. Switching from a separate “profile” model to the new system is not recommended at this point.

Oscar 0.6 also introduces better support for marketplace-like functionality with the so-called permission-based dashboard. It is now possible to give non-staff users access to a subset of the dashboard’s views (products and orders) by setting the new dashboard_access permission.

The biggest change in Oscar 0.6 is the reworking of pricing and availability , which builds on top of the change to allow multiple stockrecords per product . The change is largely backwards compatible with the old system of “partner wrappers” but it is recommended to upgrade to the new system. Support for partner wrappers will be removed for Oscar 0.7.

Multiple stockrecords per product¶ Products can now have multiple stockrecords rather than just one. This is a key structural change that paves the way for many advanced features. If a product can be fulfilled by multiple partners, a different stockrecord can be created for each partner. This is a common requirement for large-scale e-commerce sites selling millions of products that use many different fulfilment partners. It also allows better support for international sites as stockrecords can be created for partners in different countries, who sell in different currencies. See the documentation on pricing and availability for more details. Warning This changes means several APIs are deprecated as they assume there is only one stockrecord per product.

Pricing and availability¶ When products can have many stockrecords, a process needs to be in place to choose which one is selected for a given customer and product. To handle this, a new “strategy” class has been introduced, responsible for selecting the appropriate stockrecord for a given customer and product. This change also paved the way for reworking how prices, taxes and availability are handled. Instead of using “partner wrappers”, the strategy class is responsible for returning availability details and prices for a particular product. New classes known as pricing and availability policies are used to cleanly encapsulate this information. These changes allow Oscar to dynamically determine prices, partner and availability for a given customer and product. This enables several advanced features such as: Fulfilling a product from the partner that offers the best margin.

Fulfilling a product from the partner geographically closest to the customer.

Automatically switching to a new partner when when stock runs out.

Supporting transactions in multiple currencies on the same site.

Supporting different tax treatments on the same site (e.g. UK VAT and US sales tax)

Having different pricing and availability policies for different customers. More generally, it provides a structure for customising how pricing, availability work on a per-customer basis. This gives a great deal of flexibility. See the guide to prices and availability for more information.

Permission-based dashboard¶ Three changes were necessary to better support marketplace scenarios within Oscar: Oscar’s core Application class now supports specifying permissions on a per-view basis. This is done via a new default decorator. Legacy behaviour is unchanged.

The dashboard’s menus are now built dynamically. If the current user does not have access to some views in OSCAR_DASHBOARD_NAVIGATION, they will be omitted in the menu returned by oscar.apps.dashboard.nav.create_menu() .

The index, catalogue and order dashboard views have been modified to allow access to non-staff users. See the dashboard documentation for details.

The relation oscar.apps.partner.abstract_models.AbstractPartner.users was not used by core Oscar prior 0.6. It is now used to model access for the permission-based dashboard.

Payment models have abstract versions¶ The models within the payment app have been split into abstract and concrete versions. This brings them inline with other Oscar apps and allows them to be customised in the normal way.

Wishlists¶ Wishlist functionality has finally landed. Signed in customers are now able to create multiple named wishlists and add products to them. There is a new section in the customer’s account where wishlists can be managed. See the wishlist documentation for more details.

Partner dashboard & addresses¶ Partners can now have addresses. These are useful for US sales tax where tax calculations need to know the origin of a product being shipped. A dashboard to handle partners, their users and addresses has been added.

Checkout¶ The PaymentDetailsView checkout view has been restructured for flexibility. There is a new build_submission() method which is responsible for building a dict of all data for passing to the submit method. This includes the shipping address and shipping method which were previously loaded indirectly within the submit method. Warning While not major, the changes to checkout are backwards incompatible. See the backwards compatibility notes for more details.

Demo site¶ Oscar now ships with a demo site along side the sandbox site. While the sandbox is a minimal Django project that uses Oscar with all its defaults, the demo site is a more realistic example of an Oscar project. It has a custom skin and makes many alterations to the default Oscar behaviour. It’s features include: A range of different product types: books, downloads, clothing

PayPal Express integration using django-oscar-paypal

DataCash integration using django-oscar-datacash See the sandbox and demo site documentation for more details. A publicly accessible version of the demo site is available at http://demo.oscarcommerce.com.

Django 1.5, 1.6 and custom user model support¶ Oscar now supports Django 1.5 and, experimentally, 1.6. Specifically, Oscar supports custom user models, the headline new feature in Django 1.5. These can be used standalone or with a one-to-one profile model: Oscar’s account forms inspect the model fields to dynamically pick up the fields for editing and display. There are some restrictions on what fields a custom user model must have. For instance, Oscar’s default authentication backend requires the user model to have an email and password field. New Oscar projects are encouraged to use the provided abstract user model as the base for their users. Support for Django 1.6 is considered experimental at the moment as there hasn’t been time to run thorough tests for all possible incompatibilities. Further reading: How to use a custom user model.

Accounts¶ The views and templates of the accounts section have been reworked to be clearer and easier to extend. There is no longer a generic front page for the accounts section - instead, each subsection has its own page. The navigation has also moved to the left-hand side.

Bootstrap-WYSIHTML5 replaced by TinyMCE¶ TinyMCE 4.0 is now used in the dashboard for all textarea elements with the class wysiwyg . This has better browser support and is easier to customise than bootstrap-wysihtml5 (which has now been removed). It is easy to configure or replace with the HTML editor of your choice.

Improved address fields¶ The postcode and phone number fields have been improved. The postcode field is now validated in the model’s clean() method to ensure it is valid for the selected country.

The phone number field now uses a specialist PhoneNumberField field class which validates and cleans the phone number.

Better bankcard handling¶ In 0.5, there were two classes that representing a bankcard. These have been merged - the new version is AbstractBankcard . An instance of this model is returned by the bankcard property.

Customer-facing range pages¶ Ranges can now be flagged as public which means they get a customer-facing detail page which shows a range description and allows its products to be browsed. In the dashboard, the display order of the range’s products can be controlled. To this end, the core Range model has been extended with a HTML description field.

Reworked search app¶ Oscar’s search app has been reviewed and simplified. The main view class (now FacetedSearchView ) has been reworked to provide better support for faceting, which can be easily specified using the OSCAR_SEARCH_FACETS setting. The SuggestionsView has been removed as it wasn’t being used. A later version of Oscar will include a replacement. See the search app documentation for more details.

Order processing changes¶ The core EventHandler class has been extended. The handle_shipping_event method now validates a proposed shipping event before saving it.

The handle_payment_event method now validates a proposed payment event before saving it. See the EventHandler for the available methods.

Tracking Oscar sites¶ Oscar’s dashboard now serves a single pixel image from one of Tangent’s servers. This is included to gather information on which sites use Oscar, which is an important metric for Tangent, who sponsor Oscar’s development. It can easily be disabled by setting OSCAR_TRACKING=False . If you do opt out, please email the mailing list with any production Oscar sites you are running. This will help to ensure investment in Oscar’s future.