chap07.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[
<!ENTITY BASEID "djangobook.chap07">
]>

<chapter lang="ru" id="&BASEID;">

  <title id="&BASEID;.title">
    Формы
  </title>

  <para>
    Перевод &copy; Попов Руслан &lt;ruslan.popov &bull; gmail&gt;
  </para>

  <para>
    HTML формы являются основой интерактивных веб-сайтов, от простой
    формы поиска Google и вездесущих форм для комментирования в блогах
    до сложных уникальных интерфейсов для ввода данных. Эта глава
    рассматривает возможности Django по обработке форм, проверки
    переданных значений. Здесь мы рассмотрим объекты
    <classname>HttpRequest</classname> и <classname>Form</classname>.
  </para>

  <section id="&BASEID;.get-data-from-request">

    <title id="&BASEID;.get-data-from-request.title">
      Получение данных из объекта запроса
    </title>

    <para>
      Мы впервые коснулись объектов <classname>HttpRequest</classname>
      в главе <quote><xref linkend="djangobook.chap03"
      endterm="djangobook.chap03.title"/></quote> при начальном
      изучении функций представления, но мы многого тогда не
      рассказали. Помните, каждая функция представления принимала
      объект <classname>HttpRequest</classname> в качестве первого
      аргумента, как в нашем представлении
      <function>hello()</function>:
      <screen>
	    <![CDATA[
from django.http import HttpResponse

def hello(request):
    return HttpResponse("Hello world")
        ]]>
      </screen>
    </para>

    <para>
      <classname>HttpRequest</classname> объекты, в нашем случае
      представленные переменной <varname>request</varname>, обладают
      рядом интересных атрибутов и методов, с которыми вам следует
      познакомиться, чтобы вы знали их возможности. Вы можете
      использовать данные атрибуты для получения информации о текущем
      запросе (т.е., о пользователе и браузере, который запросил
      текущую страницу вашего сайта) во время выполнения функции
      представления.
    </para>

    <section id="&BASEID;.get-data-from-request.url-info">

      <title id="&BASEID;.get-data-from-request.url-info.title">
        Информация об URL
      </title>

      <para>
        <classname>HttpRequest</classname> объекты содержат информацию
        о запрошенном URL:

        <table id="&BASEID;.tbl1" frame="all" pgwide="1">

          <title id="&BASEID;.tbl1.title">
            Информация об URL
          </title>

          <tgroup cols="3" align="left" colsep="1" rowsep="1">
            <colspec colname="c1" colwidth="4cm"/>
            <colspec colname="c2" colwidth="6cm"/>
            <colspec colname="c3" colwidth="4cm"/>

            <thead>
              <row>
                <entry>Атрибут/Метод</entry>
                <entry>Описание</entry>
                <entry>Пример</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry><token>request.path</token></entry>
                <entry>Полный путь, без домена, но с начальным слешом.</entry>
                <entry><token>/hello/</token></entry>
              </row>

              <row>
                <entry><token>request.get_host()</token></entry>
                <entry>Имя компьютера (т.е., <quote>домен</quote>).</entry>
                <entry><token>127.0.0.1:8000</token> или <token>www.example.com</token></entry>
              </row>

              <row>
                <entry><token>request.get_full_path()</token></entry>
                <entry>Равен <token>path</token>, но со строкой запроса (если она существует).</entry>
                <entry><token>/hello/?print=true</token></entry>
              </row>

              <row>
                <entry><token>request.is_secure()</token></entry>
                <entry><token>True</token> в случае использования HTTPS. Иначе <token>False</token>.</entry>
                <entry><token>True</token> или <token>False</token></entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </para>

      <para>
        Всегда используйте эти атрибуты/методы вместо прямого
        вписывания URL в ваши представления. Такой подход делает код
        более гибким и его можно будет повторно использовать в других
        местах. Простейший пример:
        <screen>
          <![CDATA[
# BAD!
def current_url_view_bad(request):
    return HttpResponse("Welcome to the page at /current/")

# GOOD
def current_url_view_good(request):
    return HttpResponse("Welcome to the page at %s" % request.path)
          ]]>
        </screen>
      </para>

    </section>

    <section id="&BASEID;.get-data-from-request.other-info">

      <title id="&BASEID;.get-data-from-request.other-info.title">
        Остальная информация о запросе
      </title>

      <para>
        Атрибут <token>request.META</token> является словарём, который
        содержит все доступные HTTP заголовки текущего запроса,
        включая IP адрес посетителя и информацию об его браузере
        (название и версию). Следует отметить, что полный список
        доступных заголовков зависит от того, какие заголовки были
        посланы браузером посетителя и какие заголовки были
        установлены веб-сервером. Перечислим несколько стандартных
        ключей этого словаря:

        <itemizedlist>
          <listitem>
            <para>
              <token>HTTP_REFERER</token> &mdash; ссылка на страницу с
              которой пришли на текущую, если такая существует.
            </para>
          </listitem>

          <listitem>
            <para>
              <token>HTTP_USER_AGENT</token> &mdash; идентификационная
              строка браузера. Обычно выглядит так:
              <token>"Mozilla/5.0 (X11; U; Linux i686; fr-FR;
              rv:1.8.1.17) Gecko/20080829 Firefox/2.0.0.17"</token>.
            </para>
          </listitem>

          <listitem>
            <para>
              <token>REMOTE_ADDR</token> &mdash; IP адрес
              пользователя, т.е., <token>"12.245.67.89"</token>. (Если
              запрос был передан через прокси, тогда адрес может быть
              передан в виде списка:
              <token>"12.245.67.89,23.45.78.90"</token>.)
            </para>
          </listitem>
        </itemizedlist>
      </para>

      <para>
        Следует отметить, что так как <token>request.META</token>
        является обычным словарём языка Python, вы получите исключение
        <classname>KeyError</classname>, если попытаетесь использовать
        несуществующий ключ. (Так как HTTP заголовки являются
        <emphasis>внешними</emphasis> данными &mdash; они передаются
        браузерами посетителей &mdash; им не стоит доверять, и вы
        должны всегда проектировать ваше приложение на грамотную
        обработку возникающих ошибок, если нужного заголовка нет или
        он пустой.) Следует использовать блок
        <token>try/except</token> или метод <function>get()</function>
        для обработки случая с неопределёнными ключами:
        <screen>
          <![CDATA[
# BAD!
def ua_display_bad(request):
    ua = request.META['HTTP_USER_AGENT']  # Might raise KeyError!
    return HttpResponse("Your browser is %s" % ua)

# GOOD (VERSION 1)
def ua_display_good1(request):
    try:
        ua = request.META['HTTP_USER_AGENT']
    except KeyError:
        ua = 'unknown'
    return HttpResponse("Your browser is %s" % ua)

# GOOD (VERSION 2)
def ua_display_good2(request):
    ua = request.META.get('HTTP_USER_AGENT', 'unknown')
    return HttpResponse("Your browser is %s" % ua)
          ]]>
        </screen>
      </para>

      <para>
        Мы рекомендуем вам написать небольшое представление, которое
        будет отображать все данные из <token>request.META</token>,
        так вы сможете узнать что там есть. Вот так может выглядеть
        ваше представление:
        <screen>
          <![CDATA[
def display_meta(request):
    values = request.META.items()
    values.sort()
    html = []
    for k, v in values:
        html.append('<tr><td>%s</td><td>%s</td></tr>' % (k, v))
    return HttpResponse('<table>%s</table>' % '\n'.join(html))
          ]]>
        </screen>
      </para>

      <para>
        В качестве упражнения, вы можете преобразовать данный код для
        использования возможностей шаблонной системы Django, а не
        использовать <quote>сырой</quote> HTML.
      </para>

    </section>

    <section id="&BASEID;.get-data-from-request.submit-info">

      <title id="&BASEID;.get-data-from-request.submit-info.title">
        Информация о переданных данных
      </title>

      <para>
        Кроме основных метаданных о запросе,
        <classname>HttpRequest</classname> имеет два атрибута, которые
        содержат информацию переданную пользователем:
        <token>request.GET</token> и <token>request.POST</token>. Оба
        этих атрибута являются словарными объектами, которые
        предоставляют доступ к данным <token>GET</token> и
        <token>POST</token>.
      </para>

      <para>
        <note>
          <title>
            Словарные объекты
          </title>

          <para>
            Когда мы говорим, что <token>request.GET</token> и
            <token>request.POST</token> являются
            <quote>словарными</quote> объектами, мы подразумеваем, что
            они ведут себя как обычные словари языка Python, но
            технически не являются словарями. Например,
            <token>request.GET</token> и <token>request.POST</token>
            обладают методами <function>get()</function>,
            <function>keys()</function> и
            <function>values()</function> и вы можете выполнять
            итерацию по их ключам, так <token>for key in
            request.GET</token>.
          </para>

          <para>
            Так в чём разница? В том, что эти объекты обладают
            дополнительными методами, которых нет у обычных
            словарей. Мы ещё остановимся на этом.
          </para>

          <para>
            Вы можете встретиться с подобным термином &mdash;
            <quote>файловые объекты</quote> &mdash; такие объекты
            обладают несколькими основными методами, подобными
            <function>read()</function>, которые позволяют работать с
            ними почти как с настоящими файлами.
          </para>
        </note>
      </para>

      <para>
        POST данные обычно получают из HTML <![CDATA[<form>]]>, а GET
        данные могут приходить как от форм, так и из URL.
      </para>

    </section>

  </section>

  <section id="&BASEID;.example-simple-form">

    <title id="&BASEID;.example-simple-form.title">
      Пример обработки простой формы
    </title>

    <para>
      Продолжая наш пример с книгами, авторами и издателями, давайте
      создадим простое представление, которое позволит пользователям
      производить поиск по нашей базе книг по их названию.
    </para>

    <para>
      Обычно, разработка форм подразумевает два шага: пользовательский
      интерфейс в HTML и код сопровождающего представления, которое
      обрабатывает переданные данные. Первый шаг несложен. Давайте
      создадим представление, которое отображает поисковую форму:
      <screen>
        <![CDATA[
from django.shortcuts import render_to_response

def search_form(request):
    return render_to_response('search_form.html')
        ]]>
      </screen>
    </para>

    <para>
      Как мы уже говорили в главе <quote><xref
      linkend="djangobook.chap03"
      endterm="djangobook.chap03.title"/></quote>, представление может
      располагаться где угодно, пока оно находится через
      PYTHONPATH. Для порядка разместим его в
      <filename>books/views.py</filename>.
    </para>

    <para>
      Соответствующий шаблон, <filename>search_form.html</filename>,
      может выглядеть так:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Search</title>
</head>
<body>
    <form action="/search/" method="get">
        <input type="text" name="q">
        <input type="submit" value="Search">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Схема URL в <filename>urls.py</filename> может выглядеть так:
      <screen>
        <![CDATA[
from mysite.books import views

urlpatterns = patterns('',
    # ...
    (r'^search-form/$', views.search_form),
    # ...
)
        ]]>
      </screen>
    </para>

    <para>
      (Следует отметить, что мы импортируем модуль
      <token>views</token> напрямую, а не указываем <token>from
      mysite.views import search_form</token>, поскольку первый метод
      более краток. Мы рассмотрим этот механизм импортирования более
      подробно в главе <quote><xref linkend="djangobook.chap08"
      endterm="djangobook.chap08.title"/></quote>.)
    </para>

    <para>
      Если вы запустите <token>runserver</token> и посетите <ulink
      url="http://127.0.0.1:8000/search-form/"/>, вы увидете поисковый
      интерфейс. Очень простой.
    </para>

    <para>
      Попробуйте отправить форму, несмотря на то, что вы получите
      ошибку 404. Форма указывает на URL <token>/search/</token>,
      обработчик которого ещё не был реализован. Давайте это исправим
      с помощью второй функции представления:
      <screen>
        <![CDATA[
# urls.py

urlpatterns = patterns('',
    # ...
    (r'^search-form/$', views.search_form),
    (r'^search/$', views.search),
    # ...
)

# views.py

def search(request):
    if 'q' in request.GET:
        message = 'You searched for: %r' % request.GET['q']
    else:
        message = 'You submitted an empty form.'
    return HttpResponse(message)
        ]]>
      </screen>
    </para>

    <para>
      На данный момент, этот код просто отображает пользовательский
      ввод, таким образом мы можем удостовериться, что данные были
      переданы корректно и вы можете увидеть как работает поисковая
      система. Если кратко:

      <orderedlist>
        <listitem>
          <para>
            Тег <![CDATA[<form>]]> определяет переменную
            <varname>q</varname>. При отправке формы, значение этой
            переменной посылается через <token>GET</token>
            (<token>method="get"</token>) на URL
            <token>/search/</token>.
          </para>
        </listitem>

        <listitem>
          <para>
            Представление обрабатывающее URL <token>/search/</token>
            (<function>search()</function>) получает доступ к значению
            переменной <varname>q</varname> через
            <token>request.GET</token>.
          </para>
        </listitem>
      </orderedlist>
    </para>

    <para>
      Обратите внимание, мы явно проверяем существование переменной
      <varname>q</varname> в <token>request.GET</token>. Как мы
      говорили ранее, вы должны проявлять должное недоверие к данным,
      переданным пользователями. Если бы мы не сделали такую проверку,
      то любая передача пустой формы приводила бы к вызову исключения
      <classname>KeyError</classname> в представлении:
      <screen>
        <![CDATA[
# BAD!
def bad_search(request):
    # The following line will raise KeyError if 'q' hasn't
    # been submitted!
    message = 'You searched for: %r' % request.GET['q']
    return HttpResponse(message)
        ]]>
      </screen>
    </para>

    <para>
      <note>
        <title>
          Параметры строки запроса
        </title>

        <para>
          Так как <token>GET</token> данные передаются в строке
          запроса (т.е., <token>/search/?q=django</token>), вы можете
          использовать <token>request.GET</token> для доступа к
          переменным, переданным в этой строке. В главе <quote><xref
          linkend="djangobook.chap03"
          endterm="djangobook.chap03.title"/></quote> при ознакомлении
          со схемой URL, мы сравнивали подход Django к формированию
          URL с традиционными PHP/Java URL, например,
          <token>/time/plus?hours=3</token> и обещали вернуться к
          этому в этой главе. Теперь вы знаете как получать доступ к
          параметрам строки запроса в ваших представлениях &mdash;
          просто используйте <token>request.GET</token>.
        </para>
      </note>
    </para>

    <para>
      <token>POST</token> данные обрабатываются аналогично
      <token>GET</token> &mdash; только используйте
      <token>request.POST</token> вместо
      <token>request.GET</token>. Какая разница существует между
      <token>GET</token> и <token>POST</token>? Используйте
      <token>GET</token> в случаях, когда форма используется для
      <quote>получения</quote> данных<footnote><para>Старайтесь
      использовать в формах <token>POST</token>
      (прим. переводчика).</para></footnote>. Используйте
      <token>POST</token> при обработке форм, которая имеет побочный
      эффект &mdash; <emphasis>изменение</emphasis> данных или при
      отправке электронных сообщений, в общем для всего, что лежит вне
      задачи <emphasis>простого отображения</emphasis> данных. В нашем
      примере мы используем <token>GET</token>, так как запрос не
      изменяет данные на сервере. (Обратитесь к <ulink
      url="http://www.w3.org/2001/tag/doc/whenToUseGet.html"/>, если
      вы желаете узнать больше о <token>GET</token> и
      <token>POST</token>).
    </para>

    <para>
      После того как мы проверили переданные данные, давайте
      используем их для поиска по базе данных (и снова, в
      <filename>views.py</filename>):
      <screen>
        <![CDATA[
from django.http import HttpResponse
from django.shortcuts import render_to_response
from mysite.books.models import Book

def search(request):
    if 'q' in request.GET and request.GET['q']:
        q = request.GET['q']
        books = Book.objects.filter(title__icontains=q)
        return render_to_response('search_results.html',
            {'books': books, 'query': q})
    else:
        return HttpResponse('Please submit a search term.')
        ]]>
      </screen>
    </para>

    <para>
      Остановимся и опишем, что мы сделали:

      <itemizedlist>
        <listitem>
          <para>
            Помимо проверки существования <varname>q</varname> в
            <token>request.GET</token>, мы удостоверились, что
            <token>request.GET['q']</token> не содержит пустую строку,
            перед её передачей в базу данных.
          </para>
        </listitem>

        <listitem>
          <para>
            Мы используем
            <token>Book.objects.filter(title__icontains=q)</token> для
            поиска по нашей таблице книг, разыскивая книги у которых
            заголовок содержит переданную строку. Суффикс
            <token>icontains</token> является модификатором (это было
            рассмотрено в главе <quote><xref
            linkend="djangobook.chap05"
            endterm="djangobook.chap05.title"/></quote> и в Приложении
            B FIXME) и данный оператор может быть приблизительно
            переведён в <quote>Получить все книги, названия которых
            содержат <varname>q</varname>, не принимая во внимание
            регистр букв.</quote>
          </para>

          <para>
            Это очень простой способ реализации поиска книг. Мы не
            рекомендуем использовать простой <token>icontains</token>
            запрос на больших реальных базах данных, так как он может
            быть очень медленным. (В реальном мире, вам потребуется
            собственная поисковая система. Поищите в Интернет
            <emphasis>полнотекстовую поисковую систему с открытым
            кодом</emphasis>, чтобы получить информацию о их
            возможностях.)
          </para>
        </listitem>

        <listitem>
          <para>
            Мы передаём <varname>books</varname>, список объектов
            <classname>Book</classname>, в шаблон. Шаблонный код в
            файле <filename>search_results.html</filename> может
            выглядеть так:
            <screen>
              <![CDATA[
<p>You searched for: <strong>{{ query }}</strong></p>

{% if books %}
    <p>Found {{ books|length }} book{{ books|pluralize }}.</p>
    <ul>
        {% for book in books %}
        <li>{{ book.title }}</li>
        {% endfor %}
    </ul>
{% else %}
    <p>No books matched your search criteria.</p>
{% endif %}
              ]]>
            </screen>
          </para>
        </listitem>
      </itemizedlist>
    </para>

  </section>

  <section id="&BASEID;.example-improved-form">

    <title id="&BASEID;.example-improved-form.title">
      Усовершенствование примера обработки простой формы
    </title>

    <para>
      Как и в предыдущих главах, мы показали вам самый простой
      пример. Теперь рассмотрим некоторые проблемы и покажем как их
      можно решить.
    </para>

    <para>
      Во-первых, наша обработка пустой строки в
      <function>search()</function> слишком примитивна &mdash; мы
      просто отображаем сообщение <quote>Please submit a search
      term.</quote>, требуя от пользователя воспользоваться кнопкой
      <guibutton>Назад</guibutton>. Это неприятно и непрофессионально,
      и если вы попробуете сделать такое в реальном приложении, вас
      отлучат от Django.
    </para>

    <para>
      Гораздо лучше будет отобразить форму снова, вывести сообщение об
      ошибке над ней &mdash; пользователь сможет немедленно исправить
      её и сразу отправить данные. Простейшим способом сделать это
      является повторная обработка шаблона, вот так:
      <screen>
        <![CDATA[
from django.http import HttpResponse
from django.shortcuts import render_to_response
from mysite.books.models import Book

def search_form(request):
    return render_to_response('search_form.html')

def search(request):
    if 'q' in request.GET and request.GET['q']:
        q = request.GET['q']
        books = Book.objects.filter(title__icontains=q)
        return render_to_response('search_results.html',
            {'books': books, 'query': q})
    else:
        return render_to_response('search_form.html', {'error': True})
        ]]>
      </screen>
    </para>

    <para>
      (Отметьте, что мы включили сюда
      <function>search_form()</function>, чтобы вы могли видеть оба
      представления вместе.)
    </para>

    <para>
      Итак, мы доработали <function>search()</function> для повторного
      отображения шаблона <filename>search_form.html</filename>, если
      запрос будет пустым. А раз нам необходимо отображать сообщение
      об ошибке в шаблоне, мы передали шаблонную переменную. Теперь мы
      может отредактировать <filename>search_form.html</filename>,
      добавив проверку наличия переменной <varname>error</varname>:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Search</title>
</head>
<body>
    {% if error %}
        <p style="color: red;">Please submit a search term.</p>
    {% endif %}
    <form action="/search/" method="get">
        <input type="text" name="q">
        <input type="submit" value="Search">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Мы по-прежнему можем использовать этот шаблон из нашего
      оригинального представления, <function>search_form()</function>,
      так как оно не передаёт <varname>error</varname> в шаблон
      &mdash; следовательно, сообщение об ошибке не будет
      отображаться.
    </para>

    <para>
      Учитывая сделанные изменения, появляется вопрос: действительно
      ли мы нуждаемся в представлении
      <function>search_form()</function>? Действительно, запрос к URL
      <token>/search/</token> (без параметров <token>GET</token>)
      отобразит пустую форму (но с ошибкой). Мы можем удалить
      представление <function>search_form()</function> вместе с
      соответствующей строкой в схеме URL, останется только изменить
      <function>search()</function> так, чтобы оно не выдавало
      сообщение об ошибке, если кто-то зайдёт по этому URL без
      указания <token>GET</token> параметров:
      <screen>
        <![CDATA[
def search(request):
    error = False
    if 'q' in request.GET:
        q = request.GET['q']
        if not q:
            error = True
        else:
            books = Book.objects.filter(title__icontains=q)
            return render_to_response('search_results.html',
                {'books': books, 'query': q})
    return render_to_response('search_form.html',
        {'error': error})
        ]]>
      </screen>
    </para>

    <para>
      Теперь, если пользователь посетит <token>/search/</token> без
      указания <token>GET</token> параметров, он увидит поисковую
      форму без сообщения об ошибке. Если пользователь передаст форму
      с пустым значением <varname>q</varname>, он увидит форму
      <emphasis>c сообщением об ошибке</emphasis>. И, наконец, если
      пользователь передаст форму с непустым значением
      <varname>q</varname>, он увидит результаты выполнения поискового
      запроса.
    </para>

    <para>
      Мы можем сделать финальное улучшение этого приложения, удалим
      избыточность. После свёртывания двух представлений в единое
      стало необязательным указывать URL, по которому надо отправлять
      данные формы. Вместо строки:
      <screen>
        <![CDATA[
<form action="/search/" method="get">
        ]]>
      </screen>
      можно писать так:
      <screen>
        <![CDATA[
<form action="" method="get">
        ]]>
      </screen>
    </para>

    <para>
      Параметр <token>action=""</token> означает <quote>Отправь форму
      по URL текущей страницы.</quote> Учитывая это изменение, больше
      не требуется изменять <token>action</token> при переходе формы
      на другой URL.
    </para>

  </section>

  <section id="&BASEID;.simple-validation">

    <title id="&BASEID;.simple-validation.title">
      Простая проверка данных
    </title>

    <para>
      Наш пример с поиском всё ещё остаётся достаточно простым,
      особенно с точки зрения проверки передаваемых данных. Мы просто
      проверяем наличие информации в запросе. Множество HTML форм
      включают в себя значительно более сложные проверки. Все мы
      видели такие сообщения об ошибках на сайтах:

      <itemizedlist>
        <listitem>
          <para>
            <quote>Пожалуйста, введите верный адрес электронной
            почты. 'foo' не является адресом электронной
            почты.</quote>
          </para>
        </listitem>

        <listitem>
          <para>
            <quote>Пожалуйста, введите верный шестизначный код
            почтового отделения. '123' не является почтовым
            кодом.</quote>
          </para>
        </listitem>

        <listitem>
          <para>
            <quote>Пожалуйста, введите верную дату в формате
            <token>DD-MM-YYYY</token>.</quote>
          </para>
        </listitem>

        <listitem>
          <para>
            <quote>Пожалуйста, введите пароль, который содержит как
            минимум 8 символов и содержит хотя бы одну цифру.</quote>
          </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      <note>
        <title>
          Об использовании JavaScript для проверки данных
        </title>

        <para>
          Хотя мы не рассказываем об этом, но вы можете использовать
          JavaScript для проверки данных на стороне клиента, прямо в
          браузере. Но помните, даже если вы это делаете, вы
          <emphasis>обязаны</emphasis> сделать проверку и на стороне
          сервера. Некоторые пользователи не включают JavaScript, а
          <quote>злобные хакеры</quote> могут передавать
          самостоятельно сформированные данные, которые не доступны
          JavaScript коду.
        </para>

        <para>
          И вы ничего не можете с этим поделать, остаётся только
          <emphasis>всегда</emphasis> проверять данные, переданные
          пользователями, на стороне сервера (т.е., в ваших
          представлениях). Проверку с помощью JavaScript следует
          рассматривать как дополнительную удобную функциональность
          сайта, но не как замену основного механизма проверки.
        </para>
      </note>
    </para>

    <para>
      Давайте доработаем наше представление
      <function>search()</function> так, чтобы оно проверяло
      переданную строку на превышение её длины в 20
      символов. (Предположим для этого примера, что передача более
      длинной строки значительно замедлит скорость выполнения поиска.)
      Как мы можем это сделать? Самым простым способом будет внедрение
      логики прямо в представление, вот так:
      <screen>
        <![CDATA[
def search(request):
    error = False
    if 'q' in request.GET:
        q = request.GET['q']
        if not q:
            error = True
        elif len(q) > 20:
            error = True
        else:
            books = Book.objects.filter(title__icontains=q)
            return render_to_response('search_results.html',
                {'books': books, 'query': q})
    return render_to_response('search_form.html',
        {'error': error})
        ]]>
      </screen>
    </para>

    <para>
      Теперь, при попытке отослать запрос с длиной строки более 20
      символов, вы получите сообщение об ошибке. Но это сообщение в
      <filename>search_form.html</filename> пока говорит <quote>Please
      submit a search term.</quote> и нам потребуется изменить его
      так, чтобы оно учитывало оба случая:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Search</title>
</head>
<body>
    {% if error %}
        <p style="color: red;">Please submit a search term 20 characters or shorter.</p>
    {% endif %}
    <form action="/search/" method="get">
        <input type="text" name="q">
        <input type="submit" value="Search">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Есть что-то некрасивое в этом. Наше <quote>универсальное</quote>
      сообщение об ошибке может запутать. Как может сообщение для
      пустого запроса упоминать об ограничении размера строки запроса
      20-ю символами? Сообщение об ошибке должно быть точное.
    </para>

    <para>
      Проблема заключается в том, что мы используем обычное булево
      значение для <varname>error</varname>, а надо использовать
      <emphasis>список</emphasis> строк с сообщениями об ошибке. Вот
      так мы можем изменить код:
      <screen>
        <![CDATA[
def search(request):
    errors = []
    if 'q' in request.GET:
        q = request.GET['q']
        if not q:
            errors.append('Enter a search term.')
        elif len(q) > 20:
            errors.append('Please enter at most 20 characters.')
        else:
            books = Book.objects.filter(title__icontains=q)
            return render_to_response('search_results.html',
                {'books': books, 'query': q})
    return render_to_response('search_form.html',
        {'errors': errors})
        ]]>
      </screen>
    </para>

    <para>
      Затем, надо сделать небольшое исправление в
      <filename>search_form.html</filename> для того, чтобы учесть
      изменения в коде &mdash; в шаблон передаётся список
      <varname>error</varname>, а не булево значение:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Search</title>
</head>
<body>
    {% if errors %}
        <ul>
            {% for error in errors %}
            <li>{{ error }}</li>
            {% endfor %}
        </ul>
    {% endif %}
    <form action="/search/" method="get">
        <input type="text" name="q">
        <input type="submit" value="Search">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

  </section>

  <section id="&BASEID;.making-contact-form">

    <title id="&BASEID;.making-contact-form.title">
      Создание формы для контактной информации
    </title>

    <para>
      Несмотря на то, что мы несколько раз изменяли форму поиска по
      книгам и значительно её улучшили, она осталась достаточно
      простой: просто одно поле, <varname>q</varname>. Из-за её
      простоты мы даже не воспользовались библиотекой форм
      Django. Более сложные формы потребуют более сложную обработку
      &mdash; сделаем что-нибудь посложнее: форму для передачи
      контактной информации.
    </para>

    <para>
      Это будет форма, которая позволит пользователям отправлять
      отклик, с необязательным указанием своего адреса электронной
      почты. После передачи данных формы и их проверки, мы
      автоматически отправим сообщение по электронной почте
      сотрудникам сайта.
    </para>

    <para>
      Начнём с шаблона, <filename>contact_form.html</filename>:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Contact us</title>
</head>
<body>
    <h1>Contact us</h1>

    {% if errors %}
        <ul>
            {% for error in errors %}
            <li>{{ error }}</li>
            {% endfor %}
        </ul>
    {% endif %}

    <form action="/contact/" method="post">{% csrf_token %}
        <p>Subject: <input type="text" name="subject"></p>
        <p>Your e-mail (optional): <input type="text" name="email"></p>
        <p>Message: <textarea name="message" rows="10" cols="50"></textarea></p>
        <input type="submit" value="Submit">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Мы определили три поля: заголовок, адрес электронной почты и
      сообщение. Второе поле необязательное. Следует отметить, что мы
      используем <token>method="post"</token>, так как форма имеет
      побочный эффект &mdash; она отправляет сообщение. Также мы
      скопировали код, отвечающий за отображение ошибки из нашего
      предыдущего шаблона
      <filename>search_form.html</filename>.
      
      <note>
        <title>
          Формы и защита от Cross Site Request Forgery
        </title>

        <para>
          Использовать <ulink url="https://docs.djangoproject.com/en/1.3/ref/contrib/csrf/">защиту от Cross Site Request Forgeries</ulink>
          в Django очень просто. Оправляя форму, используя метод <token>POST</token> при включеной защите от
          <token>CSRF</token>, добвляйте в форму тег <token>csrf_token</token> как в примере выше.
          Однако, так как защита от <token>CSRF</token> непосредственно не связана с формами
          в шаблонах, этот тег опущен в последующих примерах.
        </para>
      </note>
    </para>

    <para>
      Если продолжать методику, начатую при работе с нашим
      представлением <function>search()</function>, первой наивной
      версией нашего представления <function>contact()</function>
      будет:
      <screen>
        <![CDATA[
from django.core.mail import send_mail
from django.http import HttpResponseRedirect
from django.shortcuts import render_to_response

def contact(request):
    errors = []
    if request.method == 'POST':
        if not request.POST.get('subject', ''):
            errors.append('Enter a subject.')
        if not request.POST.get('message', ''):
            errors.append('Enter a message.')
        if request.POST.get('email') and '@' not in request.POST['email']:
            errors.append('Enter a valid e-mail address.')
        if not errors:
            send_mail(
                request.POST['subject'],
                request.POST['message'],
                request.POST.get('email', 'noreply@example.com'),
                ['siteowner@example.com'],
            )
            return HttpResponseRedirect('/contact/thanks/')
    return render_to_response('contact_form.html',
        {'errors': errors})
        ]]>
      </screen>
    </para>

    <para>
      (Если вы сразу проверяете наш код в действии, вы можете
      заинтересоваться зачем размещать это представление в файле
      <filename>books/views.py</filename>. Оно предназначено для
      работы с книжным приложением, где же ему ещё находиться? Но в
      общем, всё зависит от вас. Django нет разницы где размещён код,
      если она может найти его по связи в URL. Мы предпочитаем
      создавать отдельный каталог, <filename>contact</filename> на
      уровне каталога <filename>books</filename> Он будет содержать
      пустой <filename>__init__.py</filename> и
      <filename>views.py</filename>.)
    </para>

    <para>
      Рассмотрим отличия:

      <itemizedlist>
        <listitem>
          <para>
            Мы проверяем, что <token>request.method</token> равен
            <token>'POST'</token>. Это условие будет верным только в
            случае отправки формы, иначе считаем, что происходит
            простое отображение формы. (В последнем случае,
            <token>request.method</token> будет установлен в
            <token>'GET'</token>, так как для отображения формы
            браузеры используют <token>GET</token>, а не
            <token>POST</token>.) Такой подход обеспечивает отличный
            способ изоляции случая <quote>отображения формы</quote> от
            <quote>обработки формы</quote>.
          </para>
        </listitem>

        <listitem>
          <para>
            Вместо использования <token>request.GET</token> мы
            применяем <token>request.POST</token> для доступа к
            переданным данным. Это необходимо, так как
            <![CDATA[<form>]]> в
            <filename>contact_form.html</filename> использует
            <token>method="post"</token>. Если данное представление
            вызывается через <token>POST</token>, значит
            <token>request.GET</token> будет пустым.
          </para>
        </listitem>

        <listitem>
          <para>
            В этот раз у нас есть <emphasis>два</emphasis>
            обязательных поля, <token>subject</token> и
            <token>message</token>, нам следует проверять оба. Следует
            отметить, что для получения значения из
            <token>POST</token> мы используем метод
            <function>get()</function> и подставляем пустую строку в
            качестве значения по умолчанию. Это хороший, краткий
            способ обработки двух проблем: отсутствие ключа и
            отсутствие данных.
          </para>
        </listitem>

        <listitem>
          <para>
            Несмотря на то, что поле <token>email</token> является
            необязательным, мы всё равно проверяем его, правда только
            при наличии в нём данных. Наша проверка достаточно простая
            &mdash; мы проверяем наличие в строке символа
            <token>@</token>. В реальной ситуации вам потребуется
            более устойчивая проверка (и Django предоставляет её, мы
            очень скоро её покажем).
          </para>
        </listitem>

        <listitem>
          <para>
            Мы используем функцию <function>send_mail</function> из
            модуля <token>django.core.mail</token> для отправки
            сообщения по электронной почте. Эта функция принимает
            четыре обязательных аргумента: тема сообщения, тело
            сообщения, адрес <quote>от</quote> и список адресов
            получателей. Функция <function>send_mail</function>
            является удобной оболочкой над классом Django
            <classname>EmailMessage</classname>, который предоставляет
            дополнительные возможности, например, вложение файлов,
            multipart сообщения и полный контроль над заголовками
            сообщения.
          </para>

          <para>
            Следует отметить, что для отправки сообщения с помощью
            <function>send_mail</function> ваш сервер должен быть
            соответственно сконфигурирован и Django следует указать на
            сервер исходящей почты. Обратитесь к
            <ulink url="http://docs.djangoproject.com/en/dev/topics/email/"/>
            для подробностей.
          </para>
        </listitem>

        <listitem>
          <para>
            После отправки сообщения мы перенаправляем пользователя на
            страницу с сообщением об успешном выполнении операции,
            возвращая объект
            <classname>HttpResponseRedirect</classname>. Мы оставляем
            реализацию такой страницы вам в качестве домашнего задания
            (это просто представление/привязка URL/шаблон), но нам
            следует объяснить причину, почему мы инициировали
            перенаправление вместо, например, простого вызова
            <function>render_to_response()</function> прямо здесь.
          </para>

          <para>
            Причина: если пользователь нажмёт на кнопку
            <guibutton>Обновить</guibutton> на странице, которая была
            загружена через метод <token>POST</token>, это приведёт к
            повторному выполнению запроса. В большинстве случаев это
            может привести к нежелаемому результату, например, к
            повторной передаче данных в базу данных или к повторной
            отправке сообщения по электронной почте. Если же
            пользователь был перенаправлен на другую страницу, тогда
            такого точно не произойдёт.
          </para>

          <para>
            Вы всегда должны осуществлять перенаправление после
            успешной обработки <token>POST</token> запроса.
          </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      Данное представление работает, но представьте, что вам придётся
      обработать форму с дюжиной полей. Вы действительно желаете
      самостоятельно расписывать проверки для каждого поля?
    </para>

    <para>
      Следующей проблемой является <emphasis>повторное отображение
      формы</emphasis>. В случае возникновения ошибок при проверке
      полей, лучше всего будет отобразить форму повторно,
      <emphasis>внеся</emphasis> в поля переданные данные, так
      пользователь сможет увидеть, что именно он сделал неправильно (и
      также ему не потребуется вводить эти данные повторно). Мы
      <emphasis>можем</emphasis> вручную передать <token>POST</token>
      данные обратно в шаблон, но нам потребуется отредактировать
      каждое HTML поле для вставки соответствующего значения на
      соответствующее место.
    </para>

    <para>
      <token>views.py</token>:
      <screen>
        <![CDATA[
def contact(request):
    errors = []
    if request.method == 'POST':
        if not request.POST.get('subject', ''):
            errors.append('Enter a subject.')
        if not request.POST.get('message', ''):
            errors.append('Enter a message.')
        if request.POST.get('email') and '@' not in request.POST['email']:
            errors.append('Enter a valid e-mail address.')
        if not errors:
            send_mail(
                request.POST['subject'],
                request.POST['message'],
                request.POST.get('email', 'noreply@example.com'),
                ['siteowner@example.com'],
            )
            return HttpResponseRedirect('/contact/thanks/')
    return render_to_response('contact_form.html', {
        'errors': errors,
        'subject': request.POST.get('subject', ''),
        'message': request.POST.get('message', ''),
        'email': request.POST.get('email', ''),
    })
        ]]>
      </screen>
    </para>

    <para>
      <token>contact_form.html</token>:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Contact us</title>
</head>
<body>
    <h1>Contact us</h1>

    {% if errors %}
        <ul>
            {% for error in errors %}
            <li>{{ error }}</li>
            {% endfor %}
        </ul>
    {% endif %}

    <form action="/contact/" method="post">
        <p>Subject: <input type="text" name="subject" value="{{ subject }}"></p>
        <p>Your e-mail (optional): <input type="text" name="email" value="{{ email }}"></p>
        <p>Message: <textarea name="message" rows="10" cols="50">**{{ message }}**</textarea></p>
        <input type="submit" value="Submit">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Этот подход очень трудоёмкий и привносит множество возможностей
      для ошибки. Мы надеемся, что вы начали искать возможность
      воспользоваться некой высокоуровневой библиотекой, которая будет
      выполнять такие формо-проверочные задачи.
    </para>

  </section>

  <section id="&BASEID;.first-form-class">

    <title id="&BASEID;.first-form-class.title">
      Ваш первый класс формы
    </title>

    <para>
      Django поставляется с библиотекой для работы с формами, она
      находится в модуле <token>django.forms</token> и может решать
      множество задач, которые мы рассмотрим в этой главе &mdash; от
      отображения форм до проверки полей. Давайте переработаем наше
      приложение с контактной формой, используя эту библиотеку.
    </para>

    <para>
      <note>
        <title>
          Библиотека <token>newforms</token>
        </title>

        <para>
          Общаясь в Django сообществе, вы могли услышать о
          <token>django.newforms</token>. Так раньше называлась
          стандартная библиотека <token>django.forms</token> &mdash;
          эта библиотека рассматривается в данной главе.
        </para>

        <para>
          Причина такого переименования историческая. Первый релиз
          Django поставлялся со сложной, запутанной библиотекой для
          работы с формами &mdash; <token>django.forms</token>. Она
          была полностью переписана и новая версия имела имя
          <token>django.newforms</token>, люди могли использовать как
          одну, так и другую библиотеки. После выхода Django 1.0
          старая библиотека была убрана, а
          <token>django.newforms</token> стала
          <token>django.forms</token>.
        </para>
      </note>
    </para>

    <para>
      Основным способом использования библиотеки является определения
      класса <classname>Form</classname> для каждого тега
      <![CDATA[<form>]]> в ваших шаблонах. В нашем случае, у нас есть
      только один такой тег, следовательно и класс нам надо создать
      только один. Этот класс может располагаться в любой части кода,
      даже в файле <filename>views.py</filename>, но, учитывая
      соглашения Django сообщества, код класса следует располагать в
      файле <filename>forms.py</filename>. Создайте этот файл рядом с
      <filename>views.py</filename> и впишите следующее:
      <screen>
        <![CDATA[
from django import forms

class ContactForm(forms.Form):
    subject = forms.CharField()
    email = forms.EmailField(required=False)
    message = forms.CharField()
        ]]>
      </screen>
    </para>

    <para>
      Синтаксис похож на синтаксис описания модели. Каждое поле формы
      представлено потомками класса <classname>Field</classname>
      &mdash; в нашем случае используются
      <classname>CharField</classname> и
      <classname>EmailField</classname> &mdash; в виде атрибутов
      класса <classname>Form</classname>. Каждое поле по умолчанию
      является обязательным, таким образом, чтобы отменить это
      поведение у поля <token>email</token>, мы используем атрибут
      <token>required=False</token>.
    </para>

    <para>
      Давайте перейдём в интерактивный интерпретатор Python и
      посмотрим, что этот класс может делать. Во-первых, он может
      отображать себя в виде HTML:
      <screen>
        <![CDATA[
>>> from contact.forms import ContactForm
>>> f = ContactForm()
>>> print f
<tr><th><label for="id_subject">Subject:</label></th><td><input type="text" name="subject" id="id_subject" /></td></tr>
<tr><th><label for="id_email">Email:</label></th><td><input type="text" name="email" id="id_email" /></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
        ]]>
      </screen>
    </para>

    <para>
      Django добавляет метку для каждого поля с помощью тега
      <![CDATA[<label>]]>. Идея состоит в том, чтобы сделать
      стандартное поведение наиболее оптимальным.
    </para>

    <para>
      По умолчанию форма выводится в виде содержимого таблицы, но есть
      несколько встроенных опций:
      <screen>
        <![CDATA[
>>> print f.as_ul()
<li><label for="id_subject">Subject:</label> <input type="text" name="subject" id="id_subject" /></li>
<li><label for="id_email">Email:</label> <input type="text" name="email" id="id_email" /></li>
<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>
>>> print f.as_p()
<p><label for="id_subject">Subject:</label> <input type="text" name="subject" id="id_subject" /></p>
<p><label for="id_email">Email:</label> <input type="text" name="email" id="id_email" /></p>
<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>
        ]]>
      </screen>
    </para>

    <para>
      Следует отметить, что открывающие и закрывающие теги
      <![CDATA[<table>]]>, <![CDATA[<ul>]]> и <![CDATA[<form>]]> не
      указываются, значит вы можете сами добавить любую
      дополнительную запись при необходимости.
    </para>

    <para>
      Эти методы являются простыми сокращениями для общей задачи
      <quote>отображения всей формы</quote>. Вы можете также
      отобразить HTML для конкретного поля формы:
      <screen>
        <![CDATA[
>>> print f['subject']
<input type="text" name="subject" id="id_subject" />
>>> print f['message']
<input type="text" name="message" id="id_message" />
        ]]>
      </screen>
    </para>

    <para>
      Во-вторых, объекты <classname>Form</classname> могут проверять
      пользовательские данные. Для этого, создайте новый объект
      <classname>Form</classname> и передайте ему словарь с данными,
      который соответствует именам полей формы:
      <screen>
        <![CDATA[
>>> f = ContactForm({'subject': 'Hello',
                     'email': 'adrian@example.com',
		     'message': 'Nice site!'})
        ]]>
      </screen>
    </para>

    <para>
      Теперь можно проверить каждому ли полю назначено значение:
      <screen>
        <![CDATA[
>>> f.is_bound
True
        ]]>
      </screen>
    </para>

    <para>
      Вызывайте метод <function>is_valid()</function> для
      <classname>Form</classname>, чтобы проверить данные, переданные
      форме. Мы передали верные данные для каждого поля, таким образом
      форма должна быть правильной:
      <screen>
        <![CDATA[
>>> f.is_valid()
True
        ]]>
      </screen>
    </para>

    <para>
      Если мы не передадим поле <token>email</token>, форма
      по-прежнему останется верной, так как мы указали атрибут
      <token>required=False</token> для этого поля:
      <screen>
        <![CDATA[
>>> f = ContactForm({'subject': 'Hello', 'message': 'Nice site!'})
>>> f.is_valid()
True
        ]]>
      </screen>
    </para>

    <para>
      Но если мы не укажем <token>subject</token> или
      <token>message</token>, тогда форма перестанет быть верной:
      <screen>
        <![CDATA[
>>> f = ContactForm({'subject': 'Hello'})
>>> f.is_valid()
False
>>> f = ContactForm({'subject': 'Hello', 'message': ''})
>>> f.is_valid()
False
        ]]>
      </screen>
    </para>

    <para>
      Вы можете получить сообщения об ошибке для каждого поля:
      <screen>
        <![CDATA[
>>> f = ContactForm({'subject': 'Hello', 'message': ''})
>>> f['message'].errors
[u'This field is required.']
>>> f['subject'].errors
[]
>>> f['email'].errors
[]
        ]]>
      </screen>
    </para>

    <para>
      Каждый экземпляр <classname>Form</classname> имеет атрибут
      <token>errors</token>, который хранит словарь со списком
      сообщений для каждого поля:
      <screen>
        <![CDATA[
>>> f = ContactForm({'subject': 'Hello', 'message': ''})
>>> f.errors
{'message': [u'This field is required.']}
        ]]>
      </screen>
    </para>

    <para>
      Наконец, для экземпляров <classname>Form</classname>, данные
      которых признаны верными, становится доступным атрибут
      <token>cleaned_data</token>. Атрибут содержит словарь с
      <quote>чистыми</quote> переданными данными. Библиотека для
      работы с формами не только проверяет данные, но и может их
      обрабатывать, конвертируя значения в соответствующие типы языка
      Python.
      <screen>
        <![CDATA[
>>> f = ContactForm({‘subject’: ‘Hello’, ‘email’: ‘adrian@example.com’, ‘message’: ‘Nice site!’})
>>> f.is_valid()
True
>>> f.cleaned_data
{‘message’: u’Nice site!’, ‘email’: u’adrian@example.com’, ‘subject’: u’Hello’}
        ]]>
      </screen>
    </para>

    <para>
      Наша форма работает только со строками, которые конвертируются в
      объекты <classname>Unicode</classname> &mdash; но если мы бы мы
      использовали <classname>IntegerField</classname> или
      <classname>DateField</classname>, библиотека бы предоставила в
      <token>cleaned_data</token> соответствующие типы целого или
      <token>datetime.date</token> объекты для соответствующих полей.
    </para>

  </section>

  <section id="&BASEID;.use-form-with-view">

    <title id="&BASEID;.use-form-with-view.title">
      Используем формы в представлениях
    </title>

    <para>
      Вот так можно переписать наше представление
      <function>contact()</function>, обладая базовыми знаниями о
      классе <classname>Form</classname>.
    </para>

    <para>
      Файл <filename>views.py</filename>:
      <screen>
        <![CDATA[
from django.core.mail import send_mail
from django.shortcuts import render_to_response
from mysite.books.forms import ContactForm

def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            cd = form.cleaned_data
            send_mail(
                cd['subject'],
                cd['message'],
                cd.get('email', 'noreply@example.com'),
                ['siteowner@example.com'],
            )
            return HttpResponseRedirect('/contact/thanks/')
    else:
        form = ContactForm()
    return render_to_response('contact_form.html', {'form': form})
        ]]>
      </screen>
    </para>

    <para>
      Файл <filename>contact_form.html</filename>:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Contact us</title>
</head>
<body>
    <h1>Contact us</h1>

    {% if form.errors %}
        <p style="color: red;">
            Please correct the error{{ form.errors|pluralize }} below.
        </p>
    {% endif %}

    <form action="" method="post">
        <table>
            {{ form.as_table }}
        </table>
        <input type="submit" value="Submit">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Посмотрите, как много ненужного можно убрать! Библиотека
      выполняет вывод формы, её проверку, конвертацию данных и
      повторное отображение формы в случае ошибок.
    </para>

    <para>
      Попробуйте запустить это локально. Загрузите форму, отправьте её
      без данных, отправьте её с неправильным адресом электронной
      почты, затем заполните её правильными данными и
      отправьте. (Конечно, в зависимости от конфигурации вашего
      почтового сервера, вы можете получить ошибку при вызове
      <function>send_mail</function>, но это уже другая история.)
    </para>

  </section>

  <section id="&BASEID;.fields-rendering">

    <title id="&BASEID;.fields-rendering.title">
      Изменения способа отображения полей
    </title>

    <para>
      Возможно первое, что вам потребуется сделать, когда вы
      попробуете локально поработать с нашей формой &mdash; изменить
      отображение поля <token>message</token> так, чтобы оно
      использовало <token><![CDATA[<textarea>]]></token> вместо
      <token><![CDATA[<input type="text">]]></token>. Мы можем
      исправить это с помощью атрибута поля <token>widget</token>:
      <screen>
        <![CDATA[
from django import forms

class ContactForm(forms.Form):
    subject = forms.CharField()
    email = forms.EmailField(required=False)
    message = forms.CharField(widget=forms.Textarea)
        ]]>
      </screen>
    </para>

    <para>
      Библиотека выделяет логику представления каждого поля в набор
      виджетов. Каждый тип поля имеет стандартный виджет, но вы можете
      легко его изменить или указать свой собственный.
    </para>

    <para>
      Рассматривайте классы <classname>Field</classname> в качестве
      <emphasis>проверочной логики</emphasis>, а виджеты в качестве
      <emphasis>логики представления</emphasis>.
    </para>

  </section>

  <section id="&BASEID;.maximum-length">

    <title id="&BASEID;.maximum-length.title">
      Установка максимального размера поля
    </title>

    <para>
      При проверке значения поля обычно сначала проверяют длину
      переданной строки. Ограничим поле <token>subject</token> нашей
      формы ста символами. Для этого, просто назначьте соответствующее
      значение атрибуту <token>max_length</token> классу
      <classname>CharField</classname> поля:
      <screen>
        <![CDATA[
from django import forms

class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    email = forms.EmailField(required=False)
    message = forms.CharField(widget=forms.Textarea)
        ]]>
      </screen>
    </para>

    <para>
      Также существует необязательный атрибут
      <token>min_length</token>.
    </para>

  </section>

  <section id="&BASEID;.initial-values">

    <title id="&BASEID;.initial-values.title">
      Установка начальных значений
    </title>

    <para>
      В качестве усовершенствования формы, добавим <emphasis>начальное
      значение</emphasis> для поля <token>subject</token>: <token>I
      love your site!</token> (Небольшое внушение не повредит.) Для
      этого следует воспользоваться аргументом <token>initial</token>
      при создании экземпляра формы:
      <screen>
        <![CDATA[
def contact(request):
    if request.method == 'POST':
        form = ContactForm(request.POST)
        if form.is_valid():
            cd = form.cleaned_data
            send_mail(
                cd['subject'],
                cd['message'],
                cd.get('email', 'noreply@example.com'),
                ['siteowner@example.com'],
            )
            return HttpResponseRedirect('/contact/thanks/')
    else:
        form = ContactForm(
            initial={'subject': 'I love your site!'}
        )
    return render_to_response('contact_form.html', {'form': form})
        ]]>
      </screen>
    </para>

    <para>
      Теперь поле <token>subject</token> будет отображаться
      заполненным.
    </para>

    <para>
      Следует отметить, что существует разница между передачей
      <emphasis>начальных</emphasis> данных и передачей данных,
      которые <emphasis>привязаны</emphasis> к форме. Разница
      заключается в том, что если просто передаёте
      <emphasis>начальные</emphasis> данные, то форма остаётся
      <emphasis>незаполненной</emphasis>, что она не будет содержать
      сообщений об ошибках<footnote><para>Авторы имеют в виду, что
      если при возникновении ошибки во время проверки данных и вы
      возвратите пользователю форму, передав данные в форму через
      <token>initial</token>, то никаких сообщений о возникших ошибках
      не сохранится. Примечание переводчика.</para></footnote>.
    </para>

  </section>

  <section id="&BASEID;.validation-rules">

    <title id="&BASEID;.validation-rules.title">
      Собственные правила проверки
    </title>

    <para>
      Представьте, что мы выложили форму на боевой сервер и к нам
      начали приходить сообщения. Но есть одна проблема &mdash;
      некоторые сообщения содержат всего одно-два слова, что
      недостаточно для нашей цели. Мы решили применить новую политику
      проверки: четыре слова или больше, пожалуйста.
    </para>

    <para>
      Существует ряд методов реализации собственного механизма
      проверки в форме. Если наше правило будет использоваться в
      других проектах, мы можем создать собственный тип
      поля. Большинство пользовательских проверок не используются
      повторно, хотя и могут быть внедрены в класс
      <classname>Form</classname>.
    </para>

    <para>
      Раз нам требуется дополнительная проверка поля
      <token>message</token>, добавим метод
      <function>clean_message()</function> в наш класс:
      <screen>
        <![CDATA[
from django import forms

class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    email = forms.EmailField(required=False)
    message = forms.CharField(widget=forms.Textarea)

    def clean_message(self):
        message = self.cleaned_data['message']
        num_words = len(message.split())
        if num_words < 4:
            raise forms.ValidationError("Not enough words!")
        return message
        ]]>
      </screen>
    </para>

    <para>
      Библиотека автоматически ищет любой метод, который начинается с
      <token>clean_</token> и заканчивается на имя поля. Если такой
      метод существует, он используется во время выполнения проверки
      поля.
    </para>

    <para>
      Данные метод <function>clean_message()</function> будет вызван
      <emphasis>после</emphasis> выполнения стандартной проверки для
      данного поля (в этом случае, необходимая проверка для
      <classname>CharField</classname>). Так как значение поля уже
      будет частично проверено, мы получаем его из
      <token>self.cleaned_data</token>. Также, нам не стоит
      беспокоиться о наличии значения или о том, что оно пустое, всё
      это обеспечит стандартный обработчик.
    </para>

    <para>
      Мы просто используем комбинацию <function>len()</function> и
      <function>split()</function> для подсчёта количества слов. Если
      пользователь ввёл слишком мало слов, мы вызываем исключение
      <classname>ValidationError</classname> модуля
      <token>forms</token>. Строка, переданная исключению, будет
      отображена пользователю в виде элемента списка ошибок.
    </para>

    <para>
      Важно то, что мы явно возвращаем обработанное значение поля в
      конце метода. Это позволяет нам модифицировать значение (или
      преобразовать его в другой тип Python) в рамках данного
      метода. Если мы забудем воспользоваться оператором
      <token>return</token>, тогда будет возвращён <token>None</token>
      и оригинальное значение будет утеряно.
    </para>

  </section>

  <section id="&BASEID;.specifying-labels">

    <title id="&BASEID;.specifying-labels.title">
      Определение меток
    </title>

    <para>
      По умолчанию метки для полей формы создаются автоматически из
      имени поля путём замены символов подчёркивания на пробелы и
      переводом первой буквы на заглавную &mdash; из имени поля
      <token>email</token> мы получим <quote>Email</quote>. (Знакомо?
      Это тот же простой алгоритм, который используется в моделях
      Django для вычисления значения <token>verbose_name</token> для
      их полей. Мы рассмотрели его в главе <quote><xref
      linkend="djangobook.chap05"
      endterm="djangobook.chap05.title"/></quote>.)
    </para>

    <para>
      Но как и в случае с моделями, мы можем выводить требуемую метку
      для конкретного поля. Воспользуйтесь атрибутом
      <token>label</token>, так:
      <screen>
        <![CDATA[
class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    email = forms.EmailField(required=False, label='Your e-mail address')
    message = forms.CharField(widget=forms.Textarea)
        ]]>
      </screen>
    </para>

  </section>

  <section id="&BASEID;.form-design">

    <title id="&BASEID;.form-design.title">
      Настройка дизайна формы
    </title>

    <para>
      Наш шаблон <filename>contact_form.html</filename> использует
      <token>{{ form.as_table }}</token> для отображения формы, но мы
      можем отображать её другими способами для получения более
      точного контроля над процессом отображения.
    </para>

    <para>
      Наиболее быстрым способом настройки вида формы будет
      использование CSS. Списки ошибок могут отображаться с визуальным
      выделением, автосгенерированные списки используют <![CDATA[<ul
      class="errorlist">]]>, это можно использовать:
      <screen>
        <![CDATA[
<style type="text/css">
    ul.errorlist {
        margin: 0;
        padding: 0;
    }
    .errorlist li {
        background-color: red;
        color: white;
        display: block;
        font-size: 10px;
        margin: 0 0 3px;
        padding: 4px 5px;
    }
</style>
        ]]>
      </screen>
    </para>

    <para>
      Чаще всего вы будете изменять стандартный вид формы. Тег
      <token>{{ form.as_table }}</token> и остальные являются лишь
      полезными сокращениями, но процессом отображения формы можно
      управлять, в основном на уровне шаблона.
    </para>

    <para>
      Каждый виджет поля (<![CDATA[<input type="text">]]>,
      <![CDATA[<select>]]>, <![CDATA[<textarea>]]> и так далее) может
      быть индивидуально отображён с помощью указания <token>{{
      form.fieldname }}</token> в шаблоне, а любые ошибки,
      ассоциированные с конкретным полем, можно получить через
      <token>{{ form.fieldname.errors }}</token>. Помня это, мы можем
      создать собственный шаблон для нашей формы с помощью следующего
      кода:
      <screen>
        <![CDATA[
<html>
<head>
    <title>Contact us</title>
</head>
<body>
    <h1>Contact us</h1>

    {% if form.errors %}
        <p style="color: red;">
            Please correct the error{{ form.errors|pluralize }} below.
        </p>
    {% endif %}

    <form action="" method="post">
        <div class="field">
            {{ form.subject.errors }}
            <label for="id_subject">Subject:</label>
            {{ form.subject }}
        </div>
        <div class="field">
            {{ form.email.errors }}
            <label for="id_email">Your e-mail address:</label>
            {{ form.email }}
        </div>
        <div class="field">
            {{ form.message.errors }}
            <label for="id_message">Message:</label>
            {{ form.message }}
        </div>
        <input type="submit" value="Submit">
    </form>
</body>
</html>
        ]]>
      </screen>
    </para>

    <para>
      Тег <token>{{ form.message.errors }}</token> отобразит
      <![CDATA[<ul class="errorlist">]]>, при наличии ошибок и пустую
      строку, при их отсутствии (или если к форме не привязаны
      данные). Мы можем также рассматривать
      <token>form.message.errors</token> в качестве булевого значения
      или в качестве итератора. Например:
      <screen>
        <![CDATA[
<div class="field{% if form.message.errors %} errors{% endif %}">
    {% if form.message.errors %}
        <ul>
        {% for error in form.message.errors %}
            <li><strong>{{ error }}</strong></li>
        {% endfor %}
        </ul>
    {% endif %}
    <label for="id_message">Message:</label>
    {{ form.message }}
</div>
        ]]>
      </screen>
    </para>

    <para>
      В случае ошибок при проверке данных, к тегу <![CDATA[<div>]]>
      будет добавлен класс <token>errors</token> и будут отображены
      ошибки в виде ненумерованного списка.
    </para>

  </section>

  <section id="&BASEID;.what-is-next">

    <title id="&BASEID;.what-is-next.title">
      Что дальше?
    </title>

    <para>
      Данная глава завершает вводную часть этой книги. Следующие
      главы, с <quote><xref linkend="djangobook.chap08"
      endterm="djangobook.chap08.title"/></quote> по <quote><xref
      linkend="djangobook.chap12"
      endterm="djangobook.chap12.title"/></quote>, рассматривают
      подробности профессионального использования Django, включая
      вопрос развёртывания приложения.
    </para>

    <para>
      После изучения этих семи глав вы должны обладать достаточным
      объемом знаний для того, чтобы начать работу над собственными
      Django проектами. Оставшаяся часть книги поможет вам разобраться
      с тонкостями этого процесса.
    </para>

    <para>
      Мы начнём главу <quote><xref linkend="djangobook.chap08"
      endterm="djangobook.chap08.title"/></quote> с возвращения к
      представлениям и схеме URL (о которых было рассказано в главе
      <quote><xref linkend="djangobook.chap03"
      endterm="djangobook.chap03.title"/></quote>).
    </para>

  </section>

</chapter>