.. _ref-customization:

Customization
=============

As more sites are built using Pinax, more best practices will emerge, but for
now what we recommend is:

- Always work off a stable release. The most current release is 0.7.1.
- Use the pinax-admin :ref:`setup_project <customization-setupproject>` command.
- Make necessary changes to the ``settings.py`` and ``urls.py`` files in your
  copied directory.
- Change the domain and display name of the Site in the admin interface.
- Develop your custom apps under your new project or anywhere on Python path.
- Develop your own templates under your new project.

.. _ref-project:

Choosing a Project
------------------

Pinax provides several projects to use as a starting point for
customization.  Depending on your development style, you may prefer one project
over the other.

basic
    This project comes with the bare minimum set of applications and templates to
    get you started. It includes no extra tabs, only the profile and notices tabs are
    included by default. From here you can add any extra functionality and
    applications that you would like.

cms_company
    A very simple CMS that lets you set up templates and then edit content,
    including images, right in the frontend of the site.
    
    The sample media, templates and content including in the project demonstrate
    a basic company website.

cms_holidayhouse
    A very simple CMS that lets you set up templates and then edit content,
    including images, right in the frontend of the site.
    
    The sample media, templates and content including in the project demonstrate
    a basic site for holiday house rentals.

code
    This project demonstrates group functionality and the tasks, wiki and topics
    apps. It is intended to be the starting point for things like code project
    management where each code project gets its own wiki, task tracking system
    and threaded discussions.

intranet
    This project demonstrates a closed site requiring an invitation to join and
    not exposing any information publicly. It provides a top-level task tracking
    system, wiki and bookmarks. It is intended to be the starting point of sites
    like intranets.

private_beta
    This project demonstrates the use of a waiting list and signup codes for
    sites in private beta. Otherwise it is the same as basic_project.

sample_group
    This project demonstrates group functionality with a barebones group
    containing no extra content apps as well as two additional group types,
    tribes and projects, which show different membership approaches and
    content apps such as topics, wiki, photos and task management.

social
    This project demonstrates a social networking site. It provides profiles,
    friends, photos, blogs, tribes, wikis, tweets, bookmarks, swaps,
    locations and user-to-user messaging.
    
    In 0.5 this was called ``complete_project``.

zero
    This project lays the foundation for all other Pinax starter projects. It
    provides the project directory layout and some key infrastructure apps on
    which the other starter projects are based.

.. _customization-setupproject:

pinax-admin setup_project
-------------------------

Pinax provides you with ``pinax-admin``, a command line utility. With
``pinax-admin`` you can quickly generate a cloned project. For example, to get
started quickly with Pinax you could simply do the following::

    (mysite-env)$ pinax-admin setup_project mysite

Or if you want to use the ``basic`` project base you could do::

    (mysite-env)$ pinax-admin setup_project -b basic mysite


Settings You Will (Possibly) Want To Override
---------------------------------------------

Pinax-specific:

- ``PINAX_THEME``
- ``CONTACT_EMAIL``
- ``URCHIN_ID``
- ``BBAUTH_APP_ID``
- ``BBAUTH_SHARED_SECRET``
- ``SITE_NAME``
- ``MAILER_PAUSE_SEND``
- ``SERVE_MEDIA``
- ``ACCOUNT_OPEN_SIGNUP``
- ``ACCOUNT_REQUIRED_EMAIL``
- ``ACCOUNT_EMAIL_VERIFICATION``
- ``EMAIL_CONFIRMATION_DAYS``
- ``LOGIN_REDIRECT_URLNAME``


General to Django:

- ``DEBUG``
- ``TEMPLATE_DEBUG``
- ``LOGGING_OUTPUT_ENABLED``
- ``ADMINS``
- ``MANAGERS``
- ``DATABASE_ENGINE``
- ``DATABASE_NAME``
- ``DATABASE_USER``
- ``DATABASE_PASSWORD``
- ``DATABASE_HOST``
- ``TIME_ZONE``
- ``SECRET_KEY``
- ``DEFAULT_FROM_EMAIL``
- ``SERVER_EMAIL``
- ``SEND_BROKEN_LINK_EMAILS``
- ``EMAIL_HOST``
- ``EMAIL_HOST_USER``
- ``EMAIL_HOST_PASSWORD``
- ``EMAIL_SUBJECT_PREFIX``
- ``LOGIN_URL``


``base.html`` versus ``site_base.html``
---------------------------------------

In the sample projects, ``templates/base.html`` is intended for overall page structure
whereas ``templates/site_base.html`` is intended for adding site-specific content that
is to be found on all pages (things like logo, navigation or footers).

If you are writing a theme to be used across multiple sites, you should modify
``base.html``, not ``site_base.html``. If you want to keep a particular theme
but modify content for a specific site, you should modify ``site_base.html``.

Changing Avatar/Gravatar defaults
-----------------------------------

By default Pinax assigns to users the Gravatar_ icon and uses the Gravatar icon
system. If you want your own personal site avatar default, simply go to the
``settings.py`` in your project root and add these two lines of code::

    # avatar controls
    AVATAR_DEFAULT_URL =  MEDIA_URL + '<our_custom_avatar.jpg>'
    AVATAR_GRAVATAR_BACKUP = False


Adding Tabs
-----------

See :ref:`ref-tabs`

.. _`Gravatar`: http://gravatar.com/