Fixed #15252 -- Added static template tag and CachedStaticFilesStorage to staticfiles contrib app.

Many thanks to Florian Apolloner and Jacob Kaplan-Moss for reviewing and eagle eyeing.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16594 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 197 insertions, 30 deletions

diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt
index 16f8ac4c11..465b5baeae 100644
--- a/docs/howto/static-files.txt
+++ b/docs/howto/static-files.txt
@@ -70,7 +70,7 @@ Basic usage
 
        <img src="{{ STATIC_URL }}images/hi.jpg" />
 
-   See :ref:`staticfiles-in-templates` for more details, including an
+   See :ref:`staticfiles-in-templates` for more details, **including** an
    alternate method using a template tag.
 
 Deploying static files in a nutshell
@@ -143,7 +143,7 @@ A far better way is to use the value of the :setting:`STATIC_URL` setting
 directly in your templates. This means that a switch of static files servers
 only requires changing that single value. Much better!
 
-``staticfiles`` includes two built-in ways of getting at this setting in your
+Django includes multiple built-in ways of using this setting in your
 templates: a context processor and a template tag.
 
 With a context processor
@@ -180,14 +180,19 @@ but in views written by hand you'll need to explicitly use ``RequestContext``
 To see how that works, and to read more details, check out
 :ref:`subclassing-context-requestcontext`.
 
+Another option is the :ttag:`get_static_prefix` template tag that is part of
+Django's core.
+
 With a template tag
 -------------------
 
-To easily link to static files Django ships with a :ttag:`static` template tag.
+The more powerful tool is the :ttag:`static<staticfiles-static>` template
+tag. It builds the URL for the given relative path by using the configured
+:setting:`STATICFILES_STORAGE` storage.
 
 .. code-block:: html+django
 
-    {% load static %}
+    {% load staticfiles %}
     <img src="{% static "images/hi.jpg" %}" />
 
 It is also able to consume standard context variables, e.g. assuming a
@@ -195,30 +200,21 @@ It is also able to consume standard context variables, e.g. assuming a
 
 .. code-block:: html+django
 
-    {% load static %}
+    {% load staticfiles %}
     <link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />
 
-Another option is the :ttag:`get_static_prefix` template tag. You can use
-this if you're not using :class:`~django.template.RequestContext` (and
-therefore not relying on the ``django.core.context_processors.static``
-context processor), or if you need more control over exactly where and how
-:setting:`STATIC_URL` is injected into the template. Here's an example:
-
-.. code-block:: html+django
-
-    {% load static %}
-    <img src="{% get_static_prefix %}images/hi.jpg" />
-
-There's also a second form you can use to avoid extra processing if you need
-the value multiple times:
-
-.. code-block:: html+django
+.. note::
 
-    {% load static %}
-    {% get_static_prefix as STATIC_PREFIX %}
+    There is also a template tag named :ttag:`static` in Django's core set
+    of :ref:`built in template tags<ref-templates-builtins-tags>` which has
+    the same argument signature but only uses `urlparse.urljoin()`_ with the
+    :setting:`STATIC_URL` setting and the given path. This has the
+    disadvantage of not being able to easily switch the storage backend
+    without changing the templates, so in doubt use the ``staticfiles``
+    :ttag:`static<staticfiles-static>`
+    template tag.
 
-    <img src="{{ STATIC_PREFIX }}images/hi.jpg" />
-    <img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
+.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin
 
 .. _staticfiles-development:
 
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index 5ab3c1e02f..ae9521051e 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -68,7 +68,9 @@ in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
 
 This would allow you to refer to the local file
 ``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
-``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.::
+``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:
+
+.. code-block:: html+django
 
     <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
 
@@ -82,6 +84,11 @@ Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
 The file storage engine to use when collecting static files with the
 :djadmin:`collectstatic` management command.
 
+.. versionadded:: 1.4
+
+A ready-to-use instance of the storage backend defined in this setting
+can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``.
+
 For an example, see :ref:`staticfiles-from-cdn`.
 
 .. setting:: STATICFILES_FINDERS
@@ -141,6 +148,16 @@ Files are searched by using the :setting:`enabled finders
 :setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps
 specified by the :setting:`INSTALLED_APPS` setting.
 
+.. versionadded:: 1.4
+
+The :djadmin:`collectstatic` management command calls the
+:meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process`
+method of the :setting:`STATICFILES_STORAGE` after each run and passes
+a list of paths that have been found by the management command. It also
+receives all command line options of :djadmin:`collectstatic`. This is used
+by the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
+by default.
+
 Some commonly used options are:
 
 .. django-admin-option:: --noinput
@@ -169,6 +186,13 @@ Some commonly used options are:
 
     Create a symbolic link to each file instead of copying.
 
+.. django-admin-option:: --no-post-process
+.. versionadded:: 1.4
+
+    Don't call the
+    :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process`
+    method of the configured :setting:`STATICFILES_STORAGE` storage backend.
+
 .. django-admin-option:: --no-default-ignore
 
     Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'``
@@ -237,7 +261,120 @@ Example usage::
 
     django-admin.py runserver --insecure
 
-.. currentmodule:: None
+Storages
+========
+
+StaticFilesStorage
+------------------
+
+.. class:: storage.StaticFilesStorage
+
+    A subclass of the :class:`~django.core.files.storage.FileSystemStorage`
+    storage backend that uses the :setting:`STATIC_ROOT` setting as the base
+    file system location and the :setting:`STATIC_URL` setting respectively
+    as the base URL.
+
+    .. method:: post_process(paths, **options)
+
+    .. versionadded:: 1.4
+
+    This method is called by the :djadmin:`collectstatic` management command
+    after each run and gets passed the paths of found files, as well as the
+    command line options.
+
+    The :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
+    uses this behind the scenes to replace the paths with their hashed
+    counterparts and update the cache appropriately.
+
+CachedStaticFilesStorage
+------------------------
+
+.. class:: storage.CachedStaticFilesStorage
+
+    .. versionadded:: 1.4
+
+    A subclass of the :class:`~django.contrib.staticfiles.storage.StaticFilesStorage`
+    storage backend which caches the files it saves by appending the MD5 hash
+    of the file's content to the filename. For example, the file
+    ``css/styles.css`` would also be saved as ``css/styles.55e7cbb9ba48.css``.
+
+    The purpose of this storage is to keep serving the old files in case some
+    pages still refer to those files, e.g. because they are cached by you or
+    a 3rd party proxy server. Additionally, it's very helpful if you want to
+    apply `far future Expires headers`_ to the deployed files to speed up the
+    load time for subsequent page visits.
+
+    The storage backend automatically replaces the paths found in the saved
+    files matching other saved files with the path of the cached copy (using
+    the :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process`
+    method). The regular expressions used to find those paths
+    (``django.contrib.staticfiles.storage.CachedStaticFilesStorage.cached_patterns``)
+    by default cover the `@import`_ rule and `url()`_ statement of `Cascading
+    Style Sheets`_. For example, the ``'css/styles.css'`` file with the
+    content
+
+    .. code-block:: css+django
+
+        @import url("../admin/css/base.css");
+
+    would be replaced by calling the
+    :meth:`~django.core.files.storage.Storage.url`
+    method of the ``CachedStaticFilesStorage`` storage backend, ultimatively
+    saving a ``'css/styles.55e7cbb9ba48.css'`` file with the following
+    content:
+
+    .. code-block:: css+django
+
+        @import url("/static/admin/css/base.27e20196a850.css");
+
+    To enable the ``CachedStaticFilesStorage`` you have to make sure the
+    following requirements are met:
+
+    * the :setting:`STATICFILES_STORAGE` setting is set to
+      ``'django.contrib.staticfiles.storage.CachedStaticFilesStorage'``
+    * the :setting:`DEBUG` setting is set to ``False``
+    * you use the ``staticfiles`` :ttag:`static<staticfiles-static>` template
+      tag to refer to your static files in your templates
+    * you've collected all your static files by using the
+      :djadmin:`collectstatic` management command
+
+    Since creating the MD5 hash can be a performance burden to your website
+    during runtime, ``staticfiles`` will automatically try to cache the
+    hashed name for each file path using Django's :doc:`caching
+    framework</topics/cache>`. If you want to override certain options of the
+    cache backend the storage uses, simply specify a custom entry in the
+    :setting:`CACHES` setting named ``'staticfiles'``. It falls back to using
+    the ``'default'`` cache backend.
+
+.. _`far future Expires headers`: http://developer.yahoo.com/performance/rules.html#expires
+.. _`@import`: http://www.w3.org/TR/CSS2/cascade.html#at-import
+.. _`url()`: http://www.w3.org/TR/CSS2/syndata.html#uri
+.. _`Cascading Style Sheets`: http://www.w3.org/Style/CSS/
+
+.. currentmodule:: django.contrib.staticfiles.templatetags.staticfiles
+
+Template tags
+=============
+
+static
+------
+
+.. templatetag:: staticfiles-static
+
+.. versionadded:: 1.4
+
+Uses the configued :setting:`STATICFILES_STORAGE` storage to create the
+full URL for the given relative path, e.g.:
+
+.. code-block:: html+django
+
+    {% load static from staticfiles %}
+    <img src="{% static "css/base.css" %}" />
+
+The previous example is equal to calling the ``url`` method of an instance of
+:setting:`STATICFILES_STORAGE` with ``"css/base.css"``. This is especially
+useful when using a non-local storage backend to deploy files as documented
+in :ref:`staticfiles-from-cdn`.
 
 Other Helpers
 =============
@@ -251,7 +388,7 @@ files:
       with :class:`~django.template.RequestContext` contexts.
 
     - The builtin template tag :ttag:`static` which takes a path and
-      joins it with the the static prefix :setting:`STATIC_URL`.
+      urljoins it with the static prefix :setting:`STATIC_URL`.
 
     - The builtin template tag :ttag:`get_static_prefix` which populates a
       template variable with the static prefix :setting:`STATIC_URL` to be
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 5c08c66c21..a7d548a01c 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -2353,9 +2353,9 @@ static
 
 .. highlight:: html+django
 
-To link to static files Django ships with a :ttag:`static` template tag. You
-can use this regardless if you're using :class:`~django.template.RequestContext`
-or not.
+To link to static files that are saved in :setting:`STATIC_ROOT` Django ships
+with a :ttag:`static` template tag. You can use this regardless if you're
+using :class:`~django.template.RequestContext` or not.
 
 .. code-block:: html+django
 
@@ -2370,6 +2370,17 @@ It is also able to consume standard context variables, e.g. assuming a
     {% load static %}
     <link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />
 
+.. note::
+
+    The :mod:`staticfiles<django.contrib.staticfiles>` contrib app also ships
+    with a :ttag:`static template tag<staticfiles-static>` which uses
+    ``staticfiles'`` :setting:`STATICFILES_STORAGE` to build the URL of the
+    given path. Use that instead if you have an advanced use case such as
+    :ref:`using a cloud service to serve static files<staticfiles-from-cdn>`::
+
+        {% load static from staticfiles %}
+        <img src="{% static "images/hi.jpg" %}" />
+
 .. templatetag:: get_static_prefix
 
 get_static_prefix
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index ec4eae09af..02c4e82693 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -212,6 +212,29 @@ Additionally, it's now possible to define translatable URL patterns using
 :ref:`url-internationalization` for more information about the language prefix
 and how to internationalize URL patterns.
 
+``static`` template tag
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has now a new
+:ttag:`static template tag<staticfiles-static>` to refer to files saved with
+the :setting:`STATICFILES_STORAGE` storage backend. It'll use the storage
+``url`` method and therefore supports advanced features such as
+:ref:`serving files from a cloud service<staticfiles-from-cdn>`.
+
+``CachedStaticFilesStorage`` storage backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Additional to the `static template tag`_ the
+:mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a
+:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` which
+caches the files it saves (when running the :djadmin:`collectstatic`
+management command) by appending the MD5 hash of the file's content to the
+filename. For example, the file ``css/styles.css`` would also be saved as
+``css/styles.55e7cbb9ba48.css``
+
+See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
+docs for more information.
+
 Minor features
 ~~~~~~~~~~~~~~