Cartridge 0.8.0

A Django shopping cart application.

.. image:: https://secure.travis-ci.org/stephenmcd/cartridge.png?branch=master
:target: http://travis-ci.org/#!/stephenmcd/cartridge

Created by `Stephen McDonald <http://twitter.com/stephen_mcd>`_

========
Overview
========

Cartridge is a shopping cart application built using the `Django`_
framework. It is `BSD licensed`_ and designed to provide a clean and
simple base for developing e-commerce websites. It purposely does not
include every conceivable feature of an e-commerce website; instead,
Cartridge focuses on providing core features common to most e-commerce
websites.

This specific focus stems from the idea that every e-commerce website
is different, is tailored to the particular business and products at
hand, and should therefore be as easy to customize as possible.
Cartridge achieves this goal with a code-base that is as simple as
possible and implements only the core features of an e-commerce
website.

Cartridge extends the `Mezzanine`_ content management platform. A live
demo of Cartridge can be found by visiting the `Mezzanine live demo`_.

Features
========

* Hierarchical categories
* Easily configurable product options (colours, sizes, etc.)
* Hooks for shipping calculations and payment gateways
* Sale pricing
* Promotional discount codes
* PDF invoice generation (for packing slips)
* Stock control
* Product popularity
* Thumbnail generation
* Built-in test suite
* Separation of presentation (no embedded markup)
* Smart categories (by price range, colour, etc)
* Registered or anonymous checkout
* Configurable number of checkout steps
* Denormalised data for accessiblilty and performance
* Authenticated customer accounts with transaction history

Dependencies
============

Cartridge is designed as a plugin for the `Mezzanine`_ content
management platform and, as such, requires `Mezzanine`_ to be
installed. The integration of the two applications should occur
automatically by following the installation instructions below.

Installation
============

The easiest method is to install directly from pypi using `pip`_ by
running the command below, which will also install the required
dependencies mentioned above::

$ pip install -U cartridge

Otherwise, you can download Cartridge and install it directly from source::

$ python setup.py install

Once installed, the command ``mezzanine-project`` can be used to
create a new Mezzanine project, with Cartridge installed, in similar
fashion to ``django-admin.py``::

$ mezzanine-project -a cartridge project_name
$ cd project_name
$ python manage.py createdb --noinput
$ python manage.py runserver

Here we specify the ``-a`` switch for the ``mezzanine-project`` command,
which tells it to use an alternative package (cartridge) for the project
template to use. Both Mezzanine and Cartridge contain a project template
package containing the ``settings.py`` and ``urls.py`` modules for an
initial project. If you'd like to add Cartridge to an existing Mezzanine
or Django project, you'll need to manually configure these yourself. See
the `FAQ section of the Mezzanine documentation`_ for more information.

.. note::

The ``createdb`` is a shortcut for using Django's ``syncdb``
command and setting the initial migration state for `South`_. You
can alternatively use ``syncdb`` and ``migrate`` if preferred.
South is automatically added to INSTALLED_APPS if the
``USE_SOUTH`` setting is set to ``True``.

You should then be able to browse to http://127.0.0.1:8000/admin/ and
log in using the default account (``username: admin, password:
default``). If you'd like to specify a different username and password
during set up, simply exclude the ``--noinput`` option included above
when running ``createdb``.

Contributing
============

Cartridge is an open source project managed using both the Git and
Mercurial version control systems. These repositories are hosted on
both `GitHub`_ and `Bitbucket`_ respectively, so contributing is as
easy as forking the project on either of these sites and committing
back your enhancements.

Please note the following guidelines for contributing:

* Contributed code must be written in the existing style. This is
as simple as following the `Django coding style`_ and (most
importantly) `PEP 8`_.
* Contributions must be available on a separately named branch
based on the latest version of the main branch.
* Run the tests before committing your changes. If your changes
cause the tests to break, they won't be accepted.
* If you are adding new functionality, you must include basic tests
and documentation.

If you want to do development with Cartridge, here's a quick way to set
up a development environment and run the Cartridge unit tests, using
`virtualenvwrapper`_ to set up a virtualenv::

$ mkvirtualenv cartridge
$ workon cartridge
$ pip install -e git://github.com/stephenmcd/mezzanine.git#egg=mezzanine
$ pip install pep8 pyflakes
$ git clone https://github.com/stephenmcd/cartridge
$ cd cartridge
$ python setup.py develop
$ cp cartridge/project_template/local_settings.py.template cartridge/project_template/local_settings.py
$ ./cartridge/project_template/manage.py test shop


Language Translations
=====================

Cartridge makes full use of translation strings, which allow Cartridge
to be translated into multiple languages using `Django's
internationalization`_ methodology. Translations are managed on the
`Transiflex`_ website but can also be submitted via `GitHub`_ or
`Bitbucket`_. Consult the documentation for `Django's
internationalization`_ methodology for more information on creating
translations and using them.

Donating
========

If you would like to make a donation to continue development of
Cartridge, you can do so via the `Mezzanine Project`_ website.

Support
=======

To report a security issue, please send an email privately to
`[e-mail]`_. This gives us a chance to fix the issue and
create an official release prior to the issue being made
public.

For general questions or comments, please join the `mezzanine-users`_
mailing list. To report a bug or other type of issue, please use the
`GitHub issue tracker`_. And feel free to drop by the `#mezzanine
IRC channel`_ on `Freenode`_, for a chat.

Sites Using Cartridge
=====================

* `Ripe Maternity <http://www.ripematernity.com>`_
* `Cotton On <http://shop.cottonon.com>`_
* `Coopers Store <http://store.coopers.com.au>`_
* `Sheer Ethic <http://sheerethic.com>`_
* `tindie.com <http://tindie.com>`_
* `Ross A. Laird <http://rosslaird.com/shop>`_
* `Pink Twig <http://www.pinktwig.ca/shop>`_
* `Parfume Planet <http://parfumeplanet.com>`_
* `Life is Good <http://lifeisgoodforall.co.uk/>`_
* `Brooklyn Navy Yard <http://bldg92.org/>`_
* `Cotton On Asia <http://asia.cottonon.com/>`_
* `Manai Glitter <https://manai.co.uk>`_
* `Tactical Bags <http://tacticalbags.ru>`_
* `Charles Koll Jewelry <http://charleskoll.com>`_
* `Puraforce Remedies <http://puraforceremedies.com/>`_
* `Adrenaline <http://www.adrln.com/>`_

.. _`Django`: http://djangoproject.com/
.. _`BSD licensed`: http://www.linfo.org/bsdlicense.html
.. _`Mezzanine live demo`: http://mezzanine.jupo.org/
.. _`pip`: http://www.pip-installer.org/
.. _`FAQ section of the Mezzanine documentation`: http://mezzanine.jupo.org/docs/frequently-asked-questions.html#how-can-i-add-mezzanine-to-an-existing-django-project
.. _`setuptools`: http://pypi.python.org/pypi/setuptools
.. _`Mezzanine`: http://mezzanine.jupo.org/
.. _`South`: http://south.aeracode.org/
.. _`Github`: http://github.com/stephenmcd/cartridge/
.. _`Bitbucket`: http://bitbucket.org/stephenmcd/cartridge/
.. _`mezzanine-users`: http://groups.google.com/group/mezzanine-users
.. _`Github issue tracker`: http://github.com/stephenmcd/cartridge/issues
.. _`Django coding style`: http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
.. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/
.. _`Transiflex`: https://www.transifex.net/projects/p/mezzanine/
.. _`[e-mail]`: mailto:[e-mail]?subject=Mezzanine+Security+Issue
.. _`#mezzanine IRC channel`: irc://freenode.net/mezzanine
.. _`Freenode`: http://freenode.net
.. _`Django's internationalization`: https://docs.djangoproject.com/en/dev/topics/i18n/translation/
.. _`virtualenvwrapper`: http://www.doughellmann.com/projects/virtualenvwrapper