mirror of
https://github.com/django/django.git
synced 2024-12-24 18:16:19 +00:00
38a2444277
This also removes the need for ADMIN_MEDIA_PREFIX and replaces it with the convention to find admin's static files at STATIC_URL + 'admin/'. Thanks to Jacob for the review and general help. git-svn-id: http://code.djangoproject.com/svn/django/trunk@16487 bcc190cf-cafb-0310-a4f2-bffc1f526a37
301 lines
9.1 KiB
Plaintext
301 lines
9.1 KiB
Plaintext
===================
|
|
The staticfiles app
|
|
===================
|
|
|
|
.. module:: django.contrib.staticfiles
|
|
:synopsis: An app for handling static files.
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
``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::
|
|
|
|
For an introduction to the static files app and some usage examples, see
|
|
:doc:`/howto/static-files`.
|
|
|
|
.. _staticfiles-settings:
|
|
|
|
Settings
|
|
========
|
|
|
|
.. highlight:: python
|
|
|
|
.. note::
|
|
|
|
The following settings control the behavior of the staticfiles app.
|
|
|
|
.. setting:: STATICFILES_DIRS
|
|
|
|
STATICFILES_DIRS
|
|
----------------
|
|
|
|
Default: ``[]``
|
|
|
|
This setting defines the additional locations the staticfiles app will traverse
|
|
if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the
|
|
:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
|
|
static file serving view.
|
|
|
|
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/static",
|
|
"/home/polls.com/polls/static",
|
|
"/opt/webfiles/common",
|
|
)
|
|
|
|
Prefixes (optional)
|
|
"""""""""""""""""""
|
|
|
|
In case you want to refer to files in one of the locations with an additional
|
|
namespace, you can **optionally** provide a prefix as ``(prefix, path)``
|
|
tuples, e.g.::
|
|
|
|
STATICFILES_DIRS = (
|
|
# ...
|
|
("downloads", "/opt/webfiles/stats"),
|
|
)
|
|
|
|
Example:
|
|
|
|
Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
|
|
:djadmin:`collectstatic` management command would collect the "stats" files
|
|
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.::
|
|
|
|
<a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
|
|
|
|
.. setting:: STATICFILES_STORAGE
|
|
|
|
STATICFILES_STORAGE
|
|
-------------------
|
|
|
|
Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
|
|
|
|
The file storage engine to use when collecting static files with the
|
|
:djadmin:`collectstatic` management command.
|
|
|
|
For an example, see :ref:`staticfiles-from-cdn`.
|
|
|
|
.. setting:: STATICFILES_FINDERS
|
|
|
|
STATICFILES_FINDERS
|
|
-------------------
|
|
|
|
Default::
|
|
|
|
("django.contrib.staticfiles.finders.FileSystemFinder",
|
|
"django.contrib.staticfiles.finders.AppDirectoriesFinder")
|
|
|
|
The list of finder backends that know how to find static files in
|
|
various locations.
|
|
|
|
The default will find files stored in the :setting:`STATICFILES_DIRS` setting
|
|
(using :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a
|
|
``static`` subdirectory of each app (using
|
|
:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`)
|
|
|
|
One finder is disabled by default:
|
|
:class:`django.contrib.staticfiles.finders.DefaultStorageFinder`. If added to
|
|
your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
|
|
the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
|
|
setting.
|
|
|
|
.. note::
|
|
|
|
When using the :class:`AppDirectoriesFinder` finder, make sure your apps
|
|
can be found by staticfiles. Simply add the app to the
|
|
:setting:`INSTALLED_APPS` setting of your site.
|
|
|
|
Static file finders are currently considered a private interface, and this
|
|
interface is thus undocumented.
|
|
|
|
Management Commands
|
|
===================
|
|
|
|
.. highlight:: console
|
|
|
|
``django.contrib.staticfiles`` exposes three management commands.
|
|
|
|
collectstatic
|
|
-------------
|
|
|
|
.. django-admin:: collectstatic
|
|
|
|
Collects the static files into :setting:`STATIC_ROOT`.
|
|
|
|
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 :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:
|
|
|
|
``--noinput``
|
|
Do NOT prompt the user for input of any kind.
|
|
|
|
``-i PATTERN`` or ``--ignore=PATTERN``
|
|
Ignore files or directories matching this glob-style pattern. Use multiple
|
|
times to ignore more.
|
|
|
|
``-n`` or ``--dry-run``
|
|
Do everything except modify the filesystem.
|
|
|
|
``-l`` or ``--link``
|
|
Create a symbolic link to each file instead of copying.
|
|
|
|
``--no-default-ignore``
|
|
Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'``
|
|
and ``'*~'``.
|
|
|
|
For a full list of options, refer to the commands own help by running::
|
|
|
|
$ python manage.py collectstatic --help
|
|
|
|
findstatic
|
|
----------
|
|
|
|
.. django-admin:: findstatic
|
|
|
|
Searches for one or more relative paths with the enabled finders.
|
|
|
|
For example::
|
|
|
|
$ python manage.py findstatic css/base.css admin/js/core.js
|
|
/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/static/css/base.css
|
|
|
|
This is a debugging aid; it'll show you exactly which static file will be
|
|
collected for a given path.
|
|
|
|
.. _staticfiles-runserver:
|
|
|
|
runserver
|
|
---------
|
|
|
|
.. django-admin:: runserver
|
|
|
|
Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
|
|
is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
|
|
files and the following new options.
|
|
|
|
.. django-admin-option:: --nostatic
|
|
|
|
Use the ``--nostatic`` option to disable serving of static files with the
|
|
:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is
|
|
only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
|
|
in your project's :setting:`INSTALLED_APPS` setting.
|
|
|
|
Example usage::
|
|
|
|
django-admin.py runserver --nostatic
|
|
|
|
.. django-admin-option:: --insecure
|
|
|
|
Use the ``--insecure`` option to force serving of static files with the
|
|
:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG`
|
|
setting is ``False``. By using this you acknowledge the fact that it's
|
|
**grossly inefficient** and probably **insecure**. This is only intended for
|
|
local development, should **never be used in production** and is only
|
|
available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
|
|
in your project's :setting:`INSTALLED_APPS` setting.
|
|
|
|
Example usage::
|
|
|
|
django-admin.py runserver --insecure
|
|
|
|
.. currentmodule:: None
|
|
|
|
Other Helpers
|
|
=============
|
|
|
|
There are a few other helpers outside of the
|
|
:mod:`staticfiles <django.contrib.staticfiles>` app to work with static
|
|
files:
|
|
|
|
- The :func:`django.core.context_processors.static` context processor
|
|
which adds :setting:`STATIC_URL` to every template context rendered
|
|
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`.
|
|
|
|
- The builtin template tag :ttag:`get_static_prefix` which populates a
|
|
template variable with the static prefix :setting:`STATIC_URL` to be
|
|
used as a variable or directly.
|
|
|
|
- The similar template tag :ttag:`get_media_prefix` which works like
|
|
:ttag:`get_static_prefix` but uses :setting:`MEDIA_URL`.
|
|
|
|
.. _staticfiles-development-view:
|
|
|
|
Static file development view
|
|
----------------------------
|
|
|
|
.. highlight:: python
|
|
|
|
.. function:: django.contrib.staticfiles.views.serve(request, path)
|
|
|
|
This view function serves static files in development.
|
|
|
|
.. warning::
|
|
|
|
This view will only work if :setting:`DEBUG` is ``True``.
|
|
|
|
That's because this view is **grossly inefficient** and probably
|
|
**insecure**. This is only intended for local development, and should
|
|
**never be used in production**.
|
|
|
|
This view is automatically enabled by :djadmin:`runserver` (with a
|
|
:setting:`DEBUG` setting set to ``True``). To use the view with a different
|
|
local development server, add the following snippet to the end of your
|
|
primary URL configuration::
|
|
|
|
from django.conf import settings
|
|
|
|
if settings.DEBUG:
|
|
urlpatterns += patterns('django.contrib.staticfiles.views',
|
|
url(r'^static/(?P<path>.*)$', 'serve'),
|
|
)
|
|
|
|
Note, the beginning of the pattern (``r'^static/'``) should be your
|
|
:setting:`STATIC_URL` setting.
|
|
|
|
Since this is a bit finicky, there's also a helper function that'll do this for you:
|
|
|
|
.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns()
|
|
|
|
This will return the proper URL pattern for serving static files to your
|
|
already defined pattern list. Use it like this::
|
|
|
|
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
|
|
|
|
# ... the rest of your URLconf here ...
|
|
|
|
urlpatterns += staticfiles_urlpatterns()
|
|
|
|
.. warning::
|
|
|
|
This helper function will only work if :setting:`DEBUG` is ``True``
|
|
and your :setting:`STATIC_URL` setting is neither empty nor a full
|
|
URL such as ``http://static.example.com/``.
|