| 1 |
===================================== |
| 2 |
Writing your first Django app, part 6 |
| 3 |
===================================== |
| 4 |
|
| 5 |
This tutorial begins where :doc:`Tutorial 5 </intro/tutorial05>` left off. |
| 6 |
We've built a tested web-poll application, and we'll now add a stylesheet and |
| 7 |
an image. |
| 8 |
|
| 9 |
Aside from the HTML generated by the server, web applications generally need |
| 10 |
to serve additional files — such as images, JavaScript, or CSS — necessary to |
| 11 |
render the complete web page. In Django, we refer to these files as "static |
| 12 |
files". |
| 13 |
|
| 14 |
For small projects, this isn't a big deal, because you can keep the static |
| 15 |
files somewhere your web server can find it. However, in bigger projects -- |
| 16 |
especially those comprised of multiple apps -- dealing with the multiple sets |
| 17 |
of static files provided by each application starts to get tricky. |
| 18 |
|
| 19 |
That's what ``django.contrib.staticfiles`` is for: it collects static files |
| 20 |
from each of your applications (and any other places you specify) into a |
| 21 |
single location that can easily be served in production. |
| 22 |
|
| 23 |
.. admonition:: Where to get help: |
| 24 |
|
| 25 |
If you're having trouble going through this tutorial, please head over to |
| 26 |
the :doc:`Getting Help</faq/help>` section of the FAQ. |
| 27 |
|
| 28 |
Customize your *app's* look and feel |
| 29 |
==================================== |
| 30 |
|
| 31 |
First, create a directory called ``static`` in your ``polls`` directory. Django |
| 32 |
will look for static files there, similarly to how Django finds templates |
| 33 |
inside ``polls/templates/``. |
| 34 |
|
| 35 |
Django's :setting:`STATICFILES_FINDERS` setting contains a list |
| 36 |
of finders that know how to discover static files from various |
| 37 |
sources. One of the defaults is ``AppDirectoriesFinder`` which |
| 38 |
looks for a "static" subdirectory in each of the |
| 39 |
:setting:`INSTALLED_APPS`, like the one in ``polls`` we just created. The admin |
| 40 |
site uses the same directory structure for its static files. |
| 41 |
|
| 42 |
Within the ``static`` directory you have just created, create another directory |
| 43 |
called ``polls`` and within that create a file called ``style.css``. In other |
| 44 |
words, your stylesheet should be at ``polls/static/polls/style.css``. Because |
| 45 |
of how the ``AppDirectoriesFinder`` staticfile finder works, you can refer to |
| 46 |
this static file in Django as ``polls/style.css``, similar to how you reference |
| 47 |
the path for templates. |
| 48 |
|
| 49 |
.. admonition:: Static file namespacing |
| 50 |
|
| 51 |
Just like templates, we *might* be able to get away with putting our static |
| 52 |
files directly in ``polls/static`` (rather than creating another ``polls`` |
| 53 |
subdirectory), but it would actually be a bad idea. Django will choose the |
| 54 |
first static file it finds whose name matches, and if you had a static file |
| 55 |
with the same name in a *different* application, Django would be unable to |
| 56 |
distinguish between them. We need to be able to point Django at the right |
| 57 |
one, and the best way to ensure this is by *namespacing* them. That is, by |
| 58 |
putting those static files inside *another* directory named for the |
| 59 |
application itself. |
| 60 |
|
| 61 |
Put the following code in that stylesheet (``polls/static/polls/style.css``): |
| 62 |
|
| 63 |
.. code-block:: css |
| 64 |
:caption: ``polls/static/polls/style.css`` |
| 65 |
|
| 66 |
li a { |
| 67 |
color: green; |
| 68 |
} |
| 69 |
|
| 70 |
Next, add the following at the top of ``polls/templates/polls/index.html``: |
| 71 |
|
| 72 |
.. code-block:: html+django |
| 73 |
:caption: ``polls/templates/polls/index.html`` |
| 74 |
|
| 75 |
{% load static %} |
| 76 |
|
| 77 |
<link rel="stylesheet" href="{% static 'polls/style.css' %}"> |
| 78 |
|
| 79 |
The ``{% static %}`` template tag generates the absolute URL of static files. |
| 80 |
|
| 81 |
That's all you need to do for development. |
| 82 |
|
| 83 |
Start the server (or restart it if it's already running): |
| 84 |
|
| 85 |
.. console:: |
| 86 |
|
| 87 |
$ python manage.py runserver |
| 88 |
|
| 89 |
Reload ``http://localhost:8000/polls/`` and you should see that the question |
| 90 |
links are green (Django style!) which means that your stylesheet was properly |
| 91 |
loaded. |
| 92 |
|
| 93 |
Adding a background-image |
| 94 |
========================= |
| 95 |
|
| 96 |
Next, we'll create a subdirectory for images. Create an ``images`` subdirectory |
| 97 |
in the ``polls/static/polls/`` directory. Inside this directory, add any image |
| 98 |
file that you'd like to use as a background. For the purposes of this tutorial, |
| 99 |
we're using a file named ``background.png``, which will have the full path |
| 100 |
``polls/static/polls/images/background.png``. |
| 101 |
|
| 102 |
Then, add a reference to your image in your stylesheet |
| 103 |
(``polls/static/polls/style.css``): |
| 104 |
|
| 105 |
.. code-block:: css |
| 106 |
:caption: ``polls/static/polls/style.css`` |
| 107 |
|
| 108 |
body { |
| 109 |
background: white url("images/background.png") no-repeat; |
| 110 |
} |
| 111 |
|
| 112 |
Reload ``http://localhost:8000/polls/`` and you should see the background |
| 113 |
loaded in the top left of the screen. |
| 114 |
|
| 115 |
.. warning:: |
| 116 |
|
| 117 |
The ``{% static %}`` template tag is not available for use in static files |
| 118 |
which aren't generated by Django, like your stylesheet. You should always |
| 119 |
use **relative paths** to link your static files between each other, |
| 120 |
because then you can change :setting:`STATIC_URL` (used by the |
| 121 |
:ttag:`static` template tag to generate its URLs) without having to modify |
| 122 |
a bunch of paths in your static files as well. |
| 123 |
|
| 124 |
These are the **basics**. For more details on settings and other bits included |
| 125 |
with the framework see |
| 126 |
:doc:`the static files howto </howto/static-files/index>` and |
| 127 |
:doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying |
| 128 |
static files </howto/static-files/deployment>` discusses how to use static |
| 129 |
files on a real server. |
| 130 |
|
| 131 |
When you're comfortable with the static files, read :doc:`part 7 of this |
| 132 |
tutorial </intro/tutorial07>` to learn how to customize Django's |
| 133 |
automatically-generated admin site. |