Oscar 3.0 release notes¶
- release
2021-01-27
Welcome to Oscar 3.0!
This is a significant release, in which all of Oscar’s core templates and styles have been ported to Bootstrap 4. Support for Bootstrap 3 has been dropped, and projects that upgrade to Oscar 3 will also need to upgrade their frontend and dashboard templates to use Bootstrap 4.
Compatibility¶
Oscar 3.0 is compatible with Django 2.2, Django 3.0 and Django 3.1 as well as Python 3.6, 3.7 and 3.8.
Support for Django 1.11 and Django 2.1 has been dropped. Support for Python 3.5 has been dropped.
What’s new in Oscar 3.0?¶
Oscar 3.0 features a major upgrade of Oscar’s default templates and styles to use Bootstrap version 4.5. Both the front-end and dashboard templates have been refactored to work with Bootstrap 4. This is a major, non-backward compatible change for projects that rely on or extend the default Oscar templates.
The Bootstrap 4 migration guide is a helpful resource for migration from version 3.
As with Bootstrap 4 itself, Oscar’s default styles are now defined using SASS instead of LESS.
To replace Bootstrap 3’s Glyphicons, Oscar’s default templates now rely on Font Awesome.
Support was added to the
catalogue.Option
model to define the type of option. This is used by theAddToBasketForm
to determine the appropriate form field to display for that option in the add-to-cart form. Currently supported types are: text, integer, float, boolean, and date.The
type
field on theOption
model (previously used to denote whether the option is required) has been repurposed to store the type of the option, and a newrequired
field has been added to denote whether the option is required. Projects that have forked the catalogue app will need to generate custom migrations for these model field changes. Projects should pay close attention to the data migration provided incatalogue/migrations/0019_option_required.py
for this change.Added support for restricted combinations of offers. When creating an offer in the dashboard, administrators can now define a restricted set of other offers that offer can be used in combination with. This changes introduces a new
combinations
field on theOffer
model which requires a database migration.The base
ReportGenerator
class has been refactored to make it easier to use. Subclasses must now define either amodel_class
orqueryset
to indicate which model/queryset the report generator should use, or alternatively override theget_queryset()
method. Failure to do one of these will result in an exception.Filtering by date range is now properly applied during CSV export of reports.
New fields
meta_title
andmeta_description
have been added to both theProduct
andCategory
models, which can be used to override the HTML title and meta description content for product and category pages. These are editable from the search engine optimisation tab in the dashboard edit views for products and categories respectively. A database migration is required for this change.
Backwards incompatible changes¶
The
StockRecord.price_excl_tax
field has been renamed toStockRecord.price
. Projects that have forked thepartner
app will need to generate their own migration to rename this field.The
annotate_form_field
template tag will now set thewidget_type
in the format used by Django 3.1: so no longerCheckboxInput
, but justcheckbox
.The signature of the
shipping_discount
methods onOffer
andBenefit
has changed to accept an optionalcurrency
argument, which is now supplied when calling those methods. This allows currency-aware determination of shipping discounts.The signature of the
Benefit.round
method has changed to accept an optionalcurrency
argument, which is now supplied when calling those methods. The currency is also passed to any custom rounding function that is defined usingOSCAR_OFFER_ROUNDING_FUNCTION
. This allows currency-aware rounding.
Bug fixes¶
catalogue.product_attributes.ProductAttributesContainer
was refactored to ensure that attributes inside the container are always properly loaded at initialisation. The container is now wrapped in aSimpleLazyObject
when assigned toProduct.attr
.ProductAttributesContainer.initiate_attributes()
was removed as the database query now happens on instantiation.Fixed the handling of multiple non-exclusive offers with a count condition (#3162).
Removal of deprecated features¶
Several deprecated model fields have been removed in Oscar 3.0:
order.Line.est_dispatch_date
order.Line.unit_cost_price
order.Line.unit_retail_price
partner.StockRecord.cost_price
partner.StockRecord.price_retail
Oscar ships with migrations that remove these fields. If you want to continue using them, please make sure you add the fields back to your forked app before migrating. Projects that have forked the
order
andpartner
apps will need to generate their own migrations to remove these fields.customer.notifications.services.notify_user
andcustomer.notifications.services.notify_users
have been removed. Usecommunication.utils.Dispatcher.notify_user
and Usecommunication.utils.Dispatcher.notify_users
respectively instead.customer.alerts.utils.send_alerts
,customer.alerts.utils.send_alert_confirmation
andcustomer.alerts.utils.send_product_alerts
have been removed. Usecustomer.alerts.utils.AlertsDispatcher.send_alerts
,customer.alerts.utils.AlertsDispatcher.send_product_alert_confirmation_email_for_user
andcustomer.alerts.utils.AlertsDispatcher.send_product_alert_email_for_user
respectively instead.The
CommunicationEventType
,Email
andNotification
models that moved from thecustomer
app to thecommunication
app in Oscar 2.1 can no longer be dynamically loaded from their old paths.
Minor changes¶
Several models were updated to define a default ordering, to avoid issues with inconsistent ordering of items in the dashboard and elsewhere. Database migrations are required for these changes. Models affected are:
analytics.UserProductView
analytics.UserSearch
catalogue.Option
communication.CommunicationEventType
communication.Email
customer.ProductAlert
offer.Range
order.OrderDiscount
order.OrderNote
payment.Source
payment.SourceType
voucher.VoucherSet
voucher.Voucher
voucher.VoucherApplication
Database indexes were added to several model fields to improve query efficiency. Affected fields are:
catalogue.Option.name
communication.CommunicationEventType.name
customer.ProductAlert.date_created
payment.SourceType.name
voucher.VoucherSet.date_created
voucher.Voucher.date_created
voucher.VoucherApplication.date_created
Category slugs can now be edited via the dashboard.
A new method
get_attribute_values()
was added to the Product model which returns a merged set of attribute values for child and parent products.The behaviour of
checkout.views.ThankYouView
when no order is found in the session has changed, to redirect the user to the URL defined bysettings.OSCAR_HOMEPAGE
instead of returning a page not found error.
Dependency changes¶
Python package dependencies:
Upgraded
django-tables2
to version 2.3.
Javascript and CSS dependencies:
Upgraded
bootstrap
to version 4.5.3.Added
tempusdominus-bootstrap-4
version 5.1, use for Bootstrap 4 datepicker inputs.Upgraded
tinymce
to version 5.6.
Deprecated features¶
The
catalogue.Option.is_required
is deprecated. CheckOption.required
instead.