.. _ref-media:

==============
Media Handling
==============

This document explains how Pinax handles media files across external and
internal applications and themes.

Pinax places static media (css, js, and images such as backgrounds, icons and
logos) in a separate directory from the normal Django media directory (uploads
and other user generated content stored on the file server). This is done in
order to allow for easy server optimization and improved security.

Basic media handling
====================

If you want to override default media files, place yours under
`<project_name>/media/...` with the same path. For example:

Original file::

    src/pinax/media/default/pinax/img/logo.png

Your file::

    <project_name>/media/pinax/img/logo.png
    
    
Locations of media files
========================

If you want to use Pinax' media handling with your own Django apps, please
make sure you put the media files like JavaScript, cascading stylesheets (CSS)
and images in the following directory structure::

    <app_name>/media/<app_name>/(js|img|css)
    
Doubling your `<app_name>` is required to prevent name collision of media files
while deploying.

Site specific media files goes to::

    <project_name>/media/siteExample.js
    
The special static file service view should be able to serve the media files in
development.

.. _ref-media-build_static:

build_static management command
===============================

The build_static script collects the media files from Pinax and all the
installed apps and arranges them under the
``<project_name>/site_media/static`` folder.

The command::

    <project_name>/python manage.py build_static

will collect the media files from Pinax and all the apps and places them in
the folder defined in the ``STATIC_ROOT`` setting.

Please also refer to the help of the build_static management command by running::

    <project_name>/python manage.py build_static --help

.. _ref-media-resolve_static:

resolve_static management command
=================================

To quickly resolve the absolute path of a media file on the filesystem,
you can pass its expected path(s) to the ``resolve_static`` management
command, e.g.::

    $ ./manage resolve_media pinax/css/base.css
    /Users/Jannis/.virtualenvs/mysite/lib/python2.6/site-packages/Pinax-0.9alpha1-py2.6.egg/pinax/media/default/pinax/css/base.css

If multiple locations are found which match the given path it will list all of
them, sorted by its importance.

.. _ref-media-devel:

Serving static files during development
=========================================

The ``staticfiles`` app provides the static file serving view to
handle the app and theme media as well as other media files found in the
``MEDIA_ROOT`` directory. Make sure your projects' urls.py contains the
following snippet below the rest of the url configuration::

    from django.conf import settings
    if settings.SERVE_MEDIA:
        urlpatterns += patterns("",
            (r"", include("staticfiles.urls")),
        )