/docs/ref/contrib/staticfiles.txt
Plain Text | 319 lines | 211 code | 108 blank | 0 comment | 0 complexity | 02000fd32e917ca19684f680771ba4c6 MD5 | raw file
Possible License(s): BSD-3-Clause
1=================== 2The staticfiles app 3=================== 4 5.. module:: django.contrib.staticfiles 6 :synopsis: An app for handling static files. 7 8.. versionadded:: 1.3 9 10``django.contrib.staticfiles`` collects static files from each of your 11applications (and any other places you specify) into a single location that 12can easily be served in production. 13 14.. seealso:: 15 16 For an introduction to the static files app and some usage examples, see 17 :doc:`/howto/static-files`. 18 19.. _staticfiles-settings: 20 21Settings 22======== 23 24.. highlight:: python 25 26.. note:: 27 28 The following settings control the behavior of the staticfiles app. 29 30.. setting:: STATICFILES_DIRS 31 32STATICFILES_DIRS 33---------------- 34 35Default: ``[]`` 36 37This setting defines the additional locations the staticfiles app will traverse 38if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the 39:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the 40static file serving view. 41 42This should be set to a list or tuple of strings that contain full paths to 43your additional files directory(ies) e.g.:: 44 45 STATICFILES_DIRS = ( 46 "/home/special.polls.com/polls/static", 47 "/home/polls.com/polls/static", 48 "/opt/webfiles/common", 49 ) 50 51Prefixes (optional) 52""""""""""""""""""" 53 54In case you want to refer to files in one of the locations with an additional 55namespace, you can **optionally** provide a prefix as ``(prefix, path)`` 56tuples, e.g.:: 57 58 STATICFILES_DIRS = ( 59 # ... 60 ("downloads", "/opt/webfiles/stats"), 61 ) 62 63Example: 64 65Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the 66:djadmin:`collectstatic` management command would collect the "stats" files 67in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`. 68 69This would allow you to refer to the local file 70``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with 71``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:: 72 73 <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz"> 74 75.. setting:: STATICFILES_STORAGE 76 77STATICFILES_STORAGE 78------------------- 79 80Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'`` 81 82The file storage engine to use when collecting static files with the 83:djadmin:`collectstatic` management command. 84 85For an example, see :ref:`staticfiles-from-cdn`. 86 87.. setting:: STATICFILES_FINDERS 88 89STATICFILES_FINDERS 90------------------- 91 92Default:: 93 94 ("django.contrib.staticfiles.finders.FileSystemFinder", 95 "django.contrib.staticfiles.finders.AppDirectoriesFinder") 96 97The list of finder backends that know how to find static files in 98various locations. 99 100The default will find files stored in the :setting:`STATICFILES_DIRS` setting 101(using :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a 102``static`` subdirectory of each app (using 103:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`) 104 105One finder is disabled by default: 106:class:`django.contrib.staticfiles.finders.DefaultStorageFinder`. If added to 107your :setting:`STATICFILES_FINDERS` setting, it will look for static files in 108the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` 109setting. 110 111.. note:: 112 113 When using the :class:`AppDirectoriesFinder` finder, make sure your apps 114 can be found by staticfiles. Simply add the app to the 115 :setting:`INSTALLED_APPS` setting of your site. 116 117Static file finders are currently considered a private interface, and this 118interface is thus undocumented. 119 120Management Commands 121=================== 122 123.. highlight:: console 124 125``django.contrib.staticfiles`` exposes three management commands. 126 127collectstatic 128------------- 129 130.. django-admin:: collectstatic 131 132Collects the static files into :setting:`STATIC_ROOT`. 133 134Duplicate file names are by default resolved in a similar way to how template 135resolution works: the file that is first found in one of the specified 136locations will be used. If you're confused, the :djadmin:`findstatic` command 137can help show you which files are found. 138 139Files are searched by using the :setting:`enabled finders 140<STATICFILES_FINDERS>`. The default is to look in all locations defined in 141:setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps 142specified by the :setting:`INSTALLED_APPS` setting. 143 144Some commonly used options are: 145 146``--noinput`` 147 Do NOT prompt the user for input of any kind. 148 149``-i PATTERN`` or ``--ignore=PATTERN`` 150 Ignore files or directories matching this glob-style pattern. Use multiple 151 times to ignore more. 152 153``-n`` or ``--dry-run`` 154 Do everything except modify the filesystem. 155 156``-l`` or ``--link`` 157 Create a symbolic link to each file instead of copying. 158 159``--no-default-ignore`` 160 Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'`` 161 and ``'*~'``. 162 163For a full list of options, refer to the commands own help by running:: 164 165 $ python manage.py collectstatic --help 166 167findstatic 168---------- 169 170.. django-admin:: findstatic 171 172Searches for one or more relative paths with the enabled finders. 173 174For example:: 175 176 $ python manage.py findstatic css/base.css admin/js/core.js 177 /home/special.polls.com/core/static/css/base.css 178 /home/polls.com/core/static/css/base.css 179 /home/polls.com/src/django/contrib/admin/media/js/core.js 180 181By default, all matching locations are found. To only return the first match 182for each relative path, use the ``--first`` option:: 183 184 $ python manage.py findstatic css/base.css --first 185 /home/special.polls.com/core/static/css/base.css 186 187This is a debugging aid; it'll show you exactly which static file will be 188collected for a given path. 189 190.. _staticfiles-runserver: 191 192runserver 193--------- 194 195.. django-admin:: runserver 196 197Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app 198is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static 199files and the following new options. 200 201.. django-admin-option:: --nostatic 202 203Use the ``--nostatic`` option to disable serving of static files with the 204:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is 205only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is 206in your project's :setting:`INSTALLED_APPS` setting. 207 208Example usage:: 209 210 django-admin.py runserver --nostatic 211 212.. django-admin-option:: --insecure 213 214Use the ``--insecure`` option to force serving of static files with the 215:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG` 216setting is ``False``. By using this you acknowledge the fact that it's 217**grossly inefficient** and probably **insecure**. This is only intended for 218local development, should **never be used in production** and is only 219available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is 220in your project's :setting:`INSTALLED_APPS` setting. 221 222Example usage:: 223 224 django-admin.py runserver --insecure 225 226.. currentmodule:: None 227 228Other Helpers 229============= 230 231The ``static`` context processor 232-------------------------------- 233 234.. function:: django.core.context_processors.static 235 236This context processor adds the :setting:`STATIC_URL` into each template 237context as the variable ``{{ STATIC_URL }}``. To use it, make sure that 238``'django.core.context_processors.static'`` appears somewhere in your 239:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. 240 241Remember, only templates rendered with :class:`~django.template.RequestContext` 242will have acces to the data provided by this (and any) context processor. 243 244.. templatetag:: get_static_prefix 245 246The ``get_static_prefix`` templatetag 247===================================== 248 249.. highlight:: html+django 250 251If you're not using :class:`~django.template.RequestContext`, or if you need 252more control over exactly where and how :setting:`STATIC_URL` is injected 253into the template, you can use the :ttag:`get_static_prefix` template tag 254instead:: 255 256 {% load static %} 257 <img src="{% get_static_prefix %}images/hi.jpg" /> 258 259There's also a second form you can use to avoid extra processing if you need 260the value multiple times:: 261 262 {% load static %} 263 {% get_static_prefix as STATIC_PREFIX %} 264 265 <img src="{{ STATIC_PREFIX }}images/hi.jpg" /> 266 <img src="{{ STATIC_PREFIX }}images/hi2.jpg" /> 267 268.. _staticfiles-development-view: 269 270Static file development view 271---------------------------- 272 273.. highlight:: python 274 275.. function:: django.contrib.staticfiles.views.serve(request, path) 276 277This view function serves static files in development. 278 279.. warning:: 280 281 This view will only work if :setting:`DEBUG` is ``True``. 282 283 That's because this view is **grossly inefficient** and probably 284 **insecure**. This is only intended for local development, and should 285 **never be used in production**. 286 287This view is automatically enabled by :djadmin:`runserver` (with a 288:setting:`DEBUG` setting set to ``True``). To use the view with a different 289local development server, add the following snippet to the end of your 290primary URL configuration:: 291 292 from django.conf import settings 293 294 if settings.DEBUG: 295 urlpatterns += patterns('django.contrib.staticfiles.views', 296 url(r'^static/(?P<path>.*)$', 'serve'), 297 ) 298 299Note, the beginning of the pattern (``r'^static/'``) should be your 300:setting:`STATIC_URL` setting. 301 302Since this is a bit finicky, there's also a helper function that'll do this for you: 303 304.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns() 305 306This will return the proper URL pattern for serving static files to your 307already defined pattern list. Use it like this:: 308 309 from django.contrib.staticfiles.urls import staticfiles_urlpatterns 310 311 # ... the rest of your URLconf here ... 312 313 urlpatterns += staticfiles_urlpatterns() 314 315.. warning:: 316 317 This helper function will only work if :setting:`DEBUG` is ``True`` 318 and your :setting:`STATIC_URL` setting is neither empty nor a full 319 URL such as ``http://static.example.com/``.