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.

COMPARISON_FIELDS = ('pk', 'path', 'depth')

Allow comparison of categories on a limited number of fields by ranges. When the Category model is overwritten to provide CMS content, defining this avoids fetching a lot of unneeded extra data from the database.

class Meta

classmethod fix_tree(destructive=False, fix_paths=False)

Solves some problems that can appear when transactions are not used and a piece of code breaks, leaving the tree in an inconsistent state.

The problems this method solves are:

1. Nodes with an incorrect depth or numchild values due to incorrect code and lack of database transactions.

2. “Holes” in the tree. This is normal if you move/delete nodes a lot. Holes in a tree don’t affect performance,

3. Incorrect ordering of nodes when node_order_by is enabled. Ordering is enforced on node insertion, so if an attribute in node_order_by is modified after the node is inserted, the tree ordering will be inconsistent.

Parameters

• fix_paths – A boolean value. If True, a slower, more complex fix_tree method will be attempted. If False (the default), it will use a safe (and fast!) fix approach, but it will only solve the depth and numchild nodes, it won’t fix the tree holes or broken path ordering.

• destructive – Deprecated; alias for fix_paths.

property 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, but used to be stored as a CharField and is hence kept for backwards compatibility. It’s also sufficiently useful to keep around.

property 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_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.

The type of the option determines the form input that will be used to collect the information from the customer, and the required attribute determines whether a value must be supplied in order to add the item to the basket.

clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

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.

property 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 public categories or parent’s if there is a parent product.

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

property has_stockrecords

Test if this product has any stockrecords

is_discountable

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.

property 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.

refresh_from_db(using=None, fields=None)

Reload field values from the database.

By default, the reloading happens from the database this instance was loaded from, or by the read router if this instance wasn’t loaded from any database. The using parameter will override the default.

Fields can be used to specify which fields to reload. The fields should be an iterable of field attnames. If fields is None, then all non-deferred fields are reloaded.

When accessing deferred fields of an instance, the deferred loading of the field will call this method.

save(*args, **kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

property sorted_recommended_products

Keeping order by recommendation ranking.

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)

bind_value(value_obj, value)

bind_value will bind the value passed to the value_obj, if the bind_value return None, that means the value_obj is supposed to be deleted.

clean()

Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

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

The “through” model for the m2m relationship between Product and 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.

property 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.

property 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

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

track_stock

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

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.ReverseStartsWith(*args, **kwargs)

Adds a new lookup method to the django query language, that allows the following syntax:

henk__rstartswith="koe"

The regular version of startswith:

   henk__startswith="koe"

Would be about the same as the python statement::

   henk.startswith("koe")

ReverseStartsWith will flip the right and left hand side of the expression, effectively making this the same query as:

"koe".startswith(henk)

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

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

get(request, *args, **kwargs)

Ensures that the correct URL is used before rendering a response

get_context_data(**kwargs)

Insert the single object into the context dict.

get_object(queryset=None)

Return the object the view is displaying.

Require self.queryset and a pk or slug argument in the URLconf. Subclasses can override this to return any object.

get_template_names()

Return a list of possible templates.

If an overriding class sets a template name, we use that. Otherwise, we try 2 options before defaulting to catalogue/detail.html:

1. detail-for-upc-upc.html

2. detail-for-class-classname.html

This allows alternative templates to be provided for a per-product and a per-item-class basis.

model

alias of Product