From 97cb07c3a10ff0e584a260a7ee1001614691eb1d Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Sat, 23 Aug 2008 22:25:40 +0000 Subject: Massive reorganization of the docs. See the new docs online at http://docs.djangoproject.com/. git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/tutorial02.txt | 461 ---------------------------------------------------- 1 file changed, 461 deletions(-) delete mode 100644 docs/tutorial02.txt (limited to 'docs/tutorial02.txt') diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt deleted file mode 100644 index 0b17593165..0000000000 --- a/docs/tutorial02.txt +++ /dev/null @@ -1,461 +0,0 @@ -===================================== -Writing your first Django app, part 2 -===================================== - -This tutorial begins where `Tutorial 1`_ left off. We're continuing the Web-poll -application and will focus on Django's automatically-generated admin site. - -.. _Tutorial 1: ../tutorial01/ - -.. admonition:: Philosophy - - Generating admin sites for your staff or clients to add, change and delete - content is tedious work that doesn't require much creativity. For that reason, - Django entirely automates creation of admin interfaces for models. - - Django was written in a newsroom environment, with a very clear separation - between "content publishers" and the "public" site. Site managers use the - system to add news stories, events, sports scores, etc., and that content is - displayed on the public site. Django solves the problem of creating a unified - interface for site administrators to edit content. - - The admin isn't necessarily intended to be used by site visitors; it's for site - managers. - -Activate the admin site -======================= - -The Django admin site is not activated by default -- it's an opt-in thing. To -activate the admin site for your installation, do these three things: - - * Add ``"django.contrib.admin"`` to your ``INSTALLED_APPS`` setting. - - * Run ``python manage.py syncdb``. Since you have added a new application - to ``INSTALLED_APPS``, the database tables need to be updated. - - * Edit your ``mysite/urls.py`` file and uncomment the lines below the - "Uncomment this for admin:" comments. This file is a URLconf; we'll dig - into URLconfs in the next tutorial. For now, all you need to know is that - it maps URL roots to applications. In the end, you should have a - ``urls.py`` file that looks like this: - - .. parsed-literal:: - - from django.conf.urls.defaults import * - - # Uncomment the next two lines to enable the admin: - **from django.contrib import admin** - **admin.autodiscover()** - - urlpatterns = patterns('', - # Example: - # (r'^{{ project_name }}/', include('{{ project_name }}.foo.urls')), - - # Uncomment the next line to enable admin documentation: - # (r'^admin/doc/', include('django.contrib.admindocs.urls')), - - # Uncomment the next line for to enable the admin: - **(r'^admin/(.*)', admin.site.root),** - ) - - (The bold lines are the ones that needed to be uncommented.) - -Start the development server -============================ - -Let's start the development server and explore the admin site. - -Recall from Tutorial 1 that you start the development server like so:: - - python manage.py runserver - -Now, open a Web browser and go to "/admin/" on your local domain -- e.g., -http://127.0.0.1:8000/admin/. You should see the admin's login screen: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin01.png - :alt: Django admin login screen - -Enter the admin site -==================== - -Now, try logging in. (You created a superuser account in the first part of this -tutorial, remember?) You should see the Django admin index page: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin02t.png - :alt: Django admin index page - :target: http://media.djangoproject.com/img/doc/tutorial-trunk/admin02.png - -You should see a few other types of editable content, including groups, users -and sites. These are core features Django ships with by default. - -.. _"I can't log in" questions: ../faq/#the-admin-site - -Make the poll app modifiable in the admin -========================================= - -But where's our poll app? It's not displayed on the admin index page. - -Just one thing to do: We need to tell the admin that ``Poll`` -objects have an admin interface. Edit the ``mysite/polls/models.py`` file and -add the following to the bottom of the file:: - - from django.contrib import admin - - admin.site.register(Poll) - -Now reload the Django admin page to see your changes. Note that you don't have -to restart the development server -- the server will auto-reload your project, -so any modifications code will be seen immediately in your browser. - -Explore the free admin functionality -==================================== - -Now that we've registered ``Poll``, Django knows that it should be displayed on -the admin index page: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin03t.png - :alt: Django admin index page, now with polls displayed - :target: http://media.djangoproject.com/img/doc/tutorial-trunk/admin03.png - -Click "Polls." Now you're at the "change list" page for polls. This page -displays all the polls in the database and lets you choose one to change it. -There's the "What's up?" poll we created in the first tutorial: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin04t.png - :alt: Polls change list page - :target: http://media.djangoproject.com/img/doc/tutorial-trunk/admin04.png - -Click the "What's up?" poll to edit it: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin05t.png - :alt: Editing form for poll object - :target: http://media.djangoproject.com/img/doc/tutorial-trunk/admin05.png - -Things to note here: - -* The form is automatically generated from the Poll model. -* The different model field types (``models.DateTimeField``, ``models.CharField``) - correspond to the appropriate HTML input widget. Each type of field knows - how to display itself in the Django admin. -* Each ``DateTimeField`` gets free JavaScript shortcuts. Dates get a "Today" - shortcut and calendar popup, and times get a "Now" shortcut and a convenient - popup that lists commonly entered times. - -The bottom part of the page gives you a couple of options: - -* Save -- Saves changes and returns to the change-list page for this type of - object. -* Save and continue editing -- Saves changes and reloads the admin page for - this object. -* Save and add another -- Saves changes and loads a new, blank form for this - type of object. -* Delete -- Displays a delete confirmation page. - -Change the "Date published" by clicking the "Today" and "Now" shortcuts. Then -click "Save and continue editing." Then click "History" in the upper right. -You'll see a page listing all changes made to this object via the Django admin, -with the timestamp and username of the person who made the change: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin06t.png - :alt: History page for poll object - :target: http://media.djangoproject.com/img/doc/tutorial-trunk/admin06.png - -Customize the admin form -======================== - -Take a few minutes to marvel at all the code you didn't have to write. When you -call ``admin.site.register(Poll)``, Django just lets you edit the object and -"guess" at how to display it within the admin. Often you'll want to control how -the admin looks and works. You'll do this by telling Django about the options -you want when you register the object. - -Let's see how this works by reordering the fields on the edit form. Replace the -``admin.site.register(Poll)`` line with:: - - class PollAdmin(admin.ModelAdmin): - fields = ['pub_date', 'question'] - - admin.site.register(Poll, PollAdmin) - -You'll follow this pattern -- create a model admin object, then pass it as the -second argument to ``admin.site.register()`` -- any time you need to change the -admin options for an object. - -This particular change above makes the "Publication date" come before the -"Question" field: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin07.png - :alt: Fields have been reordered - -This isn't impressive with only two fields, but for admin forms with dozens -of fields, choosing an intuitive order is an important usability detail. - -And speaking of forms with dozens of fields, you might want to split the form -up into fieldsets:: - - class PollAdmin(admin.ModelAdmin): - fieldsets = [ - (None, {'fields': ['question']}), - ('Date information', {'fields': ['pub_date']}), - ] - - admin.site.register(Poll, PollAdmin) - -The first element of each tuple in ``fieldsets`` is the title of the fieldset. -Here's what our form looks like now: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin08t.png - :alt: Form has fieldsets now - :target: http://media.djangoproject.com/img/doc/tutorial-trunk/admin08.png - -You can assign arbitrary HTML classes to each fieldset. Django provides a -``"collapse"`` class that displays a particular fieldset initially collapsed. -This is useful when you have a long form that contains a number of fields that -aren't commonly used:: - - class PollAdmin(admin.ModelAdmin): - fieldsets = [ - (None, {'fields': ['question']}), - ('Date information', {'fields': ['pub_date'], 'classes': ['collapse']}), - ] - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin09.png - :alt: Fieldset is initially collapsed - -Adding related objects -====================== - -OK, we have our Poll admin page. But a ``Poll`` has multiple ``Choices``, and -the admin page doesn't display choices. - -Yet. - -There are two ways to solve this problem. The first register ``Choice`` with the -admin just as we did with ``Poll``. That's easy:: - - admin.site.register(Choice) - -Now "Choices" is an available option in the Django admin. The "Add choice" form -looks like this: - -.. image:: http://media.djangoproject.com/img/doc/tutorial-trunk/admin10.png - :alt: Choice admin page - -In that form, the "Poll" field is a select box containing every poll in the -database. Django knows that a ``ForeignKey`` should be represented in the admin -as a ``