#19897: Improve static files documentation
--------------------------------------+------------------------------------
Reporter: wimfeijen | Owner: timo
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: staticfiles | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by timo):
* stage: Ready for checkin => Accepted
Comment:
Forgive me if I've missed IRC conversations that discuss the following. I
appreciate the clarity this change adds by removing some redundant
information, however, it seems to remove some potentially useful
information as well.
1. The instructions for upgrading from django-staticfiles were removed.
I'm assuming this is fine since we still have those instructions in older
versions of the docs and they aren't useful in the long run as we have
less people upgrading as time goes on.
2. The discussion of `STATIC_URL` and `TEMPLATE_CONTEXT_PROCESSORS` was
removed. I understand if we don't want to promote this method.
{{{
The included context processor is the easy way. Simply make sure
``'django.core.context_processors.static'`` is in your
:setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if
you're
editing that setting by hand it should look something like::
TEMPLATE_CONTEXT_PROCESSORS = (
'django.core.context_processors.debug',
'django.core.context_processors.i18n',
'django.core.context_processors.media',
'django.core.context_processors.static',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
)
Once that's done, you can refer to :setting:`STATIC_URL` in your
templates:
.. code-block:: html+django
<img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" />
If ``{{ STATIC_URL }}`` isn't working in your template, you're probably
not
using :class:`~django.template.RequestContext` when rendering the
template.
As a brief refresher, context processors add variables into the contexts
of
every template. However, context processors require that you use
:class:`~django.template.RequestContext` when rendering templates. This
happens
automatically if you're using a :doc:`generic view </ref/class-based-
views/index>`,
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.
}}}
... as well as a note describing the differences between
`MEDIA_ROOT`/`MEDIA_URL` and `STATIC_ROOT`/`STATIC_URL`. While it
references "previous versions of Django", it still seems useful to me in
describing the differences even for those who are coming to Django for the
first time.
{{{
.. note::
In previous versions of Django, it was common to place static assets in
:setting:`MEDIA_ROOT` along with user-uploaded files, and serve them
both
at :setting:`MEDIA_URL`. Part of the purpose of introducing the
``staticfiles`` app is to make it easier to keep static files separate
from user-uploaded files.
For this reason, you need to make your :setting:`MEDIA_ROOT` and
:setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and
:setting:`STATIC_URL`. You will need to arrange for serving of files in
:setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with
user-uploaded files at all. You can, however, use
:func:`django.views.static.serve` view for serving
:setting:`MEDIA_ROOT`
in development; see :ref:`staticfiles-other-directories`.
}}}
4. The documentation for `django.views.static.serve` and
`django.conf.urls.static.static` was removed. I don't think we should
remove them since our policy is that anything that's documented is "stable
API."
{{{
.. _staticfiles-other-directories:
Serving other directories
--------------------------
.. currentmodule:: django.views.static
.. function:: serve(request, path, document_root, show_indexes=False)
There may be files other than your project's static assets that, for
convenience, you'd like to have Django serve for you in local development.
The :func:`~django.views.static.serve` view can be used to serve any
directory
you give it. (Again, this view is **not** hardened for production
use, and should be used only as a development aid; you should serve these
files
in production using a real front-end webserver).
The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
``staticfiles`` is intended for static assets and has no built-in handling
for user-uploaded files, but you can have Django serve your
:setting:`MEDIA_ROOT` by appending something like this to your URLconf::
from django.conf import settings
# ... the rest of your URLconf goes here ...
if settings.DEBUG:
urlpatterns += patterns('',
url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
'document_root': settings.MEDIA_ROOT,
}),
)
Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
``'/media/'``. This will call the :func:`~django.views.static.serve` view,
passing in the path from the URLconf and the (required) ``document_root``
parameter.
.. currentmodule:: django.conf.urls.static
.. function:: static(prefix, view='django.views.static.serve', **kwargs)
Since it can become a bit cumbersome to define this URL pattern, Django
ships with a small URL helper function
:func:`~django.conf.urls.static.static` that takes as parameters the
prefix
such as :setting:`MEDIA_URL` and a dotted path to a view, such as
``'django.views.static.serve'``. Any other function parameter will be
transparently passed to the view.
}}}
5. Instead of `howto/static-files` and `howto/static-files-in-production`,
I've added a directory: `howto/static-files/index` and `howto/static-
files/deployment`.
Updated pull request: https://github.com/django/django/pull/889
rendered documents:
http://techytim.com/django/19897/howto/static-files/index.html
http://techytim.com/django/19897/howto/static-files/deployment.html
--
Ticket URL: <https://code.djangoproject.com/ticket/19897#comment:9>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to django-updates+unsubscr...@googlegroups.com.
To post to this group, send email to django-updates@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
