<commit_before>==========
Components
==========

The following section describes the various components of Cartridge and the Django models used.

Products
========

Products are the cornerstone of Cartridge and are made up from three
separate models. First, the model ``Product`` provides the container for
storing the core attributes of a product. The other two models are
``ProductImage`` and ``ProductVariation`` which each contain a
ForeignKeyField to ``Product`` and can be accessed via ``Product.images``
and ``Product.variations`` respectively.

As with the ``Category`` model, the ``Product`` model inherits from the
abstract model ``Displayable``. It also inherits from the abstract model
``Priced`` which is discussed next. The fields provided by the ``Priced``
model are not editable via the admin. The rationale for this is discussed
later in :ref:`ref-denormalized-fields`.

.. _ref-priced-items:

Priced Items
------------

The ``Priced`` abstract model provides common features for an item that
has a price. It contains fields such as ``Priced.unit_price`` for the base
price and three fields that control whether the given item is on sale:

    * ``Priced.sale_price`` for the sale price
    * ``Priced.sale_from`` DateTimeField for the start of the sale
    * ``Priced.sale_to`` DateTimeField for the end of the sale

The ``Priced`` model also contains several convenience methods:

    * ``Priced.on_sale()`` for checking whether the current price is a sale price
    * ``Priced.has_price()`` for checking whether there is a current price at all
    * ``Priced.price()`` which returns the current price of either ``Priced.unit_price`` or ``Priced.sale_price`` if applicable

The ``Priced`` abstract model is inherited by the ``Product`` model
previously discussed and the ``ProductVariation`` model discussed next.

Product Variations
------------------

The ``ProductVariation`` model represents a unique combination of options
for a product. Consider a shirt that comes in two colours and three sizes:
these combinations would be represented with a single ``Product`` instance for the shirt
and six ``ProductVariation`` instances: one for each colour/size combination.
These options are discussed below in :ref:`ref-product-options`.

The ``ProductVariation`` model is editable via the admin as the inline
``ProductVariationAdmin`` for the ``ProductAdmin`` admin; however, the
attribute ``ProductVariationAdmin.extra`` is set to ``0`` and therefore
``ProductVariation`` instances cannot be added via the admin. Instead, when
editing ``Product`` instances via the admin, a list of check-boxes is
provided with the form for each type of option available such as colour
and size, with a check-box provided for each individual option.
When the ``Product`` instance is saved, a set of related ``ProductVariation``<commit_msg>Added a section about categories as pages to the docs.<commit_after>==========
Components
==========

The following section describes the various components of Cartridge and the Django models used.

Categories
==========

A category is the main approach for displaying products on the website.
Categories in Cartridge are implemented as Mezzanine pages. Consult the
`Mezzanine documentation
<http://mezzanine.jupo.org/docs/content-architecture.html#the-page-model>`_ for a detailed overview of how pages are implemented in Mezzanine.

Products
========

Products are the cornerstone of Cartridge and are made up from three
separate models. First, the model ``Product`` provides the container for
storing the core attributes of a product. The other two models are
``ProductImage`` and ``ProductVariation`` which each contain a
ForeignKeyField to ``Product`` and can be accessed via ``Product.images``
and ``Product.variations`` respectively.

As with the ``Category`` model, the ``Product`` model inherits from the
abstract model ``Displayable``, which provides the model with features such as a URL/slug, and publish dates. It also inherits from the abstract model
``Priced`` which is discussed next. The fields provided by the ``Priced``
model are not editable via the admin. The rationale for this is discussed
later in :ref:`ref-denormalized-fields`.

.. _ref-priced-items:

Priced Items
------------

The ``Priced`` abstract model provides common features for an item that
has a price. It contains fields such as ``Priced.unit_price`` for the base
price and three fields that control whether the given item is on sale:

    * ``Priced.sale_price`` for the sale price
    * ``Priced.sale_from`` DateTimeField for the start of the sale
    * ``Priced.sale_to`` DateTimeField for the end of the sale

The ``Priced`` model also contains several convenience methods:

    * ``Priced.on_sale()`` for checking whether the current price is a sale price
    * ``Priced.has_price()`` for checking whether there is a current price at all
    * ``Priced.price()`` which returns the current price of either ``Priced.unit_price`` or ``Priced.sale_price`` if applicable

The ``Priced`` abstract model is inherited by the ``Product`` model
previously discussed and the ``ProductVariation`` model discussed next.

Product Variations
------------------

The ``ProductVariation`` model represents a unique combination of options
for a product. Consider a shirt that comes in two colours and three sizes:
these combinations would be represented with a single ``Product`` instance for the shirt
and six ``ProductVariation`` instances: one for each colour/size combination.
These options are discussed below in :ref:`ref-product-options`.

The ``ProductVariation`` model is editable via the admin as the inline
``ProductVariationAdmin`` for the ``ProductAdmin`` admin; however, the
attribute ``ProductVariationAdmin.extra`` is set to ``0`` and therefore
``ProductVariation`` instances cannot be added via the admin. Instead, when
editing ``Product`` instances via the admin, a list of check-boxes is
provided with the form, for each type of option available such as colour
and size, with a check-box provided for each individual option.
When the ``Product`` instance is saved, a set of related ``ProductVariation``
{'fraction_non_alphanumeric': 0.09680573663624512, 'fraction_numerical': 0.0003259452411994785, 'mean_word_length': 4.800567107750473, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4397240', 'n_tokens_mistral': 1564, 'n_tokens_neox': 1510, 'n_words': 808}