..
.. META INFORMATION OF TRANSLATION
..
..   $TranslationStatus: Done, waiting for revision $
..   $OriginalRevision: 11348 $
..   $TranslationAuthors: Robson Mendonça $
..
.. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION)
..
..   $HeadURL$
..   $LastChangedRevision$
..   $LastChangedBy$
..   $LastChangedDate$
..


.. _ref-contrib-formtools-form-preview:

===============================
Pré-visualização de formulários
===============================

.. module:: django.contrib.formtools
    :synopsis: Mostra um formulário HTML, força uma previsão, e então faz algo
               com a submissão do formulário.

O Django vem acompanhado com uma aplicação opcional, "form preview", que ajuda
a automatizar o seguinte workflow:

"Mostrar um formulário HTML, forçar uma pré-visualização, somente então fazer
algo com o enviado."

Para forçar uma pré-visualização de um envio de formulário, todos devem
escrever uma pequena classe Python.

Visão Geral
===========

Dada uma subclasse de :class:`django.forms.Form` que você define, esta aplicação
se preocupa com o seguinte fluxo:

    1. Mostrar o formulário como uma página HTML.
    2. Validar os dados do formulário quando este é enviado via POST.
       a. Se for válido, mostra uma pré-visualização da página.
       b. Se não for válido, mostra novamente o formulário com as mensagens de
       erro.
    3. Quando a "confirmação" do formulário é submetida da página de previsão,
       chame um hook que você define -- um método
       :meth:`~django.contrib.formtools.FormPreview.done()` que captura os
       dados válidos passados.

O framework fiscaliza a pré-visualização requisitada passando um hash de
segredo compartilhado para a página de pré-visualização, por meio de campos
hidden. Se alguém ajusta os parâmetros do formulário na página de
pré-visualização, o envio do formulário pode falhar no momento da comparação
com o hash.

Como usar o ``FormPreview``
===========================

    1. Aponte o Django para os templates padrão do ``FormPreview``. Existem
       duas maneiras de fazer isso:

       * Adicione ``'django.contrib.formtools'`` em seu
         :setting:`INSTALLED_APPS`. Isso funcionará se o seu
         :setting:`TEMPLATE_LOADERS` incluir o carregador de templates (que vem
         por padrão) ``app_directories``. Veja a
         :ref:`documentação do carregador de templates <template-loaders>` para
         saber mais.

       * De outra maneira, determine o caminho completo no sistema de arquivos
         para o diretório :file:`django/contrib/formtools/templates` e
         adicione-o no :setting:`TEMPLATE_DIRS` no arquivo settings.py.

    2. Crie uma subclasse :class:`~django.contrib.formtools.FormPreview` que
       sobrescreva o método
       :meth:`~django.contrib.formtools.FormPreview.done()`::

           from django.contrib.formtools.preview import FormPreview
           from myapp.models import SomeModel

           class SomeModelFormPreview(FormPreview):

               def done(self, request, cleaned_data):
                   # Faça algo com o cleaned_data, e depois redirecione
                   # para uma página de "sucesso".
                   return HttpResponseRedirect('/form/success')

       Este método recebe um objeto :class:`~django.http.HttpRequest` e um
       dicionário de dados de formulário, depois de terem sido validados e
       limpos. Podendo retornar um :class:`~django.http.HttpResponseRedirect`,
       que é um resultado final de um fomulário que foi enviado.

    3. Mude seu URLconf para apontar para uma instância de sua subclasse
       :class:`~django.contrib.formtools.FormPreview`


           from myapp.preview import SomeModelFormPreview
           from myapp.models import SomeModel
           from django import forms

       ...e adicione a seguinte linha para o modelo apropriado em seu URLconf::

           (r'^post/$', SomeModelFormPreview(SomeModelForm)),

       onde ``SomeModelForm`` é uma classe Form ou ModelForm.

    4. Rode o servidor do Django e visite :file:`/post/` no seu navegador.

Classes ``FormPreview``
=======================

.. class: FormPreview

Uma classe :class:`~django.contrib.formtools.FormPreview` é uma simples classe
Python que representa o fluxo da pré-visualização. As classes
:class:`~django.contrib.formtools.FormPreview` devem ser subclasses de
``django.contrib.formtools.preview.FormPreview`` e sobrescrever o método
:meth:`~django.contrib.formtools.FormPreview.done()`. Elas podem ficar em
qualquer parte da base de código.

Templates ``FormPreview``
=========================

Por padrão, o formulário é renderizado por meio do template
:file:`formtools/form.html`, e a página de previsão é renderizada por meio do
template :file:`formtools.preview.html`. Esses valores podem ser sobrescritos
por um formulário de pré-visualização configurando os atributos
:attr:`~django.contrib.formtools.FormPreview.preview_template` e
:attr:`~django.contrib.formtools.FormPreview.form_template` na subclasse
FormPreview. Veja :file:`django/contrib/formtools/templates` para conhecer os
templates padrões.