From c32fc79aa120a0a129680805aef6731c1c2c7aef Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Mon, 4 Mar 2013 06:05:11 -0500 Subject: Fixed #19582 - Added a static files tutorial. Thanks James Pic. --- docs/howto/static-files.txt | 508 -------------------------------------- docs/howto/static-files/index.txt | 508 ++++++++++++++++++++++++++++++++++++++ docs/index.txt | 3 +- docs/intro/index.txt | 1 + docs/intro/reusable-apps.txt | 12 +- docs/intro/tutorial05.txt | 11 +- docs/intro/tutorial06.txt | 125 ++++++++++ 7 files changed, 649 insertions(+), 519 deletions(-) delete mode 100644 docs/howto/static-files.txt create mode 100644 docs/howto/static-files/index.txt create mode 100644 docs/intro/tutorial06.txt (limited to 'docs') diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt deleted file mode 100644 index 964b5fab61..0000000000 --- a/docs/howto/static-files.txt +++ /dev/null @@ -1,508 +0,0 @@ -===================== -Managing static files -===================== - -Django developers mostly concern themselves with the dynamic parts of web -applications -- the views and templates that render anew for each request. But -web applications have other parts: the static files (images, CSS, -Javascript, etc.) that are needed to render a complete web page. - -For small projects, this isn't a big deal, because you can just keep the -static files somewhere your web server can find it. However, in bigger -projects -- especially those comprised of multiple apps -- dealing with the -multiple sets of static files provided by each application starts to get -tricky. - -That's what ``django.contrib.staticfiles`` is for: it 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. - -.. note:: - - If you've used the `django-staticfiles`_ third-party app before, then - ``django.contrib.staticfiles`` will look very familiar. That's because - they're essentially the same code: ``django.contrib.staticfiles`` started - its life as `django-staticfiles`_ and was merged into Django 1.3. - - If you're upgrading from ``django-staticfiles``, please see `Upgrading from - django-staticfiles`_, below, for a few minor changes you'll need to make. - -.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ - -Using ``django.contrib.staticfiles`` -==================================== - -Basic usage ------------ - -1. Put your static files somewhere that ``staticfiles`` will find them. - - By default, this means within ``static/`` subdirectories of apps in your - :setting:`INSTALLED_APPS`. - - Your project will probably also have static assets that aren't tied to a - particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of - filesystem directories to check when loading static files. It's a search - path that is by default empty. See the :setting:`STATICFILES_DIRS` docs - how to extend this list of additional paths. - - Additionally, see the documentation for the :setting:`STATICFILES_FINDERS` - setting for details on how ``staticfiles`` finds your files. - -2. Make sure that ``django.contrib.staticfiles`` is included in your - :setting:`INSTALLED_APPS`. - - For :ref:`local development`, if you are using - :ref:`runserver` or adding - :ref:`staticfiles_urlpatterns` to your - URLconf, you're done with the setup -- your static files will - automatically be served at the default (for - :djadmin:`newly created` projects) :setting:`STATIC_URL` - of ``/static/``. - -3. You'll probably need to refer to these files in your templates. The - easiest method is to use the included context processor which allows - template code like: - - .. code-block:: html+django - - Hi! - - See :ref:`staticfiles-in-templates` for more details, **including** an - alternate method using a template tag. - -Deploying static files in a nutshell ------------------------------------- - -When you're ready to move out of local development and deploy your project: - -1. Set the :setting:`STATIC_URL` setting to the public URL for your static - files (in most cases, the default value of ``/static/`` is just fine). - -2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path - you'd like your static files collected to when you use the - :djadmin:`collectstatic` management command. For example:: - - STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic" - -3. Run the :djadmin:`collectstatic` management command:: - - ./manage.py collectstatic - - This'll churn through your static file storage and copy them into the - directory given by :setting:`STATIC_ROOT`. - -4. Deploy those files by configuring your webserver of choice to serve the - files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`. - - :ref:`staticfiles-production` covers some common deployment strategies - for static files. - -Those are the **basics**. For more details on common configuration options, -read on; for a detailed reference of the settings, commands, and other bits -included with the framework see -:doc:`the staticfiles reference `. - -.. 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`. - -.. _staticfiles-in-templates: - -Referring to static files in templates -====================================== - -At some point, you'll probably need to link to static files in your templates. -You could, of course, simply hardcode the path to you assets in the templates: - -.. code-block:: html - - Sample image - -Of course, there are some serious problems with this: it doesn't work well in -development, and it makes it *very* hard to change where you've deployed your -static files. If, for example, you wanted to switch to using a content -delivery network (CDN), then you'd need to change more or less every single -template. - -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! - -Django includes multiple built-in ways of using this setting in your -templates: a context processor and a template tag. - -With a context processor ------------------------- - -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 - - 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 `, -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 -------------------- - -The more powerful tool is the :ttag:`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 staticfiles %} - Hi! - -It is also able to consume standard context variables, e.g. assuming a -``user_stylesheet`` variable is passed to the template: - -.. code-block:: html+django - - {% load staticfiles %} - - -.. note:: - - There is also a template tag named :ttag:`static` in Django's core set - of :ref:`built in template 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` - template tag. - -.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin - -.. _staticfiles-development: - -Serving static files in development -=================================== - -The static files tools are mostly designed to help with getting static files -successfully deployed into production. This usually means a separate, -dedicated static file server, which is a lot of overhead to mess with when -developing locally. Thus, the ``staticfiles`` app ships with a -**quick and dirty helper view** that you can use to serve files locally in -development. - -This view is automatically enabled and will serve your static files at -:setting:`STATIC_URL` when you use the built-in -:ref:`runserver` management command. - -To enable this view if you are using some other server for local development, -you'll add a couple of lines to your URLconf. The first line goes at the top -of the file, and the last line at the bottom:: - - from django.contrib.staticfiles.urls import staticfiles_urlpatterns - - # ... the rest of your URLconf goes here ... - - urlpatterns += staticfiles_urlpatterns() - -This will inspect your :setting:`STATIC_URL` setting and wire up the view -to serve static files accordingly. Don't forget to set the -:setting:`STATICFILES_DIRS` setting appropriately to let -``django.contrib.staticfiles`` know where to look for files additionally to -files in app directories. - -.. warning:: - - This 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**. - - Additionally, when using ``staticfiles_urlpatterns`` your - :setting:`STATIC_URL` setting can't be empty or a full URL, such as - ``http://static.example.com/``. - -For a few more details on how the ``staticfiles`` can be used during -development, see :ref:`staticfiles-development-view`. - -.. _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.*)$', '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. - -An example for serving :setting:`MEDIA_URL` (``'/media/'``) during -development:: - - from django.conf import settings - from django.conf.urls.static import static - - urlpatterns = patterns('', - # ... the rest of your URLconf goes here ... - ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) - -.. note:: - - This helper function will only be operational in debug mode and if - the given prefix is local (e.g. ``/static/``) and not a URL (e.g. - ``http://static.example.com/``). - -.. _staticfiles-production: - -Serving static files in production -================================== - -The basic outline of putting static files into production is simple: run the -:djadmin:`collectstatic` command when static files change, then arrange for -the collected static files directory (:setting:`STATIC_ROOT`) to be moved to -the static file server and served. - -Of course, as with all deployment tasks, the devil's in the details. Every -production setup will be a bit different, so you'll need to adapt the basic -outline to fit your needs. Below are a few common patterns that might help. - -Serving the app and your static files from the same server ----------------------------------------------------------- - -If you want to serve your static files from the same server that's already -serving your site, the basic outline gets modified to look something like: - -* Push your code up to the deployment server. -* On the server, run :djadmin:`collectstatic` to copy all the static files - into :setting:`STATIC_ROOT`. -* Point your web server at :setting:`STATIC_ROOT`. For example, here's - :ref:`how to do this under Apache and mod_wsgi `. - -You'll probably want to automate this process, especially if you've got -multiple web servers. There's any number of ways to do this automation, but -one option that many Django developers enjoy is `Fabric`__. - -__ http://fabfile.org/ - -Below, and in the following sections, we'll show off a few example fabfiles -(i.e. Fabric scripts) that automate these file deployment options. The syntax -of a fabfile is fairly straightforward but won't be covered here; consult -`Fabric's documentation`__, for a complete explanation of the syntax.. - -__ http://docs.fabfile.org/ - -So, a fabfile to deploy static files to a couple of web servers might look -something like:: - - from fabric.api import * - - # Hosts to deploy onto - env.hosts = ['www1.example.com', 'www2.example.com'] - - # Where your project code lives on the server - env.project_root = '/home/www/myproject' - - def deploy_static(): - with cd(env.project_root): - run('./manage.py collectstatic -v0 --noinput') - -Serving static files from a dedicated server --------------------------------------------- - -Most larger Django apps use a separate Web server -- i.e., one that's not also -running Django -- for serving static files. This server often runs a different -type of web server -- faster but less full-featured. Some good choices are: - -* lighttpd_ -* Nginx_ -* TUX_ -* Cherokee_ -* A stripped-down version of Apache_ - -.. _lighttpd: http://www.lighttpd.net/ -.. _Nginx: http://wiki.nginx.org/Main -.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server -.. _Apache: http://httpd.apache.org/ -.. _Cherokee: http://www.cherokee-project.com/ - -Configuring these servers is out of scope of this document; check each -server's respective documentation for instructions. - -Since your static file server won't be running Django, you'll need to modify -the deployment strategy to look something like: - -* When your static files change, run :djadmin:`collectstatic` locally. -* Push your local :setting:`STATIC_ROOT` up to the static file server - into the directory that's being served. ``rsync`` is a good - choice for this step since it only needs to transfer the - bits of static files that have changed. - -Here's how this might look in a fabfile:: - - from fabric.api import * - from fabric.contrib import project - - # Where the static files get collected locally - env.local_static_root = '/tmp/static' - - # Where the static files should go remotely - env.remote_static_root = '/home/www/static.example.com' - - @roles('static') - def deploy_static(): - local('./manage.py collectstatic') - project.rsync_project( - remote_dir = env.remote_static_root, - local_dir = env.local_static_root, - delete = True - ) - -.. _staticfiles-from-cdn: - -Serving static files from a cloud service or CDN ------------------------------------------------- - -Another common tactic is to serve static files from a cloud storage provider -like Amazon's S3__ and/or a CDN (content delivery network). This lets you -ignore the problems of serving static files, and can often make for -faster-loading webpages (especially when using a CDN). - -When using these services, the basic workflow would look a bit like the above, -except that instead of using ``rsync`` to transfer your static files to the -server you'd need to transfer the static files to the storage provider or CDN. - -There's any number of ways you might do this, but if the provider has an API a -:doc:`custom file storage backend ` will make the -process incredibly simple. If you've written or are using a 3rd party custom -storage backend, you can tell :djadmin:`collectstatic` to use it by setting -:setting:`STATICFILES_STORAGE` to the storage engine. - -For example, if you've written an S3 storage backend in -``myproject.storage.S3Storage`` you could use it with:: - - STATICFILES_STORAGE = 'myproject.storage.S3Storage' - -Once that's done, all you have to do is run :djadmin:`collectstatic` and your -static files would be pushed through your storage package up to S3. If you -later needed to switch to a different storage provider, it could be as simple -as changing your :setting:`STATICFILES_STORAGE` setting. - -For details on how you'd write one of these backends, -:doc:`/howto/custom-file-storage`. - -.. seealso:: - - The `django-storages`__ project is a 3rd party app that provides many - storage backends for many common file storage APIs (including `S3`__). - -__ http://s3.amazonaws.com/ -__ http://code.larlet.fr/django-storages/ -__ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html - -Upgrading from ``django-staticfiles`` -===================================== - -``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If -you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to -``django.contrib.staticfiles``, you'll need to make a few changes: - -* Application files should now live in a ``static`` directory in each app - (`django-staticfiles`_ used the name ``media``, which was slightly - confusing). - -* The management commands ``build_static`` and ``resolve_static`` are now - called :djadmin:`collectstatic` and :djadmin:`findstatic`. - -* The settings ``STATICFILES_PREPEND_LABEL_APPS``, - ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were - removed. - -* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the - new :setting:`STATICFILES_FINDERS`. - -* The default for :setting:`STATICFILES_STORAGE` was renamed from - ``staticfiles.storage.StaticFileStorage`` to - ``staticfiles.storage.StaticFilesStorage`` - -* If using :ref:`runserver` for local development - (and the :setting:`DEBUG` setting is ``True``), you no longer need to add - anything to your URLconf for serving static files in development. - -Learn more -========== - -This document has covered the basics and some common usage patterns. For -complete details on all the settings, commands, template tags, and other pieces -include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference -`. diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt new file mode 100644 index 0000000000..964b5fab61 --- /dev/null +++ b/docs/howto/static-files/index.txt @@ -0,0 +1,508 @@ +===================== +Managing static files +===================== + +Django developers mostly concern themselves with the dynamic parts of web +applications -- the views and templates that render anew for each request. But +web applications have other parts: the static files (images, CSS, +Javascript, etc.) that are needed to render a complete web page. + +For small projects, this isn't a big deal, because you can just keep the +static files somewhere your web server can find it. However, in bigger +projects -- especially those comprised of multiple apps -- dealing with the +multiple sets of static files provided by each application starts to get +tricky. + +That's what ``django.contrib.staticfiles`` is for: it 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. + +.. note:: + + If you've used the `django-staticfiles`_ third-party app before, then + ``django.contrib.staticfiles`` will look very familiar. That's because + they're essentially the same code: ``django.contrib.staticfiles`` started + its life as `django-staticfiles`_ and was merged into Django 1.3. + + If you're upgrading from ``django-staticfiles``, please see `Upgrading from + django-staticfiles`_, below, for a few minor changes you'll need to make. + +.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ + +Using ``django.contrib.staticfiles`` +==================================== + +Basic usage +----------- + +1. Put your static files somewhere that ``staticfiles`` will find them. + + By default, this means within ``static/`` subdirectories of apps in your + :setting:`INSTALLED_APPS`. + + Your project will probably also have static assets that aren't tied to a + particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of + filesystem directories to check when loading static files. It's a search + path that is by default empty. See the :setting:`STATICFILES_DIRS` docs + how to extend this list of additional paths. + + Additionally, see the documentation for the :setting:`STATICFILES_FINDERS` + setting for details on how ``staticfiles`` finds your files. + +2. Make sure that ``django.contrib.staticfiles`` is included in your + :setting:`INSTALLED_APPS`. + + For :ref:`local development`, if you are using + :ref:`runserver` or adding + :ref:`staticfiles_urlpatterns` to your + URLconf, you're done with the setup -- your static files will + automatically be served at the default (for + :djadmin:`newly created` projects) :setting:`STATIC_URL` + of ``/static/``. + +3. You'll probably need to refer to these files in your templates. The + easiest method is to use the included context processor which allows + template code like: + + .. code-block:: html+django + + Hi! + + See :ref:`staticfiles-in-templates` for more details, **including** an + alternate method using a template tag. + +Deploying static files in a nutshell +------------------------------------ + +When you're ready to move out of local development and deploy your project: + +1. Set the :setting:`STATIC_URL` setting to the public URL for your static + files (in most cases, the default value of ``/static/`` is just fine). + +2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path + you'd like your static files collected to when you use the + :djadmin:`collectstatic` management command. For example:: + + STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic" + +3. Run the :djadmin:`collectstatic` management command:: + + ./manage.py collectstatic + + This'll churn through your static file storage and copy them into the + directory given by :setting:`STATIC_ROOT`. + +4. Deploy those files by configuring your webserver of choice to serve the + files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`. + + :ref:`staticfiles-production` covers some common deployment strategies + for static files. + +Those are the **basics**. For more details on common configuration options, +read on; for a detailed reference of the settings, commands, and other bits +included with the framework see +:doc:`the staticfiles reference `. + +.. 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`. + +.. _staticfiles-in-templates: + +Referring to static files in templates +====================================== + +At some point, you'll probably need to link to static files in your templates. +You could, of course, simply hardcode the path to you assets in the templates: + +.. code-block:: html + + Sample image + +Of course, there are some serious problems with this: it doesn't work well in +development, and it makes it *very* hard to change where you've deployed your +static files. If, for example, you wanted to switch to using a content +delivery network (CDN), then you'd need to change more or less every single +template. + +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! + +Django includes multiple built-in ways of using this setting in your +templates: a context processor and a template tag. + +With a context processor +------------------------ + +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 + + 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 `, +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 +------------------- + +The more powerful tool is the :ttag:`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 staticfiles %} + Hi! + +It is also able to consume standard context variables, e.g. assuming a +``user_stylesheet`` variable is passed to the template: + +.. code-block:: html+django + + {% load staticfiles %} + + +.. note:: + + There is also a template tag named :ttag:`static` in Django's core set + of :ref:`built in template 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` + template tag. + +.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin + +.. _staticfiles-development: + +Serving static files in development +=================================== + +The static files tools are mostly designed to help with getting static files +successfully deployed into production. This usually means a separate, +dedicated static file server, which is a lot of overhead to mess with when +developing locally. Thus, the ``staticfiles`` app ships with a +**quick and dirty helper view** that you can use to serve files locally in +development. + +This view is automatically enabled and will serve your static files at +:setting:`STATIC_URL` when you use the built-in +:ref:`runserver` management command. + +To enable this view if you are using some other server for local development, +you'll add a couple of lines to your URLconf. The first line goes at the top +of the file, and the last line at the bottom:: + + from django.contrib.staticfiles.urls import staticfiles_urlpatterns + + # ... the rest of your URLconf goes here ... + + urlpatterns += staticfiles_urlpatterns() + +This will inspect your :setting:`STATIC_URL` setting and wire up the view +to serve static files accordingly. Don't forget to set the +:setting:`STATICFILES_DIRS` setting appropriately to let +``django.contrib.staticfiles`` know where to look for files additionally to +files in app directories. + +.. warning:: + + This 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**. + + Additionally, when using ``staticfiles_urlpatterns`` your + :setting:`STATIC_URL` setting can't be empty or a full URL, such as + ``http://static.example.com/``. + +For a few more details on how the ``staticfiles`` can be used during +development, see :ref:`staticfiles-development-view`. + +.. _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.*)$', '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. + +An example for serving :setting:`MEDIA_URL` (``'/media/'``) during +development:: + + from django.conf import settings + from django.conf.urls.static import static + + urlpatterns = patterns('', + # ... the rest of your URLconf goes here ... + ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) + +.. note:: + + This helper function will only be operational in debug mode and if + the given prefix is local (e.g. ``/static/``) and not a URL (e.g. + ``http://static.example.com/``). + +.. _staticfiles-production: + +Serving static files in production +================================== + +The basic outline of putting static files into production is simple: run the +:djadmin:`collectstatic` command when static files change, then arrange for +the collected static files directory (:setting:`STATIC_ROOT`) to be moved to +the static file server and served. + +Of course, as with all deployment tasks, the devil's in the details. Every +production setup will be a bit different, so you'll need to adapt the basic +outline to fit your needs. Below are a few common patterns that might help. + +Serving the app and your static files from the same server +---------------------------------------------------------- + +If you want to serve your static files from the same server that's already +serving your site, the basic outline gets modified to look something like: + +* Push your code up to the deployment server. +* On the server, run :djadmin:`collectstatic` to copy all the static files + into :setting:`STATIC_ROOT`. +* Point your web server at :setting:`STATIC_ROOT`. For example, here's + :ref:`how to do this under Apache and mod_wsgi `. + +You'll probably want to automate this process, especially if you've got +multiple web servers. There's any number of ways to do this automation, but +one option that many Django developers enjoy is `Fabric`__. + +__ http://fabfile.org/ + +Below, and in the following sections, we'll show off a few example fabfiles +(i.e. Fabric scripts) that automate these file deployment options. The syntax +of a fabfile is fairly straightforward but won't be covered here; consult +`Fabric's documentation`__, for a complete explanation of the syntax.. + +__ http://docs.fabfile.org/ + +So, a fabfile to deploy static files to a couple of web servers might look +something like:: + + from fabric.api import * + + # Hosts to deploy onto + env.hosts = ['www1.example.com', 'www2.example.com'] + + # Where your project code lives on the server + env.project_root = '/home/www/myproject' + + def deploy_static(): + with cd(env.project_root): + run('./manage.py collectstatic -v0 --noinput') + +Serving static files from a dedicated server +-------------------------------------------- + +Most larger Django apps use a separate Web server -- i.e., one that's not also +running Django -- for serving static files. This server often runs a different +type of web server -- faster but less full-featured. Some good choices are: + +* lighttpd_ +* Nginx_ +* TUX_ +* Cherokee_ +* A stripped-down version of Apache_ + +.. _lighttpd: http://www.lighttpd.net/ +.. _Nginx: http://wiki.nginx.org/Main +.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server +.. _Apache: http://httpd.apache.org/ +.. _Cherokee: http://www.cherokee-project.com/ + +Configuring these servers is out of scope of this document; check each +server's respective documentation for instructions. + +Since your static file server won't be running Django, you'll need to modify +the deployment strategy to look something like: + +* When your static files change, run :djadmin:`collectstatic` locally. +* Push your local :setting:`STATIC_ROOT` up to the static file server + into the directory that's being served. ``rsync`` is a good + choice for this step since it only needs to transfer the + bits of static files that have changed. + +Here's how this might look in a fabfile:: + + from fabric.api import * + from fabric.contrib import project + + # Where the static files get collected locally + env.local_static_root = '/tmp/static' + + # Where the static files should go remotely + env.remote_static_root = '/home/www/static.example.com' + + @roles('static') + def deploy_static(): + local('./manage.py collectstatic') + project.rsync_project( + remote_dir = env.remote_static_root, + local_dir = env.local_static_root, + delete = True + ) + +.. _staticfiles-from-cdn: + +Serving static files from a cloud service or CDN +------------------------------------------------ + +Another common tactic is to serve static files from a cloud storage provider +like Amazon's S3__ and/or a CDN (content delivery network). This lets you +ignore the problems of serving static files, and can often make for +faster-loading webpages (especially when using a CDN). + +When using these services, the basic workflow would look a bit like the above, +except that instead of using ``rsync`` to transfer your static files to the +server you'd need to transfer the static files to the storage provider or CDN. + +There's any number of ways you might do this, but if the provider has an API a +:doc:`custom file storage backend ` will make the +process incredibly simple. If you've written or are using a 3rd party custom +storage backend, you can tell :djadmin:`collectstatic` to use it by setting +:setting:`STATICFILES_STORAGE` to the storage engine. + +For example, if you've written an S3 storage backend in +``myproject.storage.S3Storage`` you could use it with:: + + STATICFILES_STORAGE = 'myproject.storage.S3Storage' + +Once that's done, all you have to do is run :djadmin:`collectstatic` and your +static files would be pushed through your storage package up to S3. If you +later needed to switch to a different storage provider, it could be as simple +as changing your :setting:`STATICFILES_STORAGE` setting. + +For details on how you'd write one of these backends, +:doc:`/howto/custom-file-storage`. + +.. seealso:: + + The `django-storages`__ project is a 3rd party app that provides many + storage backends for many common file storage APIs (including `S3`__). + +__ http://s3.amazonaws.com/ +__ http://code.larlet.fr/django-storages/ +__ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html + +Upgrading from ``django-staticfiles`` +===================================== + +``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If +you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to +``django.contrib.staticfiles``, you'll need to make a few changes: + +* Application files should now live in a ``static`` directory in each app + (`django-staticfiles`_ used the name ``media``, which was slightly + confusing). + +* The management commands ``build_static`` and ``resolve_static`` are now + called :djadmin:`collectstatic` and :djadmin:`findstatic`. + +* The settings ``STATICFILES_PREPEND_LABEL_APPS``, + ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were + removed. + +* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the + new :setting:`STATICFILES_FINDERS`. + +* The default for :setting:`STATICFILES_STORAGE` was renamed from + ``staticfiles.storage.StaticFileStorage`` to + ``staticfiles.storage.StaticFilesStorage`` + +* If using :ref:`runserver` for local development + (and the :setting:`DEBUG` setting is ``True``), you no longer need to add + anything to your URLconf for serving static files in development. + +Learn more +========== + +This document has covered the basics and some common usage patterns. For +complete details on all the settings, commands, template tags, and other pieces +include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference +`. diff --git a/docs/index.txt b/docs/index.txt index 197856ea4b..8823888e7b 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -45,7 +45,8 @@ Are you new to Django or to programming? This is the place to start! :doc:`Part 2 ` | :doc:`Part 3 ` | :doc:`Part 4 ` | - :doc:`Part 5 ` + :doc:`Part 5 ` | + :doc:`Part 6 ` * **Advanced Tutorials:** :doc:`How to write reusable apps ` | diff --git a/docs/intro/index.txt b/docs/intro/index.txt index ea6a3c4d29..6c62eb547c 100644 --- a/docs/intro/index.txt +++ b/docs/intro/index.txt @@ -14,6 +14,7 @@ place: read this material to quickly get up and running. tutorial03 tutorial04 tutorial05 + tutorial06 reusable-apps whatsnext contributing diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index 0e0c9d2ba5..1e0f1da0c5 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -2,11 +2,11 @@ Advanced tutorial: How to write reusable apps ============================================= -This advanced tutorial begins where :doc:`Tutorial 5 ` left -off. We'll be turning our Web-poll into a standalone Python package you can -reuse in new projects and share with other people. +This advanced tutorial begins where :doc:`Tutorial 6 ` +left off. We'll be turning our Web-poll into a standalone Python package +you can reuse in new projects and share with other people. -If you haven't recently completed Tutorials 1–5, we encourage you to review +If you haven't recently completed Tutorials 1–6, we encourage you to review these so that your example project matches the one described below. Reusability matters @@ -67,6 +67,10 @@ After the previous tutorials, our project should look like this:: admin.py models.py tests.py + static/ + style.css + images/ + background.gif templates/ polls/ detail.html diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt index 7fb30fbb88..3b0a95f253 100644 --- a/docs/intro/tutorial05.txt +++ b/docs/intro/tutorial05.txt @@ -640,10 +640,9 @@ information about testing. What's next? ============ -The beginner tutorial ends here for the time being. In the meantime, you might -want to check out some pointers on :doc:`where to go from here -`. +For full details on testing, see :doc:`Testing in Django +`. -If you are familiar with Python packaging and interested in learning how to -turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to -write reusable apps`. +When you're comfortable with testing Django views, read +:doc:`part 6 of this tutorial` to learn about +static files management. diff --git a/docs/intro/tutorial06.txt b/docs/intro/tutorial06.txt new file mode 100644 index 0000000000..28e1cabd96 --- /dev/null +++ b/docs/intro/tutorial06.txt @@ -0,0 +1,125 @@ +===================================== +Writing your first Django app, part 6 +===================================== + +This tutorial begins where :doc:`Tutorial 5 ` left off. +We've built a tested Web-poll application, and we'll now add a stylesheet and +an image. + +Aside from the HTML generated by the server, web applications generally need +to serve additional files — such as images, JavaScript, or CSS — necessary to +render the complete web page. In Django, we refer to these files as "static +files". + +For small projects, this isn't a big deal, because you can just keep the +static files somewhere your web server can find it. However, in bigger +projects -- especially those comprised of multiple apps -- dealing with the +multiple sets of static files provided by each application starts to get +tricky. + +That's what ``django.contrib.staticfiles`` is for: it 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. + +Customize your *app's* look and feel +==================================== + +First, create a directory called ``static`` in your ``polls`` directory. Django +will look for static files there, similarly to how Django finds templates +inside ``polls/templates/``. + +Django's :setting:`STATICFILES_FINDERS` setting contains a list +of finders that know how to discover static files from various +sources. One of the defaults is ``AppDirectoriesFinder`` which +looks for a "static" subdirectory in each of the +:setting:`INSTALLED_APPS`, like the one in ``polls`` we just created. The admin +site uses the same directory structure for its static files. + +Within the ``static`` directory you have just created, create another directory +called ``polls`` and within that create a file called ``style.css``. In other +words, your stylesheet should be at ``polls/static/polls/style.css``. Because +of how the ``AppDirectoriesFinder`` staticfile finder works, you can refer to +this static file in Django simply as ``polls/style.css``, similar to how you +reference the path for templates. + +.. admonition:: Static file namespacing + + Just like templates, we *might* be able to get away with putting our static + files directly in ``polls/static`` (rather than creating another ``polls`` + subdirectory), but it would actually be a bad idea. Django will choose the + first static file it finds whose name matches, and if you had a static file + with the same name in a *different* application, Django would be unable to + distinguish between them. We need to be able to point Django at the right + one, and the easiest way to ensure this is by *namespacing* them. That is, + by putting those static files inside *another* directory named for the + application itself. + +Put the following code in that stylesheet (``polls/static/polls/style.css``): + +.. code-block:: css + + li a { + color: green; + } + +Next, add the following at the top of ``polls/templates/polls/index.html``: + +.. code-block:: html+django + + {% load staticfiles %} + + + +``{% load staticfiles %}`` loads the :ttag:`{% static %} ` +template tag from the ``staticfiles`` template library. The ``{% static %}`` +template tag generates the absolute URL of the static file. + +That's all you need to do for development. Reload +``http://localhost:8000/polls/`` and you should see that the poll links are +green (Django style!) which means that your stylesheet was properly loaded. + +Adding a background-image +========================= + +Next, we'll create a subdirectory for images. Create an ``images`` subdirectory +in the ``polls/static/polls/`` directory. Inside this directory, put an image +called ``background.gif``. In other words, put your image in +``polls/static/polls/images/background.gif``. + +Then, add to your stylesheet (``polls/static/polls/style.css``): + +.. code-block:: css + + body { + background: white url("images/background.gif") no-repeat right bottom; + } + +Reload ``http://localhost:8000/polls/`` and you should see the background +loaded in the bottom right of the screen. + +.. warning:: + + Of course the ``{% static %}`` template tag is not available for use in + static files like your stylesheet which aren't generated by Django. You + should always use **relative paths** to link your static files between each + other, because then you can change :setting:`STATIC_URL` (used by the + :ttag:`static` template tag to generate its URLs) without having to modify + a bunch of paths in your static files as well. + +These are the **basics**. For more details on settings and other bits included +with the framework see +:doc:`the static files howto ` and the +:doc:`the staticfiles reference `. :doc:`Deploying +static files ` discusses how to use static +files on a real server. + +What's next? +============ + +The beginner tutorial ends here for the time being. In the meantime, you might +want to check out some pointers on :doc:`where to go from here +`. + +If you are familiar with Python packaging and interested in learning how to +turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to +write reusable apps`. -- cgit v1.3