diff --git a/docs/howto/static-files.txt b/docs/howto/static-files/index.txt similarity index 100% rename from docs/howto/static-files.txt rename to docs/howto/static-files/index.txt 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`.