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 the AddToBasketForm 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 the Option model (previously used to denote whether the option is required) has been repurposed to store the type of the option, and a new required 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 in catalogue/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 the Offer model which requires a database migration.

  • The base ReportGenerator class has been refactored to make it easier to use. Subclasses must now define either a model_class or queryset to indicate which model/queryset the report generator should use, or alternatively override the get_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 and meta_description have been added to both the Product and Category 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 to StockRecord.price. Projects that have forked the partner app will need to generate their own migration to rename this field.

  • The annotate_form_field template tag will now set the widget_type in the format used by Django 3.1: so no longer CheckboxInput, but just checkbox.

  • The signature of the shipping_discount methods on Offer and Benefit has changed to accept an optional currency 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 optional currency argument, which is now supplied when calling those methods. The currency is also passed to any custom rounding function that is defined using OSCAR_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 a SimpleLazyObject when assigned to Product.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 and partner apps will need to generate their own migrations to remove these fields.

  • customer.notifications.services.notify_user and customer.notifications.services.notify_users have been removed. Use communication.utils.Dispatcher.notify_user and Use communication.utils.Dispatcher.notify_users respectively instead.

  • customer.alerts.utils.send_alerts, customer.alerts.utils.send_alert_confirmation and customer.alerts.utils.send_product_alerts have been removed. Use customer.alerts.utils.AlertsDispatcher.send_alerts, customer.alerts.utils.AlertsDispatcher.send_product_alert_confirmation_email_for_user and customer.alerts.utils.AlertsDispatcher.send_product_alert_email_for_user respectively instead.

  • The CommunicationEventType, Email and Notification models that moved from the customer app to the communication 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 by settings.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. Check Option.required instead.