Store Customization
===================

The real power of Satchmo is not in what it does out of the box but what
the framework allows you to do with minimal modification.  As you start
to develop your online presence you will have a whole range of different
ideas on how you would like to make your store look and feel.  Satchmo 
provides a simple store layout that you can modify as much or as little 
as you wish.  There are several ways to tweak Satchmo to your needs.  The
following list is in order of the relative ease of customization:

1.  CSS customization
2.  Template customization
3.  URL customization
4.  Checkout process customization
5.  Shipping module customization
6.  Payment module customization
7.  Changing views
8.  Creating custom template tags

CSS Customization
-----------------

The simplest way to modify Satchmo is to change the attributes in the css
file used by the default shop.  The current style.css file is located in
/satchmo/static/css.  You can modify this file directly (not recommended) or
create a new CSS file and modify the base.html template file to point to
your new and improved css file.

The benefits of this approach is that it is simple to implement and makes it
easy to update Satchmo as changes are made.  The downside is that there is 
only so much you can do with css changes.

Template Customization
----------------------

Template customization allows you to completely alter the look and feel of 
your site without having to resort to coding.  The majority of the display 
elements are accessible via css or template changes. Before making any template 
changes, it would be useful to understand Django templates in general.  
The `Django Template Author Guide`_ is the best place to start.

Once you are ready to make template changes, the best option is to copy any of the
templates that you wish to override to a new location.
 
Next, modify settings.py to point to your new templates directory::

    TEMPLATE_DIRS = (
        # Put strings here, like "/home/html/django_templates".
        # Always use forward slashes, even on Windows.
        "/my/new/templates",)


Now, make the changes to the templates that you have to.  Don't forget, this is
also the place where you can change the email messages sent to users as well as
the pdf documents created by the admin interface.  The amount of power and flexibility
here is much higher than just about any "shopping cart" application out there!


URL Customization
-----------------

Another nifty feature of Django is the flexibility in configuring the URLs of an 
application.  Because a web store frequently requires good search engine ranking, 
you will most likely want to do everything in your power to help your store rise
in the rankings.  Using good, clean descriptive URLs is a huge plus.  Another benefit
of flexible URLs is that allows you to easily integrate Satchmo with an existing
site or differentiate your site with a creative scheme (or language).

For convenience, urls can be modified by changing the SHOP_URLS variable in the
local_settings.py file.  Any url assigned to this variable will override the existing
url naming scheme.

Additionally, the Satchmo settings application allows you to change some of the names of
urls associated with products and categories.

Shipping Module Customization
-----------------------------

The comments in the dummy.py shipping module walk through how to configure shipping for your
unique needs.

Payment Module Customization
----------------------------
See :ref:`Custom Payment Modules <custom-payment-modules>`

Using Signals
-------------
See :ref:`Signals in Satchmo <signals>` for an explanation of the available signals and how to use them to
customize your store.

.. _Django Template Author Guide: http://www.djangoproject.com/documentation/templates/

Changing Views
--------------

In some instances, you may wish to selectively override specific Satchmo views. Satchmo includes
a useful utility- ``replace_urlpattern`` in satchmo_utils.urlhelper to exchange stock urls
with your own.

Here is a simple example of using it to replace the quick_order view. In this example, we wish to change
the items that are displayed on the quick order page so that only featured items are shown. The full 
urls.py is shown below::

    from django.conf.urls.defaults import *

    # Uncomment the next two lines to enable the admin:
    # from django.contrib import admin
    # admin.autodiscover()

    from satchmo_store.urls import urlpatterns

    from satchmo_utils.urlhelper import replace_urlpattern
    from product.models import Product

    product_list = Product.objects.filter(featured=True)

    replacement = url(r'^quickorder/$', 'satchmo_store.shop.views.cart.add_multiple', 
                {'products': product_list}, 'satchmo_quick_order')
    replace_urlpattern(urlpatterns, replacement)

Custom Template Tags and Filters
---------------------------------

If you find yourself in a situation where you need to display additional information on the page
or where you need to change the way data is displayed, you should consider writing a custom template tag
or filter. The general process for using the tag or filter would be:

    1. Create the new tag in your application's templatetags directory
    2. Selectively override the Satchmo templates that use the tag
    3. Import the new tag at the top of each template and use it in the template
