~~~~~~~~~~~~~~~~~~~
Staticfiles support
~~~~~~~~~~~~~~~~~~~

.. note:: 

    As a general rule, everything on this page only applies if 
    ``django.contrib.staticfiles`` is found in your  ``INSTALLED_APPS``
    setting.


As a refresher, this is how Django's ``staticfiles`` application works:

    * You spread your assets across multiple directories; often, for 
      example, you'd have a separate static folder for each application.

    * For development, a special view is provided that will search all
      these static directories, and serve the the requested file from 
      wherever it is found.

    * For production, a ``collectstatic`` management command is
      provided that will copy the files from all these locations
      into a single folder, and then this directory can be served by
      the webserver.
      
      All the individual static directories are thus part of the same
      url space. A ``foo.png`` in one folder will overwrite a ``foo.png``
      in another.


*django-assets* integrates into this in the following way:

    * When Django is in debug mode (``DEBUG=True``), webassets uses the
      staticfiles mechanism to find the files you reference in bundles, 
      in the same way the ``staticfiles`` serve view does. You can work
      with all of your assets the way you'd expect.

      This even works with globs, so "\*.js" will query Javascript files
      from across all of your applicatnion's static directories.

    * In production, this mechanism is disabled, and you are expected to
      run ``./manage.py collectstatic`` before you deploy your application
      and/or want to use ``./manage.py assets build``.
      
      .. warning:: 
      
          If you are using automatic rebuilding in production, changes
          will not be picked up until you have run ``collectstatic``.



Specific steps to make ``django-assets`` work with staticfiles
--------------------------------------------------------------

0. Make sure ``django.contrib.staticfiles`` is listed in ``INSTALLED_APPS``.

1. Add ``django_assets.finders.AssetsFinder`` to your ``STATICFILES_FINDERS``.
   It might then look like this::

       STATICFILES_FINDERS = (
          "django.contrib.staticfiles.finders.FileSystemFinder",
          "django.contrib.staticfiles.finders.AppDirectoriesFinder",
          "django_assets.finders.AssetsFinder"
       )

   This is necessary so that output files written to ``STATIC_ROOT`` are
   served in debug mode by the ``staticfiles`` *serve view*, which is not
   the case by default. If you are not building anything in debug mode 
   (e.g. CoffeeScript, Sass), you can get away without this addition, but
   it doesn't hurt to have it anway.
   
2. Make sure you run ``./manage.py collectstatic`` in production first, 
   before letting webassets build.


``CachedStaticFileStorage``
---------------------------

The new ``CachedStaticFileStorage`` in Django 1.4 is able to rename all
files to include their content hash in the filename, and rewrite references
to them within other static files.. This is somewhat overlapping with
webassets' own :ref:`versioning system <webassets:expiry>`.

If you prefer to use ``CachedStaticFileStorage``, you shouldn't run into
any problems. Just make sure you run ``./manage.py assets build`` first,
and ``./manage.py collectstatic`` second, so that ``collectstatic`` may
version the output files generated by your ``django-assets`` bundles.

The only case where this doesn't *just work* is if you are defining 
bundles in your templates. If that is the case, you currently need to 
define an ``ASSETS_ROOT`` setting that points to a different directory
then ``STATIC_ROOT``. Only then will ``collectstatic`` be able to find the
output files created with ``./manage.py build --parse-templates``, and
process them into ``STATIC_ROOT``, like any other static file.

``ManifestStaticFileStorage`` or White Noise
--------------------------------------------

If you are using Django's ``ManifestStaticFilesStorage`` or White Noise's
``GzipManifestStaticFilesStorage`` then you must build your assets after
calling ``collectstatic`` using the ``--manifest django`` option::

    ./manage.py assets build --manifest django
    
This will add the built assets to Django's static files manifest. In particular,
this ensures that White Noise realises they are cacheable static files and
will add appropriate far-future expiry headers when serving them.
