Formulir membangun API

Widgets formulir Django dibangun menggunakan Django's template engines system.

Pengolahan membangun formulir dapat disesuaikan pada beberapa tingkat:

  • Widget dapat menentukan nama-nama cetakan penyesuaian.
  • Formulir dan widget dapat menentukan kelas-kelas pembangun penyesuaian.
  • Sebuah cetakan widget dapat ditimpa oleh sebuah proyek. (Menggunakan kembali aplikasi tertentu jangan menimpa cetakan siap-pakai karena mereka mungkin bertentangan dengan cetakan-cetakan penyesuaian proyek.)

Tingkat-rendah pembangun API

Pembangunan dari cetakan formulir dikendalikan oleh kelas pembangun penyesuaian. Sebuah pembangun penyesuaian dapat ditentukan dengan memperbaharui pengaturan FORM_RENDERER. Awalan itu pada 'django.forms.renderers.DjangoTemplates'.

By specifying a custom form renderer and overriding form_template_name you can adjust the default form markup across your project from a single place.

You can also provide a custom renderer per-form or per-widget by setting the Form.default_renderer attribute or by using the renderer argument of Form.render(), or Widget.render().

Matching points apply to formset rendering. See Menggunakan sebuah formset dalam tampilan dan cetakan for discussion.

Gunakan satu dari built-in template form renderers atau menerapkan anda sendiri. Pembangun penyesuaian harus menerapkan sebuah metode render(template_name, context, request=None). Itu harus mengembalikan sebuah cetakan terbangun (sebagai string) atau memunculkan TemplateDoesNotExist.

class BaseRenderer

The base class for the built-in form renderers.

form_template_name
New in Django 4.1.

The default name of the template to use to render a form.

Defaults to "django/forms/default.html", which is a proxy for "django/forms/table.html".

Ditinggalkan sejak versi 4.1.

The "django/forms/default.html" template is deprecated and will be removed in Django 5.0. The default will become "django/forms/div.html" at that time.

formset_template_name
New in Django 4.1.

The default name of the template to use to render a formset.

Defaults to "django/forms/formsets/default.html", which is a proxy for "django/forms/formsets/table.html".

Ditinggalkan sejak versi 4.1.

The "django/forms/formset/default.html" template is deprecated and will be removed in Django 5.0. The default will become "django/forms/formset/div.html" template.

get_template(template_name)

Subclasses must implement this method with the appropriate template finding logic.

render(template_name, context, request=None)

Renders the given template, or raises TemplateDoesNotExist.

Pembangun formulir cetakan-siap-pakai

DjangoTemplates

class DjangoTemplates

Pembangun ini menggunakan mesin DjangoTemplates berdiri sendiri (tidak terhubung ke apa yang anda telah konfigurasikan dalam pengaturan TEMPLATES). Itu memuat cetakan-cetakan pertama dari direktori cetakan formulir siap-pakai dalam django/forms/templates dan kemudian dari direktori cetakan aplikasi terpasang menggunakan pemuat app_directories.

Jika anda ingin membangun cetakan dengan penyesuaian dari pengaturan TEMPLATES anda, seperti pengeolah konteks sebagai contoh, gunakan pembangun TemplatesSetting.

class DjangoDivFormRenderer
New in Django 4.1.

Subclass of DjangoTemplates that specifies form_template_name and formset_template_name as "django/forms/div.html" and "django/forms/formset/div.html" respectively.

This is a transitional renderer for opt-in to the new <div> based templates, which are the default from Django 5.0.

Apply this via the FORM_RENDERER setting:

FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"

Once the <div> templates are the default, this transitional renderer will be deprecated, for removal in Django 6.0. The FORM_RENDERER declaration can be removed at that time.

Jinja2

class Jinja2

Pembangun ini adalah sama seperti pembangun DjangoTemplates kecuali bahwa itu menggunakan sebuah backend Jinja2. Cetakan-cetakan untuk widget siap-pakai ditempatkan dalam django/forms/jinja2 dan aplikasi terpasang dapat menyediakan cetakan dalam direktori jinja2.

To use this backend, all the forms and widgets in your project and its third-party apps must have Jinja2 templates. Unless you provide your own Jinja2 templates for widgets that don't have any, you can't use this renderer. For example, django.contrib.admin doesn't include Jinja2 templates for its widgets due to their usage of Django template tags.

class Jinja2DivFormRenderer
New in Django 4.1.

A transitional renderer as per DjangoDivFormRenderer above, but subclassing Jinja2 for use with the Jinja2 backend.

Apply this via the FORM_RENDERER setting:

FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"

TemplatesSetting

class TemplatesSetting

This renderer gives you complete control of how form and widget templates are sourced. It uses get_template() to find templates based on what's configured in the TEMPLATES setting.

Using this renderer along with the built-in templates requires either:

  • 'django.forms' in INSTALLED_APPS dan setidaknya satu mesin dengan APP_DIRS=True.

  • Adding the built-in templates directory in DIRS of one of your template engines. To generate that path:

    import django
    django.__path__[0] + '/forms/templates'  # or '/forms/jinja2'
    

Menggunakan pembangun ini membutuhkan anda untuk memastikan cetakan formulir proyek anda butuhkan dapat ditempatkan.

Context available in formset templates

New in Django 4.0.

Formset templates receive a context from BaseFormSet.get_context(). By default, formsets receive a dictionary with the following values:

  • formset: The formset instance.

Context available in form templates

New in Django 4.0.

Form templates receive a context from Form.get_context(). By default, forms receive a dictionary with the following values:

  • form: The bound form.
  • fields: All bound fields, except the hidden fields.
  • hidden_fields: All hidden bound fields.
  • errors: All non field related or hidden field related form errors.

Konteks tersedia dalam cetakan widget

Cetakan widget menerima sebuah konteks dari Widget.get_context(). Secara awalan, widget menerima sebuah nilai tunggal dalam konteks, widget. Ini adalah sebuah dictionary yang mengandung nilai-nilai seperti:

  • name
  • value
  • attrs
  • is_hidden
  • template_name

Beberapa widget menambah informasi lebih lanjut pada konteks. Sebagai contoh, semua widget yang subkelas Input menentukan widget['type'] dan MultiWidget menentukan widget['subwidgets'] untuk tujuan perulangan.

Overriding built-in formset templates

New in Django 4.0.

BaseFormSet.template_name

To override formset templates, you must use the TemplatesSetting renderer. Then overriding widget templates works the same as overriding any other template in your project.

Overriding built-in form templates

New in Django 4.0.

Form.template_name

To override form templates, you must use the TemplatesSetting renderer. Then overriding widget templates works the same as overriding any other template in your project.

Menimpa cetakan widget siap-pakai

Setiap widget mempunyai sebuah atribut template_name dengan sebuah nilai seperti input.html. Cetakan widget siap-pakai disimpan dalam jalur django/forms/widgets. Anda dapat menyediakan cetakan penyesuaian untuk input.html dengan menentukan django/forms/widgets/input.html, sebagai contoh. Lihat Widget pasang tetap untuk nama dari setiap cetakan widget.

Untuk menimpa cetakan widget, anda harus menggunakan pembangun TemplatesSetting. Kemudian menimpa cetakan widget bekerja the same as menimpa cetakan lain apapun dalam proyek anda.