API för rendering av formulär

Djangos formulärwidgets renderas med hjälp av Djangos template engines system.

Renderingsprocessen för formulär kan anpassas på flera nivåer:

• Widgets kan ange egna mallnamn.

• Formulär och widgetar kan ange egna renderarklasser.

• En widgets mall kan åsidosättas av ett projekt. (Återanvändbara program bör vanligtvis inte åsidosätta inbyggda mallar eftersom de kan komma i konflikt med ett projekts egna mallar)

API för rendering på låg nivå

Renderingen av formulärmallar styrs av en anpassningsbar renderingsklass. En anpassad renderare kan anges genom att uppdatera inställningen FORM_RENDERER. Standardvärdet är 'django.forms.renderers.DjangoTemplates'.

Genom att ange en anpassad formulärrenderare och åsidosätta form_template_name kan du justera standardmarkeringen för formulär i hela projektet från ett enda ställe.

Du kan också ange en anpassad renderare per formulär eller per widget genom att ange attributet Form.default_renderer eller genom att använda argumentet renderer i Form.render() eller Widget.render().

Matchningspunkter gäller för rendering av formulär. Se Använda en formulärsats i vyer och mallar för diskussion.

Använd en av :ref:inbyggda renderare för mallformulär <built-in-template-form-renderers>` eller implementera din egen. Anpassade renderare måste implementera en ``render(template_name, context, request=None) metod. Den bör returnera en renderad mall (som en sträng) eller ge upphov till TemplateDoesNotExist.

class BaseRenderer[source]

Basklass för de inbyggda formulärrenderingarna.

form_template_name

Standardnamnet på den mall som ska användas för att rendera ett formulär.

Standard är mallen "django/forms/div.html".

formset_template_name

Standardnamnet på den mall som ska användas för att återge en formulärsats.

Standard är mallen "django/forms/formsets/div.html".

field_template_name

Standardnamnet på den mall som används för att rendera en BoundField.

Standardvärde är "django/forms/field.html"

bound_field_class

New in Django 5.2.

Standardklassen som används för att representera formulärfält i hela projektet.

Standardvärdet är BoundField class.

Detta kan anpassas ytterligare med hjälp av Form.bound_field_class för överstyrning per formulär, eller Field.bound_field_class för överstyrning per fält.

get_template(template_name)[source]

Underklasser måste implementera denna metod med lämplig logik för att hitta mallar.

render(template_name, context, request=None)[source]

Renderar den angivna mallen, eller ger upphov till TemplateDoesNotExist.

Inbyggda formulärmallar för mallar

DjangoMallar

class DjangoTemplates[source]

Denna renderare använder en fristående DjangoTemplates-motor (utan koppling till vad du kan ha konfigurerat i TEMPLATES-inställningen). Den laddar mallar först från den inbyggda katalogen för formulärmallar i django/forms/templates och sedan från de installerade programmens mallkataloger med hjälp av app_directories.

Om du vill rendera mallar med anpassningar från din inställning TEMPLATES, t.ex. kontextprocessorer, använder du renderingsprogrammet TemplatesSetting.

class DjangoDivFormRenderer

Deprecated since version 5.0.

Aliaset för DjangoTemplates.

Jinja2

class Jinja2[source]

Denna renderare är densamma som DjangoTemplates renderare förutom att den använder en Jinja2 backend. Mallar för de inbyggda widgetarna finns i django/forms/jinja2 och installerade appar kan tillhandahålla mallar i en jinja2-katalog.

För att kunna använda den här backend måste alla formulär och widgetar i ditt projekt och dess tredjepartsappar ha Jinja2-mallar. Om du inte tillhandahåller dina egna Jinja2-mallar för widgetar som inte har några, kan du inte använda den här renderingen. Till exempel: inkluderar django.contrib.admin inte Jinja2-mallar för sina widgets på grund av deras användning av Django-malltaggar.

class Jinja2DivFormRenderer

Deprecated since version 5.0.

Alias för Jinja2.

TemplatesSetting

class TemplatesSetting[source]

Denna renderare ger dig fullständig kontroll över hur formulär- och widgetmallar hämtas. Den använder get_template() för att hitta mallar baserat på vad som konfigureras i inställningen TEMPLATES.

För att använda denna renderare tillsammans med de inbyggda mallarna krävs antingen:

• 'django.forms' i INSTALLED_APPS och minst en motor med APP_DIRS=True.

• Lägga till den inbyggda mallkatalogen i DIRS för en av dina mallmotorer. För att generera den sökvägen:

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

För att kunna använda den här renderaren måste du se till att de formulärmallar som ditt projekt behöver kan hittas.

Kontext tillgänglig i formulärmallar

Formset-mallar får en kontext från BaseFormSet.get_context(). Som standard får formulär en ordbok med följande värden:

• formulär: Instansen för formuläret.

Kontext tillgänglig i formulärmallar

Formulärmallar får en kontext från Form.get_context(). Som standard får formulär en ordbok med följande värden:

• ”Formulär”: Det bundna formuläret.

• fält: Alla bundna fält, utom de dolda fälten.

• hidden_fields: Alla dolda bundna fält.

• fel: Alla formulärfel som inte är fältrelaterade eller som är relaterade till dolda fält.

Sammanhang tillgängligt i fältmallar

Fältmallar får en kontext från BoundField.get_context(). Som standard får fält en ordbok med följande värden:

• fält: Klassen:~django.forms.BoundField.

Kontext tillgänglig i widgetmallar

Widgetmallar får en kontext från Widget.get_context(). Som standard får widgetar ett enda värde i kontexten, widget. Detta är en ordbok som innehåller värden som t.ex:

• namn

• värde

• attrs

• is_hidden

• template_name

Vissa widgetar lägger till ytterligare information i sammanhanget. Till exempel: definierar alla widgetar som är underklassade Input widget['type'] och MultiWidget definierar widget['subwidgets'] för loopingändamål.

Åsidosätta inbyggda mallar för formulär

BaseFormSet.template_name

För att åsidosätta formulärmallar måste du använda renderingen TemplatesSetting. Då fungerar åsidosättande av formulärmallar på samma sätt som åsidosättande av alla andra mallar i ditt projekt.

Åsidosätta inbyggda formulärmallar

Form.template_name

För att åsidosätta formulärmallar måste du använda TemplatesSetting-renderaren. Då fungerar åsidosättande av formulärmallar på samma sätt som åsidosättande av alla andra mallar i ditt projekt.

Åsidosätta inbyggda fältmallar

Field.template_name

För att åsidosätta fältmallar måste du använda TemplatesSetting-renderaren. Då fungerar åsidosättande av fältmallar på samma sätt som åsidosättande av alla andra mallar i ditt projekt.

Åsidosätta inbyggda widgetmallar

Varje widget har ett attribut template_name med ett värde som till exempel input.html. Inbyggda widgetmallar lagras i sökvägen django/forms/widgets. Du kan tillhandahålla en anpassad mall för input.html genom att definiera django/forms/widgets/input.html, till exempel. Se inbyggda widgetar för namnet på varje widgets mall.

För att åsidosätta widgetmallar måste du använda TemplatesSetting-renderaren. Då fungerar åsidosättande av widgetmallar på samma sätt som åsidosättande av alla andra mallar i ditt projekt.