Catalogue

This is an essential Oscar app which exposes functionality to manage your product catalogue. oscar.apps.catalogue.abstract_models.AbstractProduct is its main model. The catalogue app also includes views specific to viewing a list or individual products.

Abstract models

class oscar.apps.catalogue.abstract_models.AbstractAttributeOption(*args, **kwargs)

Provides an option within an option group for an attribute type Examples: In a Language group, English, Greek, French

class oscar.apps.catalogue.abstract_models.AbstractAttributeOptionGroup(*args, **kwargs)

Defines a group of options that collectively may be used as an attribute type

For example, Language

class oscar.apps.catalogue.abstract_models.AbstractCategory(*args, **kwargs)

A product category. Merely used for navigational purposes; has no effects on business logic.

Uses django-treebeard.

ensure_slug_uniqueness()

Ensures that the category’s slug is unique amongst it’s siblings. This is inefficient and probably not thread-safe.

full_name

Returns a string representation of the category and it’s ancestors, e.g. ‘Books > Non-fiction > Essential programming’.

It’s rarely used in Oscar’s codebase, but used to be stored as a CharField and is hence kept for backwards compatibility. It’s also sufficiently useful to keep around.

full_slug

Returns a string of this category’s slug concatenated with the slugs of it’s ancestors, e.g. ‘books/non-fiction/essential-programming’.

Oscar used to store this as in the ‘slug’ model field, but this field has been re-purposed to only store this category’s slug and to not include it’s ancestors’ slugs.

generate_slug()

Generates a slug for a category. This makes no attempt at generating a unique slug.

get_absolute_url()

Our URL scheme means we have to look up the category’s ancestors. As that is a bit more expensive, we cache the generated URL. That is safe even for a stale cache, as the default implementation of ProductCategoryView does the lookup via primary key anyway. But if you change that logic, you’ll have to reconsider the caching approach.

get_ancestors_and_self()

Gets ancestors and includes itself. Use treebeard’s get_ancestors if you don’t want to include the category itself. It’s a separate function as it’s commonly used in templates.

get_descendants_and_self()

Gets descendants and includes itself. Use treebeard’s get_descendants if you don’t want to include the category itself. It’s a separate function as it’s commonly used in templates.

save(*args, **kwargs)

Oscar traditionally auto-generated slugs from names. As that is often convenient, we still do so if a slug is not supplied through other means. If you want to control slug creation, just create instances with a slug already set, or expose a field on the appropriate forms.

class oscar.apps.catalogue.abstract_models.AbstractOption(*args, **kwargs)

An option that can be selected for a particular item when the product is added to the basket.

For example, a list ID for an SMS message send, or a personalised message to print on a T-shirt.

This is not the same as an ‘attribute’ as options do not have a fixed value for a particular item. Instead, option need to be specified by a customer when they add the item to their basket.

class oscar.apps.catalogue.abstract_models.AbstractProduct(*args, **kwargs)

The base product object

There’s three kinds of products; they’re distinguished by the structure field.

• A stand alone product. Regular product that lives by itself.
• A child product. All child products have a parent product. They’re a specific version of the parent.
• A parent product. It essentially represents a set of products.

An example could be a yoga course, which is a parent product. The different times/locations of the courses would be associated with the child products.

attribute_summary

Return a string of all of a product’s attributes

calculate_rating()

Calculate rating value

can_be_parent(give_reason=False)

Helps decide if a the product can be turned into a parent product.

clean()

Validate a product. Those are the rules:

	stand alone	parent	child
title	required	required	optional
product class	required	required	must be None
parent	forbidden	forbidden	required
stockrecords	0 or more	forbidden	0 or more
categories	1 or more	1 or more	forbidden
attributes	optional	optional	optional
rec. products	optional	optional	unsupported
options	optional	optional	forbidden

Because the validation logic is quite complex, validation is delegated to the sub method appropriate for the product’s structure.

get_absolute_url()

Return a product’s absolute url

get_categories()

Return a product’s categories or parent’s if there is a parent product.

get_is_discountable()

At the moment, is_discountable can’t be set individually for child products; they inherit it from their parent.

get_missing_image()

Returns a missing image object.

get_product_class()

Return a product’s item class. Child products inherit their parent’s.

get_title()

Return a product’s title or it’s parent’s title if it has no title

has_stockrecords

Test if this product has any stockrecords

is_discountable = None

Determines if a product may be used in an offer. It is illegal to discount some types of product (e.g. ebooks) and this field helps merchants from avoiding discounting such products Note that this flag is ignored for child products; they inherit from the parent product.

is_review_permitted(user)

Determines whether a user may add a review on this product.

Default implementation respects OSCAR_ALLOW_ANON_REVIEWS and only allows leaving one review per user and product.

Override this if you want to alter the default behaviour; e.g. enforce that a user purchased the product to be allowed to leave a review.

options

Returns a set of all valid options for this product. It’s possible to have options product class-wide, and per product.

primary_image()

Returns the primary image for a product. Usually used when one can only display one product image, e.g. in a list of products.

product_class

“Kind” of product, e.g. T-Shirt, Book, etc. None for child products, they inherit their parent’s product class

product_options

It’s possible to have options product class-wide, and per product.

update_rating()

Recalculate rating field

class oscar.apps.catalogue.abstract_models.AbstractProductAttribute(*args, **kwargs)

Defines an attribute for a product class. (For example, number_of_pages for a ‘book’ class)

class oscar.apps.catalogue.abstract_models.AbstractProductAttributeValue(*args, **kwargs)

The “through” model for the m2m relationship between catalogue.Product and catalogue.ProductAttribute. This specifies the value of the attribute for a particular product

For example: number_of_pages = 295

summary()

Gets a string representation of both the attribute and it’s value, used e.g in product summaries.

value_as_html

Returns a HTML representation of the attribute’s value. To customise e.g. image attribute values, declare a _image_as_html property and return e.g. an <img> tag. Defaults to the _as_text representation.

value_as_text

Returns a string representation of the attribute’s value. To customise e.g. image attribute values, declare a _image_as_text property and return something appropriate.

class oscar.apps.catalogue.abstract_models.AbstractProductCategory(*args, **kwargs)

Joining model between products and categories. Exists to allow customising.

class oscar.apps.catalogue.abstract_models.AbstractProductClass(*args, **kwargs)

Used for defining options and attributes for a subset of products. E.g. Books, DVDs and Toys. A product can only belong to one product class.

At least one product class must be created when setting up a new Oscar deployment.

Not necessarily equivalent to top-level categories but usually will be.

options

These are the options (set by the user when they add to basket) for this item class. For instance, a product class of “SMS message” would always require a message to be specified before it could be bought. Note that you can also set options on a per-product level.

requires_shipping = None

Some product type don’t require shipping (eg digital products) - we use this field to take some shortcuts in the checkout.

track_stock = None

Digital products generally don’t require their stock levels to be tracked.

class oscar.apps.catalogue.abstract_models.AbstractProductImage(*args, **kwargs)

An image of a product

delete(*args, **kwargs)

Always keep the display_order as consecutive integers. This avoids issue #855.

display_order = None

Use display_order to determine which is the “primary” image

is_primary()

Return bool if image display order is 0

class oscar.apps.catalogue.abstract_models.AbstractProductRecommendation(*args, **kwargs)

‘Through’ model for product recommendations

class oscar.apps.catalogue.abstract_models.MissingProductImage(name=None)

Mimics a Django file field by having a name property.

sorl-thumbnail requires all it’s images to be in MEDIA_ROOT. This class tries symlinking the default “missing image” image in STATIC_ROOT into MEDIA_ROOT for convenience, as that is necessary every time an Oscar project is setup. This avoids the less helpful NotFound IOError that would be raised when sorl-thumbnail tries to access it.

class oscar.apps.catalogue.abstract_models.ProductAttributesContainer(product)

Stolen liberally from django-eav, but simplified to be product-specific

To set attributes on a product, use the attr attribute:

product.attr.weight = 125

Views

class oscar.apps.catalogue.views.CatalogueView(**kwargs)

Browse all products in the catalogue

class oscar.apps.catalogue.views.ProductCategoryView(**kwargs)

Browse products in a given category

get_categories()

Return a list of the current category and its ancestors