Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Added tutorial06: using AppDirectoryFinder. #795

Closed
wants to merge 19 commits into
from

Conversation

Projects
None yet
3 participants

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial05.txt
@@ -640,10 +640,8 @@ 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
-</intro/whatsnext>`.
+For full details on testing, see :doc:`Testing in Django
+</topics/testing>` documentation.
@timgraham

timgraham Feb 23, 2013

Owner

remove "documentation" (or alternately, say "the Testing in Django documentation")

@timgraham

timgraham Feb 23, 2013

Owner

topics/testing is a broken link, think it should be topics/testing/index

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial05.txt
-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</intro/reusable-apps>`.
+When you're comfortable with testing server side code, read :doc:`part 6 of this
@timgraham

timgraham Feb 23, 2013

Owner

hyphenate "server-side"

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+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.
+
+Customize your *app's* look and feel
+====================================
+
+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".
+
+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
@timgraham

timgraham Feb 23, 2013

Owner

amend to say something like "a list of finders (subclasses of django.contrib.staticfiles.finders.BaseFinder)"?

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+We've built a tested Web-poll application, and we'll now add a stylesheet.
+
+Customize your *app's* look and feel
+====================================
+
+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".
+
+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
+:class:`django.contrib.staticfiles.finders.BaseFinder` that know how to
@timgraham

timgraham Feb 23, 2013

Owner

django.contrib.staticfiles.finders.BaseFinder isn't documented so omit the :class: markup and use django.contrib.staticfiles.finders.BaseFinder instead, unless you want to add something so it isn't a broken link

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+Customize your *app's* look and feel
+====================================
+
+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".
+
+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
+:class:`django.contrib.staticfiles.finders.BaseFinder` that know how to
+discover static files from various sources. One of the defaults is
+:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder` which looks
@timgraham

timgraham Feb 23, 2013

Owner

like BaseFinder, AppDirectoriesFinder also lacks a link target

@timgraham timgraham commented on the diff Feb 23, 2013

docs/intro/tutorial06.txt
+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
+:class:`django.contrib.staticfiles.finders.BaseFinder` that know how to
+discover static files from various sources. One of the defaults is
+:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder` which looks
+for a "static" subdirectory in each of the :setting:`INSTALLED_APPS` - this is
+how Django knows to find the polls static files by default, including for the
+admin site.
+
+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 ``AppDirectoriesFinder`` staticfile finder works as described above, you
@timgraham

timgraham Feb 23, 2013

Owner

how the AppDirectoriesFinder staticfile finder works. I'd also probably drop "as described above"

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+inside ``polls/templates/``.
+
+Django's :setting:`STATICFILES_FINDERS` setting contains a list of
+:class:`django.contrib.staticfiles.finders.BaseFinder` that know how to
+discover static files from various sources. One of the defaults is
+:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder` which looks
+for a "static" subdirectory in each of the :setting:`INSTALLED_APPS` - this is
+how Django knows to find the polls static files by default, including for the
+admin site.
+
+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 ``AppDirectoriesFinder`` staticfile finder works as described above, you
+can refer to this static file in Django simply as ``polls/style.css``, exactly
+like for templates.
@timgraham

timgraham Feb 23, 2013

Owner

instead of "exactly like for templates" I would say "similar to how you reference the path for templates"

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+ 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;
+ }
+
+And, add at the top of your ``polls/templates/polls/index.html``:
@timgraham

timgraham Feb 23, 2013

Owner

And add the following at the top

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+ 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;
+ }
+
+And, add at the top of your ``polls/templates/polls/index.html``:
+
+.. code-block:: html+django
+
+ {# this enables the static template tag #}
@timgraham

timgraham Feb 23, 2013

Owner

not sure we want to actually encourage this type of commenting, maybe just explain it in the paragraph that follows?

@timgraham timgraham commented on an outdated diff Feb 23, 2013

docs/intro/tutorial06.txt
+ li a {
+ color: green;
+ }
+
+And, add at the top of your ``polls/templates/polls/index.html``:
+
+.. code-block:: html+django
+
+ {# this enables the static template tag #}
+ {% load staticfiles %}
+
+ <link rel="stylesheet" type="text/css" href="{% static 'polls/style.css' %}" />
+
+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..
@timgraham

timgraham Feb 23, 2013

Owner

I laughed.... "Django style!"
fix double period at end of sentence

@timgraham timgraham commented on the diff Feb 23, 2013

docs/intro/tutorial06.txt
+=========================
+
+We will 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;
+ }
+
+That's all you need for the development server. Reload
@timgraham

timgraham Feb 23, 2013

Owner

leaves me wondering what I need to do when I'm not using the development server

@jpic

jpic Feb 24, 2013

Contributor

Me too because of the moving parts of this documentation. But I think we should link to the deployment docs when it has a section for staticfiles.

@reinout

reinout Feb 24, 2013

I'd add this after the "reload":

For more information, see the :doc:static files howto</howto/static-files> and :doc:/howto/static-files-in-production.

That should do it, especially that second "hey, production deployment!" link.

@reinout

reinout Feb 24, 2013

The deployment howto is part of #801. I'm making a last set of fixes to that one.

Owner

timgraham commented Feb 23, 2013

Thanks, this is a solid start. I've left some comments. If you could also update intro/reusable-apps.txt to reflect the presence of this tutorial (Tutorials 1-6 and "our project should look like this" should include the new static directory) that would be fantastic.

Contributor

jpic commented Feb 24, 2013

It is now.

On Sun, Feb 24, 2013 at 4:24 PM, Reinout van Rees
notifications@github.comwrote:

@jpic https://github.com/jpic is
http://yourlabs.org/site_media/django/docs/_build/html/intro/tutorial06.htmlup to date?


Reply to this email directly or view it on GitHubhttps://github.com/django/django/pull/795#issuecomment-14009929.

http://yourlabs.org http://blog.yourlabs.org
Customer is king - Le client est roi - El cliente es rey.

reinout commented Feb 24, 2013

One error I can see: "In your template, load the {% static %} template tag from the staticfiles template library with {% load static %}"

That should be "{% load staticfiles %}" (as it is in your example code).

@reinout reinout commented on an outdated diff Feb 24, 2013

docs/intro/tutorial06.txt
+In your template, load the ``{% static %}`` template tag from the
+``staticfiles`` template library with ``{% load static %}``. Then, use ``{%
+static %}`` to generate the absolute URL of the static file. Add the following
+at the top of your ``polls/templates/polls/index.html``:
+
+.. code-block:: html+django
+
+ {% load staticfiles %}
+
+ <link rel="stylesheet" type="text/css" href="{% static 'polls/style.css' %}" />
+
+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.
+
+See :doc:`deploying static files in production </howto/static-files-in-production>` for more information.
@reinout

reinout Feb 24, 2013

The title "deploying static files in production" has been changed into just "deploying static files" (after feedback).

Contributor

jpic commented Feb 24, 2013

Oops, forgot to comment that I pushed the fix. Thanks !!

@timgraham timgraham closed this Mar 30, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment