Bekerja dengan formulir¶

GET dan POST¶

GET dan POST adalah hanya cara HTTP digunakan untuk berhubungan dengan formulir.

Django's login form is returned using the POST method, in which the browser bundles up the form data, encodes it for transmission, sends it to the server, and then receives back its response.

GET, by contrast, bundles the submitted data into a string, and uses this to compose a URL. The URL contains the address where the data must be sent, as well as the data keys and values. You can see this in action if you do a search in the Django documentation, which will produce a URL of the form https://docs.djangoproject.com/search/?q=forms&release=1.

GET and POST adalah khususnya digunakan untuk tujuan berbeda.

Any request that could be used to change the state of the system - for example, a request that makes changes in the database - should use POST. GET should be used only for requests that do not affect the state of the system.

GET would also be unsuitable for a password form, because the password would appear in the URL, and thus, also in browser history and server logs, all in plain text. Neither would it be suitable for large quantities of data, or for binary data, such as an image. A web application that uses GET requests for admin forms is a security risk: it can be easy for an attacker to mimic a form's request to gain access to sensitive parts of the system. POST, coupled with other protections like Django's CSRF protection offers more control over access.

On the other hand, GET is suitable for things like a web search form, because the URLs that represent a GET request can easily be bookmarked, shared, or resubmitted.

Kelas Form Django¶

At the heart of this system of components is Django's Form class. In much the same way that a Django model describes the logical structure of an object, its behavior, and the way its parts are represented to us, a Form class describes a form and determines how it works and appears.

In a similar way that a model class's fields map to database fields, a form class's fields map to HTML form <input> elements. (A ModelForm maps a model class's fields to HTML form <input> elements via a Form; this is what the Django admin is based upon.)

A form's fields are themselves classes; they manage form data and perform validation when a form is submitted. A DateField and a FileField handle very different kinds of data and have to do different things with it.

A form field is represented to a user in the browser as an HTML "widget" - a piece of user interface machinery. Each field type has an appropriate default Widget class, but these can be overridden as required.

Mengawali, mengolah, dan membangun formulir¶

Ketika membangun sebuah obyek di Django, kami umumnya:

1. get hold of it in the view (fetch it from the database, for example)

2. lewatkan ke konteks cetakan

3. perluas itu pada markah HTML menggunakan variabel cetakan

Membangun formulir dalam cetakan melibatkan hampir pekerjaan sama seperti membangun jenis lain dari obyek, tetapi ada beberapa kunci perbedaan.

In the case of a model instance that contained no data, it would rarely if ever be useful to do anything with it in a template. On the other hand, it makes perfect sense to render an unpopulated form - that's what we do when we want the user to populate it.

Jadi ketika kami menangani instance model dalam tampilan, kami khususnya mengambil itu dari basisdata. Ketika kami sedang berhubungan dengan seuah formulir kami khususnya menginstansiasi itu dalam tampilan.

When we instantiate a form, we can opt to leave it empty or prepopulate it, for example with:

• data dari instance model tersimpan (seperti dalam kasus dari formulir admin untuk penyuntingan).

• data yang kami telah kumpulkan dari sumber lain

• data diterima dari pengajuan formulir HTML sebelumnya

Kasus terakhir ini paling menarik, karena itu memungkinkan untuk pengguna tidak hanya membaca jaringan situs, tetapi juga mengirim informasi kembali ke jaringan situs.

Pekerjaan yang butuh diselesaikan¶

Misalnya anda ingin membuat sebuah formulir sederhana pada situs jaringan anda, untuk mendapatkan nama pengguna, anda akan butuh sesuatu seperti ini di cetakan anda:

<form action="/your-name/" method="post">
    <label for="your_name">Your name: </label>
    <input id="your_name" type="text" name="your_name" value="{{ current_name }}">
    <input type="submit" value="OK">
</form>

Ini memberitahukan perambah untuk mengembalikan data formulir ke URL /your-name/, menggunakan cara POST. Dia akan menampilkan bidang teks, label "Nama anda:", dan tombol ditandai "OK". Jika konteks cetakan mengandung variabel current_name, yang akan digunakan untuk pra-isian bidang your_name.

Anda akan butuh sebuah tampilan yang membangun cetakan mengandung formulir HTML, dan dapat mendukung bidang current_name sewajarnya.

Ketika formulir diajukan, permintaan POST yang dikirim ke peladen akan mengandung data formulir.

Sekarang anda akan juga butuh sebuah tampilan sesuai ke URL /your-name/ yang akan menemukan pasangan kunci/nilai yang sesuai di permintaan, dan kemudian mengolah mereka.

This is a very simple form. In practice, a form might contain dozens or hundreds of fields, many of which might need to be prepopulated, and we might expect the user to work through the edit-submit cycle several times before concluding the operation.

Kami mungkin membutuhkan beberapa pengesahan untuk muncul dalam peramban, bahkan sebelum formulir diajukan; kami mungkin ingin menggunakan bidang-bdiang lebih rumit, yang mengizinkan pengguna melakukan hal-hal seperti mengambil tanggal dari kalender dan seterusnya.

Pada titik ini itu lebih mudah mendapatkan Django melakukan kebanyakan dari pekerjaan ini untuk kita.

Membangun formulir di Django¶

from django import forms


class NameForm(forms.Form):
    your_name = forms.CharField(label="Your name", max_length=100)

<label for="your_name">Your name: </label>
<input id="your_name" type="text" name="your_name" maxlength="100" required>

from django.http import HttpResponseRedirect
from django.shortcuts import render

from .forms import NameForm


def get_name(request):
    # if this is a POST request we need to process the form data
    if request.method == "POST":
        # create a form instance and populate it with data from the request:
        form = NameForm(request.POST)
        # check whether it's valid:
        if form.is_valid():
            # process the data in form.cleaned_data as required
            # ...
            # redirect to a new URL:
            return HttpResponseRedirect("/thanks/")

    # if a GET (or any other method) we'll create a blank form
    else:
        form = NameForm()

    return render(request, "name.html", {"form": form})

<form action="/your-name/" method="post">
    {% csrf_token %}
    {{ form }}
    <input type="submit" value="Submit">
</form>

Instance formulir terikat dan tidak terikat¶

Perbedaan diantara Bound and unbound forms adalah penting:

• Sebuah formulir tidak terikat tidak mempunyai data terkait dengan itu. Ketika dibanguk ke pengguna, itu akan kosong atau mengandung nilai awalan.

• Sebuah formulir ikatan telah mengajukan data, dan kemudian dapat digunakan untuk memberitahu jika data adalah sah. Jika sebuah ikatan tidak sah dibangun, itu dapat menyertakan pesan-pesan kesalahan berderet mengatakan pengguna apa yang data untuk diperbaiki.

Atribut formulir is_bound akan memberitahu anda apakah sebuah formulir mempunyai data terikat ke itu atau tidak.

Lebih pada bidang¶

Pertimbangkan formulir lebih berguna dari contoh minimal kami diatas, yang kami dapat gunakan untuk menerapkan kegunaan "hubungi kami" pada situs jaringan pribadi:

from django import forms


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

Our earlier form used a single field, your_name, a CharField. In this case, our form has four fields: subject, message, sender and cc_myself. CharField, EmailField and BooleanField are just three of the available field types; a full list can be found in Bidang formulir.

from django.core.mail import send_mail

if form.is_valid():
    subject = form.cleaned_data["subject"]
    message = form.cleaned_data["message"]
    sender = form.cleaned_data["sender"]
    cc_myself = form.cleaned_data["cc_myself"]

    recipients = ["[email protected]"]
    if cc_myself:
        recipients.append(sender)

    send_mail(subject, message, sender, recipients)
    return HttpResponseRedirect("/thanks/")

Formulir cetakan-cetakan dapat digunakan kembali¶

The HTML output when rendering a form is itself generated via a template. You can control this by creating an appropriate template file and setting a custom FORM_RENDERER to use that form_template_name site-wide. You can also customize per-form by overriding the form's template_name attribute to render the form using the custom template, or by passing the template name directly to Form.render().

The example below will result in {{ form }} being rendered as the output of the form_snippet.html template.

Dalam cetakan anda:

# In your template:
{{ form }}

# In form_snippet.html:
{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

Then you can configure the FORM_RENDERER setting:

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    form_template_name = "form_snippet.html"


FORM_RENDERER = "project.settings.CustomFormRenderer"

… or for a single form:

class MyForm(forms.Form):
    template_name = "form_snippet.html"
    ...

… or for a single render of a form instance, passing in the template name to the Form.render(). Here's an example of this being used in a view:

def index(request):
    form = MyForm()
    rendered_form = form.render("form_snippet.html")
    context = {"form": rendered_form}
    return render(request, "index.html", context)

See Mengeluarkan formulir sebagai HTML for more details.

Reusable field group templates¶

Each field is available as an attribute of the form, using {{ form.name_of_field }} in a template. A field has a as_field_group() method which renders the related elements of the field as a group, its label, widget, errors, and help text.

This allows generic templates to be written that arrange fields elements in the required layout. For example:

{{ form.non_field_errors }}
<div class="fieldWrapper">
  {{ form.subject.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.message.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.sender.as_field_group }}
</div>
<div class="fieldWrapper">
  {{ form.cc_myself.as_field_group }}
</div>

By default Django uses the "django/forms/field.html" template which is designed for use with the default "django/forms/div.html" form style.

The default template can be customized by setting field_template_name in your project-level FORM_RENDERER:

from django.forms.renderers import TemplatesSetting


class CustomFormRenderer(TemplatesSetting):
    field_template_name = "field_snippet.html"

… or on a single field:

class MyForm(forms.Form):
    subject = forms.CharField(template_name="my_custom_template.html")
    ...

… or on a per-request basis by calling BoundField.render() and supplying a template name:

def index(request):
    form = ContactForm()
    subject = form["subject"]
    context = {"subject": subject.render("my_custom_template.html")}
    return render(request, "index.html", context)

Membangun bidang manual¶

More fine grained control over field rendering is also possible. Likely this will be in a custom field template, to allow the template to be written once and reused for each field. However, it can also be directly accessed from the field attribute on the form. For example:

{{ form.non_field_errors }}
<div class="fieldWrapper">
    {{ form.subject.errors }}
    <label for="{{ form.subject.id_for_label }}">Email subject:</label>
    {{ form.subject }}
</div>
<div class="fieldWrapper">
    {{ form.message.errors }}
    <label for="{{ form.message.id_for_label }}">Your message:</label>
    {{ form.message }}
</div>
<div class="fieldWrapper">
    {{ form.sender.errors }}
    <label for="{{ form.sender.id_for_label }}">Your email address:</label>
    {{ form.sender }}
</div>
<div class="fieldWrapper">
    {{ form.cc_myself.errors }}
    <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>
    {{ form.cc_myself }}
</div>

Complete <label> elements can also be generated using the label_tag(). For example:

<div class="fieldWrapper">
    {{ form.subject.errors }}
    {{ form.subject.label_tag }}
    {{ form.subject }}
</div>

<ul class="errorlist">
    <li>Sender is required.</li>
</ul>

{% if form.subject.errors %}
    <ol>
    {% for error in form.subject.errors %}
        <li><strong>{{ error|escape }}</strong></li>
    {% endfor %}
    </ol>
{% endif %}

<ul class="errorlist nonfield">
    <li>Generic validation error</li>
</ul>

Memutar terhadap bidang-bidang formulir¶

Jika anda sedang menggunakan HTML sama untuk setiap bidang formulir anda, anda dapat mengurangi kode ganda dengan memutari setiap bidang bergantian menggunakan putaran {% for %}:

{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
        {% if field.help_text %}
          <p class="help" id="{{ field.auto_id }}_helptext">
            {{ field.help_text|safe }}
          </p>
        {% endif %}
    </div>
{% endfor %}

Atribut berguna pada {{ field }} termasuk:

{{ field.errors }}

Outputs a <ul class="errorlist"> containing any validation errors corresponding to this field. You can customize the presentation of the errors with a {% for error in field.errors %} loop. In this case, each object in the loop is a string containing the error message.

{{ field.field }}

The Field instance from the form class that this BoundField wraps. You can use it to access Field attributes, e.g. {{ char_field.field.max_length }}.

{{ field.help_text }}

Teks bantuan apapun yang telah dikaitkan dengan bidang.

{{ field.html_name }}

The name of the field that will be used in the input element's name field. This takes the form prefix into account, if it has been set.

{{ field.id_for_label }}

ID yang akan digunakan untuk bidang ini (id_email di contoh diatas). Jika anda sedang membangun label secara manual, anda mungkin ingin menggunakan ini sebagai pengganti label_tag. Itu juga sangat berguna, sebagai contoh, jika anda mempunyai beberapa JavaScript berderet dan ingin menghindari kode keras ID bidang.

{{ field.is_hidden }}

This attribute is True if the form field is a hidden field and False otherwise. It's not particularly useful as a template variable, but could be useful in conditional tests such as:

{% if field.is_hidden %}
   {# Do something special #}
{% endif %}

{{ field.label }}

Label dari bidang, sebagai contoh Alamat surel.

{{ field.label_tag }}

The field's label wrapped in the appropriate HTML <label> tag. This includes the form's label_suffix. For example, the default label_suffix is a colon:

<label for="id_email">Email address:</label>

{{ field.legend_tag }}

Similar to field.label_tag but uses a <legend> tag in place of <label>, for widgets with multiple inputs wrapped in a <fieldset>.

{{ field.use_fieldset }}

This attribute is True if the form field's widget contains multiple inputs that should be semantically grouped in a <fieldset> with a <legend> to improve accessibility. An example use in a template:

{% if field.use_fieldset %}
  <fieldset>
  {% if field.label %}{{ field.legend_tag }}{% endif %}
{% else %}
  {% if field.label %}{{ field.label_tag }}{% endif %}
{% endif %}
{{ field }}
{% if field.use_fieldset %}</fieldset>{% endif %}

{{ field.value }}

Nilai bidang sebagai contoh someone@example.com.

{# Include the hidden fields #}
{% for hidden in form.hidden_fields %}
{{ hidden }}
{% endfor %}
{# Include the visible fields #}
{% for field in form.visible_fields %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}