134 lines
5.4 KiB
Plaintext
134 lines
5.4 KiB
Plaintext
=====================================
|
|
Writing your first Django app, part 6
|
|
=====================================
|
|
|
|
This tutorial begins where :doc:`Tutorial 5 </intro/tutorial05>` 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 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.
|
|
|
|
.. admonition:: Where to get help:
|
|
|
|
If you're having trouble going through this tutorial, please head over to
|
|
the :doc:`Getting Help</faq/help>` section of the FAQ.
|
|
|
|
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 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 best 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
|
|
:caption: polls/static/polls/style.css
|
|
|
|
li a {
|
|
color: green;
|
|
}
|
|
|
|
Next, add the following at the top of ``polls/templates/polls/index.html``:
|
|
|
|
.. code-block:: html+django
|
|
:caption: polls/templates/polls/index.html
|
|
|
|
{% load static %}
|
|
|
|
<link rel="stylesheet" href="{% static 'polls/style.css' %}">
|
|
|
|
The ``{% static %}`` template tag generates the absolute URL of static files.
|
|
|
|
That's all you need to do for development.
|
|
|
|
Start the server (or restart it if it's already running):
|
|
|
|
.. console::
|
|
|
|
$ python manage.py runserver
|
|
|
|
Reload ``http://localhost:8000/polls/`` and you should see that the question
|
|
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, add any image
|
|
file that you'd like to use as a background. For the purposes of this tutorial,
|
|
we're using a file named ``background.png``, which will have the full path
|
|
``polls/static/polls/images/background.png``.
|
|
|
|
Then, add a reference to your image in your stylesheet
|
|
(``polls/static/polls/style.css``):
|
|
|
|
.. code-block:: css
|
|
:caption: polls/static/polls/style.css
|
|
|
|
body {
|
|
background: white url("images/background.png") no-repeat;
|
|
}
|
|
|
|
Reload ``http://localhost:8000/polls/`` and you should see the background
|
|
loaded in the top left of the screen.
|
|
|
|
.. warning::
|
|
|
|
The ``{% static %}`` template tag is not available for use in static files
|
|
which aren't generated by Django, like your stylesheet. 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 </howto/static-files/index>` and
|
|
:doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying
|
|
static files </howto/static-files/deployment>` discusses how to use static
|
|
files on a real server.
|
|
|
|
When you're comfortable with the static files, read :doc:`part 7 of this
|
|
tutorial </intro/tutorial07>` to learn how to customize Django's
|
|
automatically-generated admin site.
|