<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Writing your first Django app, part 6 — Django 1.5.9 documentation</title> <link rel="stylesheet" href="../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '1.5.9', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="top" title="Django 1.5.9 documentation" href="../index.html" /> <link rel="up" title="Getting started" href="index.html" /> <link rel="next" title="Advanced tutorial: How to write reusable apps" href="reusable-apps.html" /> <link rel="prev" title="Writing your first Django app, part 5" href="tutorial05.html" /> <script type="text/javascript" src="../templatebuiltins.js"></script> <script type="text/javascript"> (function($) { if (!django_template_builtins) { // templatebuiltins.js missing, do nothing. return; } $(document).ready(function() { // Hyperlink Django template tags and filters var base = "../ref/templates/builtins.html"; if (base == "#") { // Special case for builtins.html itself base = ""; } // Tags are keywords, class '.k' $("div.highlight\\-html\\+django span.k").each(function(i, elem) { var tagname = $(elem).text(); if ($.inArray(tagname, django_template_builtins.ttags) != -1) { var fragment = tagname.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>"); } }); // Filters are functions, class '.nf' $("div.highlight\\-html\\+django span.nf").each(function(i, elem) { var filtername = $(elem).text(); if ($.inArray(filtername, django_template_builtins.tfilters) != -1) { var fragment = filtername.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>"); } }); }); })(jQuery); </script> </head> <body> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../index.html">Django 1.5.9 documentation</a></h1> <div id="global-nav"> <a title="Home page" href="../index.html">Home</a> | <a title="Table of contents" href="../contents.html">Table of contents</a> | <a title="Global index" href="../genindex.html">Index</a> | <a title="Module index" href="../py-modindex.html">Modules</a> </div> <div class="nav"> « <a href="tutorial05.html" title="Writing your first Django app, part 5">previous</a> | <a href="index.html" title="Getting started" accesskey="U">up</a> | <a href="reusable-apps.html" title="Advanced tutorial: How to write reusable apps">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="intro-tutorial06"> <div class="section" id="s-writing-your-first-django-app-part-6"> <span id="writing-your-first-django-app-part-6"></span><h1>Writing your first Django app, part 6<a class="headerlink" href="#writing-your-first-django-app-part-6" title="Permalink to this headline">¶</a></h1> <p>This tutorial begins where <a class="reference internal" href="tutorial05.html"><em>Tutorial 5</em></a> left off. We’ve built a tested Web-poll application, and we’ll now add a stylesheet and an image.</p> <p>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”.</p> <p>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.</p> <p>That’s what <tt class="docutils literal"><span class="pre">django.contrib.staticfiles</span></tt> 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.</p> <div class="section" id="s-customize-your-app-s-look-and-feel"> <span id="customize-your-app-s-look-and-feel"></span><h2>Customize your <em>app’s</em> look and feel<a class="headerlink" href="#customize-your-app-s-look-and-feel" title="Permalink to this headline">¶</a></h2> <p>First, create a directory called <tt class="docutils literal"><span class="pre">static</span></tt> in your <tt class="docutils literal"><span class="pre">polls</span></tt> directory. Django will look for static files there, similarly to how Django finds templates inside <tt class="docutils literal"><span class="pre">polls/templates/</span></tt>.</p> <p>Django’s <a class="reference internal" href="../ref/contrib/staticfiles.html#std:setting-STATICFILES_FINDERS"><tt class="xref std std-setting docutils literal"><span class="pre">STATICFILES_FINDERS</span></tt></a> setting contains a list of finders that know how to discover static files from various sources. One of the defaults is <tt class="docutils literal"><span class="pre">AppDirectoriesFinder</span></tt> which looks for a “static” subdirectory in each of the <a class="reference internal" href="../ref/settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a>, like the one in <tt class="docutils literal"><span class="pre">polls</span></tt> we just created. The admin site uses the same directory structure for its static files.</p> <p>Within the <tt class="docutils literal"><span class="pre">static</span></tt> directory you have just created, create another directory called <tt class="docutils literal"><span class="pre">polls</span></tt> and within that create a file called <tt class="docutils literal"><span class="pre">style.css</span></tt>. In other words, your stylesheet should be at <tt class="docutils literal"><span class="pre">polls/static/polls/style.css</span></tt>. Because of how the <tt class="docutils literal"><span class="pre">AppDirectoriesFinder</span></tt> staticfile finder works, you can refer to this static file in Django simply as <tt class="docutils literal"><span class="pre">polls/style.css</span></tt>, similar to how you reference the path for templates.</p> <div class="admonition-static-file-namespacing admonition"> <p class="first admonition-title">Static file namespacing</p> <p class="last">Just like templates, we <em>might</em> be able to get away with putting our static files directly in <tt class="docutils literal"><span class="pre">polls/static</span></tt> (rather than creating another <tt class="docutils literal"><span class="pre">polls</span></tt> 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 <em>different</em> 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 <em>namespacing</em> them. That is, by putting those static files inside <em>another</em> directory named for the application itself.</p> </div> <p>Put the following code in that stylesheet (<tt class="docutils literal"><span class="pre">polls/static/polls/style.css</span></tt>):</p> <div class="highlight-css"><div class="highlight"><pre><span class="nt">li</span> <span class="nt">a</span> <span class="p">{</span> <span class="k">color</span><span class="o">:</span> <span class="nb">green</span><span class="p">;</span> <span class="p">}</span> </pre></div> </div> <p>Next, add the following at the top of <tt class="docutils literal"><span class="pre">polls/templates/polls/index.html</span></tt>:</p> <div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">load</span> <span class="nv">staticfiles</span> <span class="cp">%}</span> <span class="nt"><link</span> <span class="na">rel=</span><span class="s">"stylesheet"</span> <span class="na">type=</span><span class="s">"text/css"</span> <span class="na">href=</span><span class="s">"</span><span class="cp">{%</span> <span class="k">static</span> <span class="s1">'polls/style.css'</span> <span class="cp">%}</span><span class="s">"</span> <span class="nt">/></span> </pre></div> </div> <p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">staticfiles</span> <span class="pre">%}</span></tt> loads the <a class="reference internal" href="../ref/contrib/staticfiles.html#std:templatetag-staticfiles-static"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">static</span> <span class="pre">%}</span></tt></a> template tag from the <tt class="docutils literal"><span class="pre">staticfiles</span></tt> template library. The <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">static</span> <span class="pre">%}</span></tt> template tag generates the absolute URL of the static file.</p> <p>That’s all you need to do for development. Reload <tt class="docutils literal"><span class="pre">http://localhost:8000/polls/</span></tt> and you should see that the poll links are green (Django style!) which means that your stylesheet was properly loaded.</p> </div> <div class="section" id="s-adding-a-background-image"> <span id="adding-a-background-image"></span><h2>Adding a background-image<a class="headerlink" href="#adding-a-background-image" title="Permalink to this headline">¶</a></h2> <p>Next, we’ll create a subdirectory for images. Create an <tt class="docutils literal"><span class="pre">images</span></tt> subdirectory in the <tt class="docutils literal"><span class="pre">polls/static/polls/</span></tt> directory. Inside this directory, put an image called <tt class="docutils literal"><span class="pre">background.gif</span></tt>. In other words, put your image in <tt class="docutils literal"><span class="pre">polls/static/polls/images/background.gif</span></tt>.</p> <p>Then, add to your stylesheet (<tt class="docutils literal"><span class="pre">polls/static/polls/style.css</span></tt>):</p> <div class="highlight-css"><div class="highlight"><pre><span class="nt">body</span> <span class="p">{</span> <span class="k">background</span><span class="o">:</span> <span class="nb">white</span> <span class="sx">url("images/background.gif")</span> <span class="k">no-repeat</span> <span class="k">right</span> <span class="k">bottom</span><span class="p">;</span> <span class="p">}</span> </pre></div> </div> <p>Reload <tt class="docutils literal"><span class="pre">http://localhost:8000/polls/</span></tt> and you should see the background loaded in the bottom right of the screen.</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">Of course the <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">static</span> <span class="pre">%}</span></tt> template tag is not available for use in static files like your stylesheet which aren’t generated by Django. You should always use <strong>relative paths</strong> to link your static files between each other, because then you can change <a class="reference internal" href="../ref/settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a> (used by the <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-static"><tt class="xref std std-ttag docutils literal"><span class="pre">static</span></tt></a> template tag to generate its URLs) without having to modify a bunch of paths in your static files as well.</p> </div> <p>These are the <strong>basics</strong>. For more details on settings and other bits included with the framework see <a class="reference internal" href="../howto/static-files/index.html"><em>the static files howto</em></a> and <a class="reference internal" href="../ref/contrib/staticfiles.html"><em>the staticfiles reference</em></a>. <a class="reference internal" href="../howto/static-files/deployment.html"><em>Deploying static files</em></a> discusses how to use static files on a real server.</p> </div> <div class="section" id="s-what-s-next"> <span id="what-s-next"></span><h2>What’s next?<a class="headerlink" href="#what-s-next" title="Permalink to this headline">¶</a></h2> <p>The beginner tutorial ends here for the time being. In the meantime, you might want to check out some pointers on <a class="reference internal" href="whatsnext.html"><em>where to go from here</em></a>.</p> <p>If you are familiar with Python packaging and interested in learning how to turn polls into a “reusable app”, check out <a class="reference internal" href="reusable-apps.html"><em>Advanced tutorial: How to write reusable apps</em></a>.</p> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Writing your first Django app, part 6</a><ul> <li><a class="reference internal" href="#customize-your-app-s-look-and-feel">Customize your <em>app’s</em> look and feel</a></li> <li><a class="reference internal" href="#adding-a-background-image">Adding a background-image</a></li> <li><a class="reference internal" href="#what-s-next">What’s next?</a></li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="tutorial05.html">Writing your first Django app, part 5</a></li> <li>Next: <a href="reusable-apps.html">Advanced tutorial: How to write reusable apps</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../index.html">Django 1.5.9 documentation</a> <ul><li><a href="index.html">Getting started</a> <ul><li>Writing your first Django app, part 6</li></ul> </li></ul> </li> </ul> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/intro/tutorial06.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">Jan 15, 2015</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="tutorial05.html" title="Writing your first Django app, part 5">previous</a> | <a href="index.html" title="Getting started" accesskey="U">up</a> | <a href="reusable-apps.html" title="Advanced tutorial: How to write reusable apps">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>