Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #19582 - Added a static files tutorial.

Thanks James Pic.
  • Loading branch information...
commit c32fc79aa120a0a129680805aef6731c1c2c7aef 1 parent 9916e69
Tim Graham authored
0  docs/howto/static-files.txt → docs/howto/static-files/index.txt
File renamed without changes
3  docs/index.txt
@@ -45,7 +45,8 @@ Are you new to Django or to programming? This is the place to start!
45 45
   :doc:`Part 2 <intro/tutorial02>` |
46 46
   :doc:`Part 3 <intro/tutorial03>` |
47 47
   :doc:`Part 4 <intro/tutorial04>` |
48  
-  :doc:`Part 5 <intro/tutorial05>`
  48
+  :doc:`Part 5 <intro/tutorial05>` |
  49
+  :doc:`Part 6 <intro/tutorial06>`
49 50
 
50 51
 * **Advanced Tutorials:**
51 52
   :doc:`How to write reusable apps <intro/reusable-apps>` |
1  docs/intro/index.txt
@@ -14,6 +14,7 @@ place: read this material to quickly get up and running.
14 14
    tutorial03
15 15
    tutorial04
16 16
    tutorial05
  17
+   tutorial06
17 18
    reusable-apps
18 19
    whatsnext
19 20
    contributing
12  docs/intro/reusable-apps.txt
@@ -2,11 +2,11 @@
2 2
 Advanced tutorial: How to write reusable apps
3 3
 =============================================
4 4
 
5  
-This advanced tutorial begins where :doc:`Tutorial 5 </intro/tutorial05>` left
6  
-off. We'll be turning our Web-poll into a standalone Python package you can
7  
-reuse in new projects and share with other people.
  5
+This advanced tutorial begins where :doc:`Tutorial 6 </intro/tutorial06>`
  6
+left off. We'll be turning our Web-poll into a standalone Python package
  7
+you can reuse in new projects and share with other people.
8 8
 
9  
-If you haven't recently completed Tutorials 1–5, we encourage you to review
  9
+If you haven't recently completed Tutorials 1–6, we encourage you to review
10 10
 these so that your example project matches the one described below.
11 11
 
12 12
 Reusability matters
@@ -67,6 +67,10 @@ After the previous tutorials, our project should look like this::
67 67
             admin.py
68 68
             models.py
69 69
             tests.py
  70
+            static/
  71
+                style.css
  72
+                images/
  73
+                    background.gif
70 74
             templates/
71 75
                 polls/
72 76
                     detail.html
11  docs/intro/tutorial05.txt
@@ -640,10 +640,9 @@ information about testing.
640 640
 What's next?
641 641
 ============
642 642
 
643  
-The beginner tutorial ends here for the time being. In the meantime, you might
644  
-want to check out some pointers on :doc:`where to go from here
645  
-</intro/whatsnext>`.
  643
+For full details on testing, see :doc:`Testing in Django
  644
+</topics/testing/index>`.
646 645
 
647  
-If you are familiar with Python packaging and interested in learning how to
648  
-turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
649  
-write reusable apps</intro/reusable-apps>`.
  646
+When you're comfortable with testing Django views, read
  647
+:doc:`part 6 of this tutorial</intro/tutorial06>` to learn about
  648
+static files management.
125  docs/intro/tutorial06.txt
... ...
@@ -0,0 +1,125 @@
  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 just keep the
  15
+static files somewhere your web server can find it. However, in bigger
  16
+projects -- especially those comprised of multiple apps -- dealing with the
  17
+multiple sets of static files provided by each application starts to get
  18
+tricky.
  19
+
  20
+That's what ``django.contrib.staticfiles`` is for: it collects static files
  21
+from each of your applications (and any other places you specify) into a
  22
+single location that can easily be served in production.
  23
+
  24
+Customize your *app's* look and feel
  25
+====================================
  26
+
  27
+First, create a directory called ``static`` in your ``polls`` directory. Django
  28
+will look for static files there, similarly to how Django finds templates
  29
+inside ``polls/templates/``.
  30
+
  31
+Django's :setting:`STATICFILES_FINDERS` setting contains a list
  32
+of finders that know how to discover static files from various
  33
+sources. One of the defaults is ``AppDirectoriesFinder`` which
  34
+looks for a "static" subdirectory in each of the
  35
+:setting:`INSTALLED_APPS`, like the one in ``polls`` we just created. The admin
  36
+site uses the same directory structure for its static files.
  37
+
  38
+Within the ``static`` directory you have just created, create another directory
  39
+called ``polls`` and within that create a file called ``style.css``. In other
  40
+words, your stylesheet should be at ``polls/static/polls/style.css``. Because
  41
+of how the ``AppDirectoriesFinder`` staticfile finder works, you can refer to
  42
+this static file in Django simply as ``polls/style.css``, similar to how you
  43
+reference the path for templates.
  44
+
  45
+.. admonition:: Static file namespacing
  46
+
  47
+    Just like templates, we *might* be able to get away with putting our static
  48
+    files directly in ``polls/static`` (rather than creating another ``polls``
  49
+    subdirectory), but it would actually be a bad idea. Django will choose the
  50
+    first static file it finds whose name matches, and if you had a static file
  51
+    with the same name in a *different* application, Django would be unable to
  52
+    distinguish between them. We need to be able to point Django at the right
  53
+    one, and the easiest way to ensure this is by *namespacing* them. That is,
  54
+    by putting those static files inside *another* directory named for the
  55
+    application itself.
  56
+
  57
+Put the following code in that stylesheet (``polls/static/polls/style.css``):
  58
+
  59
+.. code-block:: css
  60
+
  61
+    li a {
  62
+        color: green;
  63
+    }
  64
+
  65
+Next, add the following at the top of ``polls/templates/polls/index.html``:
  66
+
  67
+.. code-block:: html+django
  68
+
  69
+    {% load staticfiles %}
  70
+
  71
+    <link rel="stylesheet" type="text/css" href="{% static 'polls/style.css' %}" />
  72
+
  73
+``{% load staticfiles %}`` loads the :ttag:`{% static %} <staticfiles-static>`
  74
+template tag from the ``staticfiles`` template library. The ``{% static %}``
  75
+template tag generates the absolute URL of the static file.
  76
+
  77
+That's all you need to do for development. Reload
  78
+``http://localhost:8000/polls/`` and you should see that the poll links are
  79
+green (Django style!) which means that your stylesheet was properly loaded.
  80
+
  81
+Adding a background-image
  82
+=========================
  83
+
  84
+Next, we'll create a subdirectory for images. Create an ``images`` subdirectory
  85
+in the ``polls/static/polls/`` directory. Inside this directory, put an image
  86
+called ``background.gif``. In other words, put your image in
  87
+``polls/static/polls/images/background.gif``.
  88
+
  89
+Then, add to your stylesheet (``polls/static/polls/style.css``):
  90
+
  91
+.. code-block:: css
  92
+
  93
+    body {
  94
+        background: white url("images/background.gif") no-repeat right bottom;
  95
+    }
  96
+
  97
+Reload ``http://localhost:8000/polls/`` and you should see the background
  98
+loaded in the bottom right of the screen.
  99
+
  100
+.. warning::
  101
+
  102
+    Of course the ``{% static %}`` template tag is not available for use in
  103
+    static files like your stylesheet which aren't generated by Django. You
  104
+    should always use **relative paths** to link your static files between each
  105
+    other, because then you can change :setting:`STATIC_URL` (used by the
  106
+    :ttag:`static` template tag to generate its URLs) without having to modify
  107
+    a bunch of paths in your static files as well.
  108
+
  109
+These are the **basics**. For more details on settings and other bits included
  110
+with the framework see
  111
+:doc:`the static files howto </howto/static-files>` and the
  112
+:doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying
  113
+static files </howto/static-files/deployment>` discusses how to use static
  114
+files on a real server.
  115
+
  116
+What's next?
  117
+============
  118
+
  119
+The beginner tutorial ends here for the time being. In the meantime, you might
  120
+want to check out some pointers on :doc:`where to go from here
  121
+</intro/whatsnext>`.
  122
+
  123
+If you are familiar with Python packaging and interested in learning how to
  124
+turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
  125
+write reusable apps</intro/reusable-apps>`.

0 notes on commit c32fc79

Please sign in to comment.
Something went wrong with that request. Please try again.