Criando Formulários a Partir de Models — Django 1

7/24/2019 Criando Formulrios a Partir de Models Django 1

1/16

2/23/2016 Criando formulrios a partir de models Django 1.0 documentation

https://django-portuguese.readthedocs.org/en/1.0/topics/forms/modelforms.html 1

Criando formulrios a partir de models

ModelForm

Se voc est construindo uma aplicao baseada em banco de dados, existe uma grandechance de que seus formulrios correspondero com os seus modelos Django. Por exemplo,

voc tem um modeloBlogComment, e quer criar um formulrio que possibilite que as

pessoas enviem comentrios. Neste caso, seria redundante definir os tipos de campo no seu

formulrio, porque isso j foi feito no seu modelo.

Por este motivo, o Django disponibiliza uma classe de ajuda que possibilita a criao de uma

classe Forma partir de um modelo Django.

Por exemplo:

>>> fromdjango.formsimportModelForm

# Cria a classe de formulrio>>> classArticleForm(ModelForm):... classMeta:... model =Article

# Criando um formulrio para adicionar um artigo.>>> form =ArticleForm()

# Criando um formulrio para atualizar dados de um artigo.>>> article =Article.objects.get(pk=1)>>> form =ArticleForm(instance=article)

Tipos de campos

A classe Formgerada ter um campo de formulrio para cada campo de modelo. Cada

campo de modelo tem um campo de formulrio correspondente padro. Por exemplo, umCharFieldnum modelo representado como umCharFieldnum formulrio. Um

ManyToManyFieldno modelo representado como umMultipleChoiceField. Segue

uma lista completa de converses:

Campo de modelo Campo de formulrio

AutoField No representado no formulrio

BooleanField BooleanField

CharField CharFieldcom max_lengthigual ao valor de


2/16



max_lengthdo campo do modelo

CommaSeparatedIntegerField CharField

DateField DateField

DateTimeField DateTimeField

DecimalField DecimalField

EmailField EmailField

FileField FileField

FilePathField CharField

FloatField FloatField

ForeignKey ModelChoiceField(veja abaixo)

ImageField ImageField

IntegerField IntegerField

IPAddressField IPAddressField

ManyToManyField ModelMultipleChoiceField(veja abaixo)NullBooleanField CharField

PhoneNumberField USPhoneNumberField(de

django.contrib.localflavor.us)

PositiveIntegerField IntegerField

PositiveSmallIntegerField IntegerField

SlugField CharField

SmallIntegerField IntegerField

TextField CharFieldcom widget=forms.Textarea

TimeField TimeField

URLField URLFieldcom verify_existsigual ao valor de

verify_existsdo campo do modelo

XMLField CharFieldcom widget=Textarea

New in Django 1.0: O campo de formulrioFloatFieldjuntamente com os campos de

fomulrio e de modeloDecimalFieldso novos no Django 1.0.

Como esperado, os campos de modelo do tipoForeignKeye ManyToManyFieldsocasos especiais:

ForeignKey representado pordjango.forms.ModelChoiceField, que um

ChoiceFieldem quechoices umQuerySetdo modelo.

ManyToManyField representado por

django.forms.ModelMultipleChoiceField, que um MultipleChoiceField

em que choices umQuerySetdo modelo.


3/16



Alm disso, cada campo de formulrio gerado tem os valores de atributos definidos como

asseguir:

Se um campo de modelo temblank=True, ento o valor derequiredserFalseno

campo de formulrio. Caso contrrio,required=True.

O atributo labeldo campo de formulrio ser igual aoverbose_namedo campo de

modelo, com o primeiro caractere em maisculo.O help_textdo campo de formulrio igual aohelp_textdo campo de modelo.

Se o campo de modelo tem o atributochoicesdefinido, ento owidgetdo campo de

formulrio ser oSelect, com a lista de opes vindas do atributochoicesdo campo

de modelo. As opes normalmente incluiro o valor em branco, que selecionado por

padro. Se o campo requerido, isso fora o usurio a fazer uma escolha. O valor em

branco no ser includo se o campo de modelo tem atributoblank=Falsee um valor

de defaultexplcito (em vez disso o valor dedefaultser selecionado inicialmente).

Finalmente, note que voc pode redefinir o campo de formulrio utilizado por um determinado

modelo. Veja Redefinindo os tipos de campo padroabaixo.

Um exemplo completo

Considere este conjunto de modelos:

fromdjango.dbimportmodelsfromdjango.formsimportModelForm

TITLE_CHOICES =(('MR', 'Mr.'),('MRS', 'Mrs.'),('MS', 'Ms.'),

)

classAuthor(models.Model):name =models.CharField(max_length=100)title =models.CharField(max_length=3, choices=TITLE_CHOICE

birth_date =models.DateField(blank=True, null=True)

def__unicode__(self):returnself.name

classBook(models.Model):name =models.CharField(max_length=100)authors =models.ManyToManyField(Author)

classAuthorForm(ModelForm):classMeta:


4/16



model =Author

classBookForm(ModelForm):classMeta:

model =Book

Com estes modelos, as subclasses deModelFormacima seriam equivalentes a isto (a nica

diferena sendo o mtodosave(), que discutiremos daqui a pouco.):

classAuthorForm(forms.Form):name =forms.CharField(max_length=100)title =forms.CharField(max_length=3,

widget=forms.Select(choices=TITLE_CHOICES))birth_date =forms.DateField(required=False)

classBookForm(forms.Form):name =forms.CharField(max_length=100)authors =forms.ModelMultipleChoiceField(queryset=Author.ob

O mtodo save()

Todo formulrio produzido porModelFormtem tambm um mtodosave(). Este mtodo

cria e grava um objeto no banco de dados a partir dos dados atrelados ao formulrio. Uma

subclasse de ModelFormpode aceitar uma instncia de modelo existente como uma

argumento nomeadoinstance se este argumento fornecido, osave()ir atualizar a

instncia. Se no fornecido, osave()criar uma nova instncia do modelo especificado:

# Cria uma instncia de formulrio com dados do POST.>>> f = ArticleForm(request.POST)

# Grava um novo objeto Article com os dados do formulrio.>>> new_article = f.save()

# Cria um formulrio para editar um Article existente.

>>> a = Article.objects.get(pk=1)>>> f = ArticleForm(instance=a)>>> f.save()

# Cria um formulrio para editar um Article existente, mas# usa os dados do POST para popular o formulrio.>>> a = Article.objects.get(pk=1)>>> f = ArticleForm(request.POST, instance=a)>>> f.save()


5/16



Note que save()ir levantar uma exceoValueErrorse os dados no formulrio no

validarem -- ou seja if form.errors.

Este mtodo save()aceita um argumento nomeado opcionalcommit, que aceita ou True

ou False. Se voc chamar save()com commit=False, ento ele devolver um objeto que

ainda no foi gravado no banco de dados. Neste caso, sua responsabilidade chamar

save()na instncia de modelo. Isso til se voc quer fazer algum custom processamento

customizado no objeto antes de grav-lo, ou se voc quer usar um umas dasopes de

gravao de modeloespecializadas.commit Truepor padro.

Um efeito colateral no uso decommit=False notado quando o seu modelo tem um

relacionamento de muitos para muitos com outro modelo. Se seu modelo tem um

relacionamento de muitos para muitos e voc especificacommit=Falsequando vai gravar

um formulrio, o Django no pode gravar od dados para o relacionamento de muitos para

muitos imediatamente. Isso se deve ao fato de no ser possvel gravar os dados de muitos

para muitos para uma instncia que ainda no existe no banco de dados.

Para contornar este problema, cada vez que voc grava um formulrio usando

commit=False, o Django adiciona um mtodosave_m2m()para a sua subclasse de

ModelForm. Depois de de gravar manualmente a instncia produzida pelo formulrio, voc

pode chamarsave_m2m()para gravar os dados de muitos para muitos do formulrio. Por

exemplo:

# Cria uma instncia de formulrio com os dados de POST.>>> f = AuthorForm(request.POST)

# Cria, mas no grava a nova instncia de Author.>>> new_author = f.save(commit=False)

# Modifica o Author de alguma maneira.>>> new_author.some_field = 'some_value'

# Grava a nova instncia.>>> new_author.save()

# Agora, grava od dados de muitos para muitos para o formulrio>>> f.save_m2m()

S necessrio chamar osave_m2m()se voc usarsave(commit=False). Quando voc

simplesmente usa osave()num formulrio, todos os dados -- incluindo os dados de muitos

para muitos -- so gravados sem a necessidade de chamadas a nenhum mtodo adicional.

Por exemplo:
https://django-portuguese.readthedocs.org/en/1.0/ref/models/instances.html#ref-models-force-insert


6/16



# Cria uma instncia de formulrio com os dados de POST.>>> a = Author()>>> f = AuthorForm(request.POST, instance=a)

# Cria e grava a nova instncia de Author. No h necessidade d# nada mais.>>> new_author = f.save()

A no ser pelos mtodossave()e save_m2m(), um ModelFormfunciona exatamente igual

a qualquer outro formulrio deforms. Por exemplo, o mtodois_valid()` utilizado para

validar os dados, o mtodois_multipart()para determinar se um formulrio requer

upload de arquivo multipart (e serequest.FILESdeve ser passado ao formulrio), etc. Veja

Vinculando arquivos enviados a um formulriopara mais informao.

Usando somente alguns campos no formulrio

Em alguns casos, voc no quer que todos os campos do modelo apaream no formulrio

gerado. Existem trs maneiras de dizer aoModelFormpara usar somente alguns campos do

modelo:

1. Coloque editable=Falseno campo do modelo. Como resultado,qualquerformulrio

criado via ModelFormno incluir este campo.

2. Use o atributo fieldsda classe internaMetado ModelForm. Esse atributo, se

especificado, deve ser uma lista de nomes de campos a serem includos no formulrio.

3. Use o atributo excludeda classe internaMetado ModelForm. Esse atributo, se

especificado, deve ser uma lista de nomes de campos a serem excludos do formulrio.

Por exemplo, se voc quer que um formulrio para o modeloAuthor(definido acima) tenha

somente os camposnamee title, voc especificaria fieldsou excludeassim:

classPartialAuthorForm(ModelForm):classMeta:

model =Author

fields =('name', 'title')

classPartialAuthorForm(ModelForm):classMeta:

model =Authorexclude =('birth_date',)

J que o modelo Author tem somente trs campos, 'name', 'title', e 'birth_date', os formulrios

acima contero exatamente os mesmos campos.
https://django-portuguese.readthedocs.org/en/1.0/ref/forms/api.html#binding-uploaded-files


7/16



Note

Se voc especifica fieldsou excludena criao de um formulrio com ModelForm,

ento na chamada do mtodo save(), no sero atribudos valores aos campos que

no constam do formulrio resultante. O Django impedir qualquer tentativa de gravar

um modelo incompleto, ento se o modelo no permite que os campos faltantes sejam

vazios, e no existe um valor padro definido para eles, qualquer tentativa de chamar

save()num ModelFormcom campos faltantes no funcionar. Para evitar esse erro,voc deve instanciar seu modelo com valores iniciais para os campos vazios, porm

obrigatrios:

author =Author(title='Mr')form =PartialAuthorForm(request.POST, instance=author)form.save()

Alternatively, you can use save(commit=False)and manually set any extra required

fields:

form =PartialAuthorForm(request.POST)author =form.save(commit=False)author.title ='Mr'author.save()

Veja a seo sobre gravao de formulriospara mais detalhes no uso de

save(commit=False).

Redefinindo os tipos de campo padro

Os tipos de campos padro, como descritos na tabelaTipos de camposacima, so

padres sensatos. Se voc tem umDateFieldno seu modelo, existem grandes chances dq

que voc queira que ele seja representado como umDateFieldno seu formulrio. Mas o

ModelFormte d a flexibilidade de mudar o campo de formulrio para um determinado

campo de modelo. Isso feito de maneira declarativa especificando os campos como faria

num Formnormal. Campos declarados redefiniro os camps padres gerados pelo uso do

atributo model.

Por exemplo, se voc quiser usarMyDateFormFieldpara o campopub_date, faa oseguinte:

>>> classArticleForm(ModelForm):... pub_date =MyDateFormField()...... classMeta:... model =Article


8/16



Se quiser redefiner um widget padro de um campo, ento especifique o parmetro widget

quando declarar o campo de formulrio:

>>> classArticleForm(ModelForm):... pub_date =DateField(widget=MyDateWidget())...... classMeta:

... model =Article

Sobrescrevendo o mtodo clean()

Voc pode sobrescrever o mtodoclean()em um formulrio de modelo para fornecer

informaes adicionais como uma validao, da mesma forma que faria num formulrio

normal.

In this regard, model forms have two specific characteristics when compared to forms:

Por padro o mtodoclean()valida a unicidade dos campos que so marcados como

unique, unique_togetherou unique_for_date|month|yearno modelo. Portanto, se

voc gostaria de sobrescrever o mtodoclean()e manter a validao padro, voc deve

chamar o mtodo daclean()da classe pai.

Also, a model form instance bound to a model object will contain aself.instanceattribute

that gives model form methods access to that specific model instance.

Herana de formulrio

Como nos formulrios bsicos, voc pode extender e reutilizarModelFormsatravs da

herana. Isso til se voc precisa declarar campos ou mtodos adicionais em uma classe

pai para uso em alguns formulrios derivados de modelos. Por exemplo, usando a classe

ArticleFormanterior:

>>> classEnhancedArticleForm(ArticleForm):... defclean_pub_date(self):

... ...

Isso cria um formulrio que se comporta da mesma maneira queArticleForm, exceto por

alguma validao e limpeza de dados adicional para o campopub_date.

Voc pode criar uma subclasse da classe internaMetada classe pai se voc quer mudar as

listas Meta.fieldsouMeta.excludes:

>>> classRestrictedArticleForm(EnhancedArticleForm):


9/16



... classMeta(ArticleForm.Meta):

... exclude =['body']

Isso adiciona o mtodo deEnhancedArticleForme modifica oArticleForm.Meta

original para remover um campo.

Entretanto, existem algumas coisas a serem notadas.

As regras normais de resoluo de nomes Python se aplicam. Se voc tem mltiplas

classes base que declaram uma classe internaMeta, somente a primeira ser utilizada.

Isso significa o Metado filho, se existir, caso contrrio oMetado primeiro pai, etc.

Pela mesma razo, uma subclasse no pode herdar deModelForme Form

simultaneamente.

bem provvel que estas notas no te afetaro, a no ser que esteja tentando fazer algo

complexo utilizando subclasses.

Model Formsets

Como nos formsets comuns, o Django fornece um par de classes avanadas de formset que

tornam facil trabalhar com modelos do Django. Vamos reutilizar o modeloAuthordo exemplo

acima:

>>> fromdjango.forms.modelsimportmodelformset_factory>>> AuthorFormSet =modelformset_factory(Author)

Isso criar um formset que capaz de funcionar com os dados associados ao modelo

Authorque funciona exatamente igual a um formset comum:

>>> formset =AuthorFormSet()>>> printformset


10/16



Note

Uma coisa para se notar que modelformset_factoryusa formset_factorypara

gerar formsets. Isto significa que um formeset de model somente uma extenso de um

formset bsico que sabe como interagir com um model em particular.

Mudando o querysetPor padro quando voc cria um formset de um modelo o formset ir usar um queryset que

inclui todos os objetos no modelo (ex:Author.objects.all()). Voc pode sobrescrever

esse comportamento usando o argumentoqueryset:

>>> formset =AuthorFormSet(queryset=Author.objects.filter(name

Alternativamente, voc pode criar uma subclasse que defina oself.querysetno

__init__:

fromdjango.forms.modelsimportBaseModelFormSet

classBaseAuthorFormSet(BaseModelFormSet):def__init__(self, *args, **kwargs):

self.queryset =Author.objects.filter(name__startswith= super(BaseAuthorFormSet, self).__init__(*args, **kwargs

Ento, passe sua classeBaseAuthorFormSetpara a funo factory:

>>> AuthorFormSet =modelformset_factory(Author, formset=BaseAu

Controlando quais campos so usados com fieldse exclude

Por padro um model formset usar todos os campos do model, que no esto marcados

com editable=False, Entretanto, isto pode ser sobrescrito no nvel do formset:

>>> AuthorFormSet =modelformset_factory(Author, fields=('name'

Usando fieldsvoc ir restringir o formset para usar somente os campos fornecidos.

Alternativamente, voc pode ter uma abordagem de "out-put", especificando quais campos

sero excludos:


11/16



>>> AuthorFormSet =modelformset_factory(Author, exclude=('birt

Usando excludevoc ir evistar que dados campos sejam usados em um formset.

Gravando objetos num formset

Como num ModelFormvoc pode gravar os dados no objeto do modelo. Isso feito com omtodo save()do formset:

# Cria uma instncia de formset com os dados do POST.>>> formset = AuthorFormSet(request.POST)

# Supondo que tudo est vlido, grave os dados>>> instances = formset.save()

O mtodo save()devolver as instncias que foram gravadas no banco de dados. Se umainstncia no mudar seus nos dados atrelados ela no ser gravada no banco e no ser

encontrada no valor de retorn (instancesno exemplo acima).

Pass commit=Falseto return the unsaved model instances:

# no grava no banco de dados>>> instances = formset.save(commit=False)>>> for instance in instances:... # faz alguma coisa com a instncia... instance.save()

Isso d a habilidade de anexar dados s instncias antes de grav-las no banco de dados.

Se seu formset contm umManyToManyFieldvoc precisar tambm chamar

formset.save_m2m()para assegurar que os relacionamentos de muitos para muitos sero

gravados apropriadamente.

Limitando o nmero de objetos editveis

Como em formsets comuns voc pode usar um parmetromax_numno

modelformset_factorypara limitar o nmero de formulrios mostrados. Com formsets de

modelo, isso limitar apropriadamente a query para selecionar somente o mximo de objetos

necessrios:

>>> Author.objects.order_by('name')[, , >> AuthorFormSet =modelformset_factory(Author, max_num=2, ext


12/16



>>> formset =AuthorFormSet(queryset=Author.objects.order_by('n>>> formset.initial[{'id': 1, 'name': u'Charles Baudelaire'}, {'id': 3, 'name': u'

Se o valor de max_num maior que o nmero de objetos retornados, formulrios em branco

extrasero adicionados ao formset, to logo o total de formulrios no excedamax_num:

>>> AuthorFormSet =modelformset_factory(Author, max_num=4, ext>>> formset =AuthorFormSet(queryset=Author.objects.order_by('n>>> forform informset.forms:... printform.as_table()Name:


13/16



(qualquer umaunique, unique_togetherou unique_for_date|month|year). Se voc

quiser sobrescrever o mtodoclean()de ummodel_formsete manter esta validao,

voc deve chamar o mtodocleanda classe pai:

class MyModelFormSet(BaseModelFormSet):def clean(self):

super(MyModelFormSet, self).clean()

# exemplo de validao customizada de forms do formset:for form in self.forms:

# your custom formset validation# sua validao personalizada de formset

Usando um queryset customizado

Como j foi dito, voc pode sobrescrever o queryset padro usado pelo model formset:

defmanage_authors(request):AuthorFormSet =modelformset_factory(Author)ifrequest.method =="POST":

formset =AuthorFormSet(request.POST, request.FILES,queryset=Author.objects.filter(

ifformset.is_valid():formset.save()# Faa algo.

else:formset =AuthorFormSet(queryset=Author.objects.filter(

returnrender_to_response("manage_authors.html", {"formset": formset,

})

Note que ns passamos o argumentoquerysetem ambos os casosPOSTe GETneste

exemplo.

Usando o formset no template

J trs formas de renderizar um formset num template Django.

Primeiro, voc pode deixar o formset fazer a maior parte do trabalho:

{{formset}}

Segundo, voc pode manualmente renderizar o formset, mas deixe o form trabalhar por contra


14/16



prpria:

{{formset.management_form}}{%forforminformset.forms%}

{{form}}{%endfor%}

Quando voc renderizar formulrios manualmente, certifique-se de renderizar o

management_formcomo mostrado acima. Veja adocumentao do management form.

Terceiro, voc pode renderizar manualmente cada campo:


{%forfieldinform%}{{field.label_tag}}: {{field}}

{%endfor%}{%endfor%}

Se voc optar por usar este terceiro mtodo e voc no iterar sobre os campos com um loop

{% for %}, voc precisar renderizar a chave primria. Por exemplo, se voc renderizou os

campos namee agede um model:


{{form.id}}

{{form.name}}{{form.age}}

{%endfor%}

Observe como preciso, explicitamente, renderizar{{form.id}}. Isto garante que o formset

do model, no caso doPOST, ir funcionar perfeitamente. (Este exemplo assume uma chave

primria chamada id, certifique-se de renderiz-la.)

Formsets em linha (inline)
https://readthedocs.org/projects/django-portuguese/?fromdocs=django-portuguesehttps://django-portuguese.readthedocs.org/en/1.0/topics/forms/formsets.html#understanding-the-managementform


15/16



Formsets em linha uma pequena camada de abstrao sobre os formsets de model. Este

simplificam o caso de trabalhar com objetos relacionados atravs de uma chave estrangeira.

Suponhamos que voc tenha dois models:

classAuthor(models.Model):name =models.CharField(max_length=100)

classBook(models.Model):author =models.ForeignKey(Author)title =models.CharField(max_length=100)

Se voc quiser criar um formset que permita editar books pertencentes a um author em

particular, voc pode fazer isto:

>>> fromdjango.forms.modelsimportinlineformset_factory>>> BookFormSet =inlineformset_factory(Author, Book)

>>> author =Author.objects.get(name=u'Mike Royko')>>> formset =BookFormSet(instance=author)

Note

inlineformset_factoryusa modelformset_factorye marca can_delete=True.

Mais de uma chave estrangeira para o mesmo model

Se o seu model contm mais de uma chave estrangeira para o mesmo model, voc precisar

resolver a ambiguidade manualmente utilizandofk_name. Por exemplo, considere o seguinte

model:

classFriendship(models.Model):from_friend =models.ForeignKey(Friend)to_friend =models.ForeignKey(Friend)length_in_months =models.IntegerField()

Para resolver isto, voc pode usarfk_nameparainlineformset_factory:

>>> FriendshipFormSet =inlineformset_factory(Friend, Friendshi

Usando um formset em linha em um view

Voc pode querer prover um view que permite um usurio editar os objetos relacionados de


16/16


um model. Aqui tem uma maneira de se fazer isso:

defmanage_books(request, author_id):author =Author.objects.get(pk=author_id)BookInlineFormSet =inlineformset_factory(Author, Book)ifrequest.method =="POST":

formset =BookInlineFormSet(request.POST, request.FILES

ifformset.is_valid():formset.save()# Do something.

else:formset =BookInlineFormSet(instance=author)

returnrender_to_response("manage_books.html", {"formset": formset,

})

Observe como passamosinstanceem ambos os casosPOSTe GET.

Criando Formulários a Partir de Models — Django 1

Documents

Transcript of Criando Formulários a Partir de Models — Django 1