From 7325fbf4ff20f9b0f21d3a1aba1abaca78a765d7 Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Sat, 15 Sep 2007 21:46:18 +0000 Subject: queryset-refactor: Merged to [6250] git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6339 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/add_ons.txt | 5 ++- docs/form_preview.txt | 97 ++++++++++++++++++++++++++++++++++++++++ docs/shortcuts.txt | 120 ++++++++++++++++++++++++++++++++++++++++++++++---- docs/templates.txt | 7 ++- docs/tutorial01.txt | 10 +++++ 5 files changed, 226 insertions(+), 13 deletions(-) create mode 100644 docs/form_preview.txt (limited to 'docs') diff --git a/docs/add_ons.txt b/docs/add_ons.txt index a1d78b8685..00c6e0dcf4 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -70,8 +70,9 @@ An abstraction of the following workflow: "Display an HTML form, force a preview, then do something with the submission." -Full documentation for this feature does not yet exist, but you can read the -code and docstrings in ``django/contrib/formtools/preview.py`` for a start. +See the `form preview documentation`_. + +.. _form preview documentation: ../form_preview/ humanize ======== diff --git a/docs/form_preview.txt b/docs/form_preview.txt new file mode 100644 index 0000000000..4be7b07a74 --- /dev/null +++ b/docs/form_preview.txt @@ -0,0 +1,97 @@ +============ +Form preview +============ + +Django comes with an optional "form preview" application that helps automate +the following workflow: + +"Display an HTML form, force a preview, then do something with the submission." + +To force a preview of a form submission, all you have to do is write a short +Python class. + +Overview +========= + +Given a ``django.newforms.Form`` subclass that you define, this application +takes care of the following workflow: + + 1. Displays the form as HTML on a Web page. + 2. Validates the form data when it's submitted via POST. + a. If it's valid, displays a preview page. + b. If it's not valid, redisplays the form with error messages. + 3. When the "confirmation" form is submitted from the preview page, calls + a hook that you define -- a ``done()`` method that gets passed the valid + data. + +The framework enforces the required preview by passing a shared-secret hash to +the preview page via hidden form fields. If somebody tweaks the form parameters +on the preview page, the form submission will fail the hash-comparison test. + +How to use ``FormPreview`` +========================== + + 1. Point Django at the default FormPreview templates. There are two ways to + do this: + + * Add ``'django.contrib.formtools'`` to your ``INSTALLED_APPS`` + setting. This will work if your ``TEMPLATE_LOADERS`` setting includes + the ``app_directories`` template loader (which is the case by + default). See the `template loader docs`_ for more. + + * Otherwise, determine the full filesystem path to the + ``django/contrib/formtools/templates`` directory, and add that + directory to your ``TEMPLATE_DIRS`` setting. + + 2. Create a ``FormPreview`` subclass that overrides the ``done()`` method:: + + from django.contrib.formtools import FormPreview + from myapp.models import SomeModel + + class SomeModelFormPreview(FormPreview): + + def done(self, request, cleaned_data): + # Do something with the cleaned_data, then redirect + # to a "success" page. + return HttpResponseRedirect('/form/success') + + This method takes an ``HttpRequest`` object and a dictionary of the form + data after it has been validated and cleaned. It should return an + ``HttpResponseRedirect`` that is the end result of the form being + submitted. + + 3. Change your URLconf to point to an instance of your ``FormPreview`` + subclass:: + + from myapp.preview import SomeModelFormPreview + from myapp.models import SomeModel + from django import newforms as forms + + ...and add the following line to the appropriate model in your URLconf:: + + (r'^post/$', SomeModelFormPreview(forms.models.form_for_model(SomeModel))), + + Or, if you already have a Form class defined for the model:: + + (r'^post/$', SomeModelFormPreview(SomeModelForm)), + + 4. Run the Django server and visit ``/post/`` in your browser. + +.. _template loader docs: ../templates_python/#loader-types + +``FormPreview`` classes +======================= + +A ``FormPreview`` class is a simple Python class that represents the preview +workflow. ``FormPreview`` classes must subclass +``django.contrib.formtools.preview.FormPreview`` and override the ``done()`` +method. They can live anywhere in your codebase. + +``FormPreview`` templates +========================= + +By default, the form is rendered via the template ``formtools/form.html``, and +the preview page is rendered via the template ``formtools.preview.html``. +These values can be overridden for a particular form preview by setting +``preview_template`` and ``form_template`` attributes on the FormPreview +subclass. See ``django/contrib/formtools/templates`` for the default templates. diff --git a/docs/shortcuts.txt b/docs/shortcuts.txt index 2c0dbb5663..6c55486b5f 100644 --- a/docs/shortcuts.txt +++ b/docs/shortcuts.txt @@ -6,36 +6,138 @@ The package ``django.shortcuts`` collects helper functions and classes that "span" multiple levels of MVC. In other words, these functions/classes introduce controlled coupling for convenience's sake. -``render_to_response`` -====================== +``render_to_response()`` +======================== ``django.shortcuts.render_to_response`` renders a given template with a given context dictionary and returns an ``HttpResponse`` object with that rendered text. -Example:: +Required arguments +------------------ + +``template`` + The full name of a template to use. + +Optional arguments +------------------ + +``context`` + A dictionary of values to add to the template context. By default, this + is an empty dictionary. If a value in the dictionary is callable, the + view will call it just before rendering the template. + +``mimetype`` + **New in Django development version:** The MIME type to use for the + resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` + setting. + +Example +------- + +The following example renders the template ``myapp/index.html`` with the +MIME type ``application/xhtml+xml``:: from django.shortcuts import render_to_response - r = render_to_response('myapp/template.html', {'foo': 'bar'}) + + def my_view(request): + # View code here... + return render_to_response('myapp/index.html', {"foo": "bar"}, + mimetype="application/xhtml+xml") This example is equivalent to:: from django.http import HttpResponse from django.template import Context, loader - t = loader.get_template('myapp/template.html') - c = Context({'foo': 'bar'}) - r = HttpResponse(t.render(c)) + + def my_view(request): + # View code here... + t = loader.get_template('myapp/template.html') + c = Context({'foo': 'bar'}) + r = HttpResponse(t.render(c), + mimetype="application/xhtml+xml") + +.. _an HttpResponse object: ../request_response/#httpresponse-objects ``get_object_or_404`` ===================== -``django.shortcuts.get_object_or_404`` calls ``get()`` on a given model +``django.shortcuts.get_object_or_404`` calls `get()`_ on a given model manager, but it raises ``django.http.Http404`` instead of the model's ``DoesNotExist`` exception. +Required arguments +------------------ + +``klass`` + A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the + object. + +``**kwargs`` + Lookup parameters, which should be in the format accepted by ``get()`` and + ``filter()``. + +Example +------- + +The following example gets the object with the primary key of 1 from +``MyModel``:: + + from django.shortcuts import get_object_or_404 + + def my_view(request): + my_object = get_object_or_404(MyModel, pk=1) + +This example is equivalent to:: + + from django.http import Http404 + + def my_view(request): + try: + my_object = MyModel.object.get(pk=1) + except MyModel.DoesNotExist: + raise Http404 + +Note: As with ``get()``, an ``AssertionError`` will be raised if more than +one object is found. + +.. _get(): ../db-api/#get-kwargs + ``get_list_or_404`` =================== -``django.shortcuts.get_list_or_404`` returns the result of ``filter()`` on a +``django.shortcuts.get_list_or_404`` returns the result of `filter()`_ on a given model manager, raising ``django.http.Http404`` if the resulting list is empty. + +Required arguments +------------------ + +``klass`` + A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the + object. + +``**kwargs`` + Lookup parameters, which should be in the format accepted by ``get()`` and + ``filter()``. + +Example +------- + +The following example gets all published objects from ``MyModel``:: + + from django.shortcuts import get_list_or_404 + + def my_view(request): + my_objects = get_list_or_404(MyModel, published=True) + +This example is equivalent to:: + + from django.http import Http404 + + def my_view(request): + my_objects = MyModels.object.filter(published=True) + if not my_objects: + raise Http404 + +.. _filter(): ../db-api/#filter-kwargs diff --git a/docs/templates.txt b/docs/templates.txt index 0c8cc79311..dbed0ba5c9 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -1135,12 +1135,15 @@ Returns a boolean of whether the value's length is the argument. linebreaks ~~~~~~~~~~ -Converts newlines into ``

`` and ``
`` tags. +Replaces line breaks in plain text with appropriate HTML; a single +newline becomes an HTML line break (``
``) and a new line +followed by a blank line becomes a paragraph break (``

``). linebreaksbr ~~~~~~~~~~~~ -Converts newlines into ``
`` tags. +Converts all newlines in a piece of plain text to HTML line breaks +(``
``). linenumbers ~~~~~~~~~~~ diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index 77b5b11103..2e18fd6130 100644 --- a/docs/tutorial01.txt +++ b/docs/tutorial01.txt @@ -41,6 +41,16 @@ From the command line, ``cd`` into a directory where you'd like to store your code, then run the command ``django-admin.py startproject mysite``. This will create a ``mysite`` directory in your current directory. +.. admonition:: Max OS X permissions + + If you're using Mac OS X, you may see the message "permission + denied" when you try to run ``django-admin.py startproject``. This + is because, on Unix-based systems like OS X, a file must be marked + as "exceutable" before it can be run as a program. To do this, open + Terminal.app and navigate (using the `cd` command) to the directory + where ``django-admin.py`` is installed, then run the command + ``chmod +x django-admin.py``. + .. note:: You'll need to avoid naming projects after built-in Python or Django -- cgit v1.3