Fixed #14528 and #14538 -- Refined staticfiles documentation. Thanks, gremmie and romaniuk.

successfully deployed into production. This usually means a separate, dedicated

media server, which is a lot of overhead to mess with when developing locally.

Thus, the ``staticfiles`` app ships with a quick and dirty helper view that you

can use to serve media locally in development.

can use to serve files locally in development.

To enable this view, you'll add a couple of lines to your URLconf. The first

line goes at the top of the file, and the last line at the bottom::

This will inspect your :setting:`STATICFILES_URL` and

:setting:`STATICFILES_ROOT` settings and wire up the view to serve static media

accordingly.

accordingly. Don't forget to set the :setting:`STATICFILES_DIRS` setting

appropriately to let ``django.contrib.staticfiles`` know where to look for

files.

.. warning::

Below, and in the following sections, we'll show off a few example fabfiles

(i.e. Fabric scripts) that automate these media deployment options. The syntax

of a fabfile is fairly streightforward but won't be covered here; consult `Fabric's documentation`__, for a complete explanation of the syntax..

of a fabfile is fairly streightforward but won't be covered here; consult

`Fabric's documentation`__, for a complete explanation of the syntax..

__ http://docs.fabfile.org/

For example, if you've written an S3 storage backend in

``myproject.storage.S3Storage`` you could use it with::

    STATICFILES_STORAGE = 'storages.backends.s3.S3Storage'

    STATICFILES_STORAGE = 'myproject.storage.S3Storage'

Once that's done, all you have to do is run :djadmin:`collectstatic` and your

media would be pushed through your storage package up to S3. If you later needed

.. seealso::

    The `django-storages`__ project is a 3rd party app that provides many

    storage backends for many common file storage APIs (including S3).

    storage backends for many common file storage APIs (including `S3`__).

__ http://s3.amazonaws.com/

__ http://code.welldev.org/django-storages/

__ http://code.welldev.org/django-storages/wiki/S3Storage

Upgrading from ``django-staticfiles``

.. versionadded:: 1.3

``django.contrib.staticfiles`` collects media from each of your applications

(and any other places you specify) into a single location that can easily be

served in production.

``django.contrib.staticfiles`` collects static files from each of your

applications (and any other places you specify) into a single location that

can easily be served in production.

.. seealso::

... or perhaps::

    STATICFILES_URL = 'http://media.exmaple.com/'

    STATICFILES_URL = 'http://static.example.com/'

This should **always** have a trailing slash.

:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the

static file serving view.

It should be defined as a sequence of ``(prefix, path)`` tuples, e.g.::

This should be set to a list or tuple of strings that contain full paths to

your additional files directory(ies) e.g.::

    STATICFILES_DIRS = (

       ('', '/home/special.polls.com/polls/media'),

       ('', '/home/polls.com/polls/media'),

       ('common', '/opt/webfiles/common'),

        "/home/special.polls.com/polls/static",

        "/home/polls.com/polls/static",

        "/opt/webfiles/common",

    )

In case you want to refer to files in one of the locations with a additional

namespace, you can **optionally** provide a prefix as ``(prefix, path)``

tuples, e.g.::

    STATICFILES_DIRS = (

        "/home/polls.com/polls/static",

        ("downloads", "/opt/webfiles/stats"),

    )

With this configuration, the :djadmin:`collectstatic` management command would

for example collect the stats files in a ``'downloads'`` directory. So

assuming you have :setting:`STATICFILES_URL` set ``'/static/'``, this would

allow you to refer to the file ``'/opt/webfiles/stats/polls_20101022.tar.gz'``

with ``'/static/downloads/polls_20101022.tar.gz'`` in your templates.

.. setting:: STATICFILES_STORAGE

STATICFILES_STORAGE

Collects the static files into :setting:`STATICFILES_ROOT`.

Duplicate file names are resolved in a similar way to how template resolution

works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from

earlier apps, and files from storage directories later in

:setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused,

the :djadmin:`findstatic` command can help show you where 

Duplicate file names are by default resolved in a similar way to how template

resolution works: the file that is first found in one of the specified

locations will be used. If you're confused, the :djadmin:`findstatic` command

can help show you which files are found.

Files are searched by using the :ref:`enabled finders

<staticfiles-finders>`. The default is to look in all locations defined in

:ref:`staticfiles-dirs` and in the ``media`` directory of apps specified by the

:setting:`INSTALLED_APPS` setting.

Files are searched by using the :setting:`enabled finders

<STATICFILES_FINDERS>`. The default is to look in all locations defined in

:setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps

specified by the :setting:`INSTALLED_APPS` setting.

Some commonly used options are:

For example::

   $ python manage.py findstatic css/base.css admin/js/core.js

   /home/special.polls.com/core/media/css/base.css

   /home/polls.com/core/media/css/base.css

   /home/special.polls.com/core/static/css/base.css

   /home/polls.com/core/static/css/base.css

   /home/polls.com/src/django/contrib/admin/media/js/core.js

By default, all matching locations are found. To only return the first match

for each relative path, use the ``--first`` option::

   $ python manage.py findstatic css/base.css --first

   /home/special.polls.com/core/media/css/base.css

   /home/special.polls.com/core/static/css/base.css

This is a debugging aid; it'll show you exactly which static file will be

collected for a given path.

Other Helpers

=============

The ``media`` context processor

-------------------------------

The ``staticfiles`` context processor

-------------------------------------

.. function:: django.contrib.staticfiles.context_processors.staticfiles

    {% load staticfiles %}

    <img src="{% get_staticfiles_prefix %}images/hi.jpg" />

There's also a second form you can use to avoid extra processing if you need the

value multiple times::

There's also a second form you can use to avoid extra processing if you need

the value multiple times::

    {% load staticfiles %}

    {% get_staticfiles_prefix as STATIC_PREFIX %}

.. function:: django.contrib.staticfiles.views.serve(request, path)

This view function serves static media in in development.

This view function serves static files in development.

.. warning::

   urlpatterns += staticfiles_urlpatterns()