govuk frontend wtf

GOV.UK Frontend WTForms Widgets

Gov.uk Frontend WTForms ist ein Community -Tool des Gov.uk -Designsystems. Das Design -Systemteam ist nicht dafür verantwortlich und kann Sie nicht bei der Verwendung unterstützen. Wenden Sie sich direkt an die Betreuer, wenn Sie Hilfe benötigen oder eine Funktion anfordern möchten.

Dieses Repository enthält einen Satz von WTForms -Widgets, mit denen WTForm -Felder mithilfe von GOV.UK -Frontend -Komponenten -Styling rendern. Dies geschieht mit Jinja Macros vom Gov.uk Frontend Jinja Port des ursprünglichen Gov.uk Frontend Nunjucks Makros. Diese werden mit Gov.uk Frontend-Veröffentlichungen auf dem neuesten Stand gehalten, gründlich getestet und erzeugen 100% äquivalentes Aufschlag.

Dieser Ansatz macht auch die zugeordneten Fehlermeldungen an der entsprechenden Stelle, zeigt die Fehlerzusammenfassungskomponente oben auf der Seite an und legt alle verwandten ARIA -Attribute fest. Das Hinzufügen des entsprechenden Widgets zu Ihrer vorhandenen Python -Klasse sowie weitaus einfachere Vorlagen erleichtert es schnell und einfach, vollständig gov.uk -konforme Formulare zu produzieren.

Wenn Sie eine vollständig vorgestellte Flask -App erstellen möchten, die sich in Gov.uk Frontend Jinja und Gov.uk Frontend WTForms integriert, verwenden Sie bitte das Repository Gov.uk Frontend Flask Vorlage, um Ihre App zu generieren.

Wie man benutzt

Weitere detailliertere Beispiele finden Sie im Quellcode für Demo -Apps.

Stellen Sie nach dem Ausführen pip install govuk-frontend-wtf sicher, dass Sie Jinja mitteilen, wo die Vorlagen die Verwendung des PackageLoader laden, WTFormsHelpers registrieren und dann eine Umgebungsvariable für SECRET_KEY festlegen.

app/__init__.py :

 from flask import Flask
from govuk_frontend_wtf . main import WTFormsHelpers
from jinja2 import ChoiceLoader , PackageLoader , PrefixLoader

app = Flask ( __name__ )
app . config [ "SECRET_KEY" ] = os . environ . get ( "SECRET_KEY" )

app . jinja_loader = ChoiceLoader (
    [
        PackageLoader ( "app" ),
        PrefixLoader (
            {
                "govuk_frontend_jinja" : PackageLoader ( "govuk_frontend_jinja" ),
                "govuk_frontend_wtf" : PackageLoader ( "govuk_frontend_wtf" ),
            }
        ),
    ]
)

WTFormsHelpers ( app )

Importieren und fügen Sie das relevante Widget in jedes Feld in Ihre Formklasse ein (siehe Tabelle unten). Beachten Sie, dass in diesem Beispiel widget=GovTextInput() der einzige Unterschied zu einer Standard-Flask-WTF-Form Definition ist.

app/forms.py :

 from flask_wtf import FlaskForm
from govuk_frontend_wtf . wtforms_widgets import GovSubmitInput , GovTextInput
from wtforms import StringField , SubmitField
from wtforms . validators import Email , InputRequired , Length


class ExampleForm ( FlaskForm ):
    email_address = StringField (
        "Email address" ,
        widget = GovTextInput (),
        validators = [
            InputRequired ( message = "Enter an email address" ),
            Length ( max = 256 , message = "Email address must be 256 characters or fewer" ),
            Email ( message = "Enter an email address in the correct format, like [email protected]" ),
        ],
        description = "We’ll only use this to send you a receipt" ,
    )

    submit = SubmitField ( "Continue" , widget = GovSubmitInput ())

Erstellen Sie eine Route, um Ihr Formular und Ihre Vorlage zu bedienen.

app/routes.py :

 from flask import redirect , render_template , url_for

from app import app
from app . forms import ExampleForm

@ app . route ( "/" )
def index ():
    return render_template ( "index.html" )


@ app . route ( "/example-form" , methods = [ "GET" , "POST" ])
def example ():
    form = ExampleForm ()
    if form . validate_on_submit ():
        return redirect ( url_for ( "index" ))
    return render_template ( "example_form.html" , form = form )

Setzen Sie schließlich in Ihrer Vorlage den Seitentitel angemessen, wenn es eine Formularvalidierungsfehler gemäß GOV.UK -Entwurfssystem -Anleitung gibt. Fügen Sie die govukErrorSummary() -Komponente zu Beginn des content ein. Übergeben Sie die Parameter in einem Wörterbuch an Ihr Formularfeld gemäß den zugehörigen Komponenten -Makrooptionen.

app/templates/example_form.html :

{% extends "base.html" %}

{%- from 'govuk_frontend_jinja/components/error-summary/macro.html' import govukErrorSummary -%}

{% block pageTitle %}{%- if form and form.errors %}Error: {% endif -%}Example form – GOV.UK Frontend WTForms Demo{% endblock %}

{% block content %}
< div class =" govuk-grid-row " >
    < div class =" govuk-grid-column-two-thirds " >
        {% if form.errors %}
            {{ govukErrorSummary(wtforms_errors(form)) }}
        {% endif %}

        < h1 class =" govuk-heading-xl " > Example form </ h1 >

        < form action ="" method =" post " novalidate >
            {{ form.csrf_token }}
            
            {{ form.email_address(params={
              'type': 'email',
              'autocomplete': 'email',
              'spellcheck': false
            }) }}
            
            {{ form.submit }}
        </ form >
    </ div >
</ div >
{% endblock %}

Widgets

Die verfügbaren Widgets und ihre entsprechenden Feldtypen von Flask-WTF sind wie folgt:

WTForms Feld	Gov. UK Widget (en)	Notizen
Booleanfield	GovCheckBoxInput
Datefield	GovdateInput
DateTimeField	GovdateInput
Dezimalfield	Govtextinput
Dateifield	GovFileInput
Multiple filefield	GovFileInput (multiple = true)	Beachten Sie, dass Sie multiple=True angeben müssen, wenn Sie das Widget in Ihrer Formklasse aufrufen. Nicht , wenn Sie es in der Jinja -Vorlage rendern.
Floatfield	Govtextinput
Integerfield	Govtextinput	Verwenden Sie params , um einen type anzugeben, wenn Sie HTML5 -Zahlenelemente verwenden müssen. Dies wird nicht automatisch geschehen.
Passwortfield	GovpasswordInput
Radiofield	Govradioinput
SelectField	GovSelect
SelectMultiplefield	GovCheckboxeInput	Beachten Sie, dass dies Kontrollkästchen als <select multiple> Elemente verleihen.
Sublefield	GovSubmitinput
Stringfield	Govtextinput
Textefeld	GovtextArea, GovaracterCount

Um Dinge wie E -Mail -Felder mit GovTextInput zu generieren, müssen Sie beim Rendern wie folgt zusätzliche Parameter übergeben:

{{ form.email_address(params={'type': 'email', 'autocomplete': 'email', 'spellcheck': false}) }}

Die Tests ausführen

python3 -m venv venv
source venv/bin/activate
pip install -r tests/requirements.txt
pytest --cov=govuk_frontend_wtf --cov-report=term-missing --cov-branch

Versioning

Wir verwenden Semver für die Versionierung. Die verfügbaren Versionen finden Sie in den Tags in diesem Repository.

Wie man beiträgt

Wir begrüßen den Beitrag aus der Gemeinschaft. Wenn Sie zu diesem Projekt beitragen möchten, überprüfen Sie bitte die Richtlinien für Verhaltens- und Beitragskodex.

Mitwirkende

• Matt Shaw (Primärerbauer)
• Andy Mantell (Originalautor)

Siehe die vollständige Liste der Mitwirkenden auf GitHub

Unterstützung

Diese Software wird ohne Garantie "as-is" bereitgestellt. Die Unterstützung wird von den Wartenden und der Open -Source -Community auf "Best Bemühungen" bereitgestellt.

Wenn Sie ein Beamter sind, können Sie sich bei der britischen Regierung Digital Slack Workspace anmelden, um die oben aufgeführten Wartenden und die Community von Personen zu kontaktieren, die dieses Projekt im #govuk-design-Systemkanal verwenden.

Andernfalls finden Sie in den Beitragsrichtlinien, wie Sie einen Fehlerbericht oder eine Feature -Anfrage erhöhen können.