Documentation
¶
Overview ¶
Package forms provides struct-based form definitions for creation, binding, validation, and field metadata extraction.
Index ¶
- type BoundField
- type Choice
- type ChoiceProvider
- type Cleanable
- type Form
- func (f *Form[T]) Bind(r *http.Request) bool
- func (f *Form[T]) Errors() *burrow.ValidationError
- func (f *Form[T]) Field(name string) (BoundField, bool)
- func (f *Form[T]) Fields() []BoundField
- func (f *Form[T]) Instance() *T
- func (f *Form[T]) IsValid() bool
- func (f *Form[T]) NonFieldErrors() []string
- func (f *Form[T]) WithContext(ctx context.Context) *Form[T]
- type Option
- func WithChoices[T any](field string, choices []Choice) Option[T]
- func WithChoicesFunc[T any](field string, fn func(context.Context) ([]Choice, error)) Option[T]
- func WithCleanFunc[T any](fn func(context.Context, *T) error) Option[T]
- func WithExclude[T any](fields ...string) Option[T]
- func WithInitial[T any](values map[string]any) Option[T]
- func WithReadOnly[T any](fields ...string) Option[T]
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BoundField ¶
type BoundField struct {
Name string // Go struct field name
FormName string // HTML field name (from form tag or lowercase)
Label string // translated from verbose_name/verbose tag
HelpText string // from help_text tag
Type string // "text", "number", "textarea", "select", "checkbox", "date", "email", "hidden", "subform"
Value any // current value
Required bool // from validate:"required"
ReadOnly bool // render as plain text, not editable
Choices []Choice // static or dynamic, with translated labels
SubFields []BoundField // populated when Type == "subform"
Errors []string // field-specific error messages
}
BoundField provides field metadata for template rendering.
Label is read from the verbose_name/verbose struct tag and piped through i18n.T by [extractFields], so the English Label doubles as the i18n message ID. Templates render {{ .Label }} as-is — no {{ t }} wrapping needed. See docs/guide/i18n.md for the Label-as-key convention.
When Type is "subform", SubFields holds the nested struct's BoundFields (one level of recursion). Their FormName uses the parent.child convention (e.g. "profile.name"), which matches the burrow.Bind decoder.
type Choice ¶
Choice represents a single option in a select or radio field. Label is piped through i18n.T by [extractFields], following the same Label-as-key convention as BoundField.Label.
type ChoiceProvider ¶
ChoiceProvider may be implemented by form structs that provide dynamic choices for select fields. The field parameter is the Go struct field name.
type Cleanable ¶
Cleanable may be implemented by form structs for cross-field validation. Clean is called after per-field validation passes. The context carries request-scoped data (e.g. i18n localizer). It may return a *burrow.ValidationError to report field-level or non-field errors.
type Form ¶
type Form[T any] struct { // contains filtered or unexported fields }
Form holds form state for a struct type T.
func FromModel ¶
FromModel creates a form pre-populated from an existing model instance. If instance is nil, creates an empty form (for create mode).
func (*Form[T]) Bind ¶
Bind decodes the request body into the form struct, validates it, and runs any Cleanable.Clean method. Returns true if the form is valid.
func (*Form[T]) Errors ¶
func (f *Form[T]) Errors() *burrow.ValidationError
Errors returns the validation errors, or nil if valid.
func (*Form[T]) Field ¶
func (f *Form[T]) Field(name string) (BoundField, bool)
Field returns a single BoundField by Go struct field name.
func (*Form[T]) Fields ¶
func (f *Form[T]) Fields() []BoundField
Fields returns all visible BoundFields in struct field order. Validation errors are auto-translated via i18n.TData.
func (*Form[T]) Instance ¶
func (f *Form[T]) Instance() *T
Instance returns the bound/populated struct.
func (*Form[T]) NonFieldErrors ¶
NonFieldErrors returns errors not tied to a specific field (from Clean).
func (*Form[T]) WithContext ¶ added in v0.22.0
WithContext sets the context used when rendering the form's fields. Bind already does this from the http.Request, so call WithContext only when rendering a form outside the request lifecycle (background jobs, CLI, templates rendered from a goroutine). The context's locale drives label/choice translation in Fields.
type Option ¶
type Option[T any] func(*formConfig[T])
Option configures a Form during construction.
func WithChoices ¶
WithChoices sets static choices for a field (by Go struct field name).
func WithChoicesFunc ¶
WithChoicesFunc sets a dynamic choice provider for a field (by Go struct field name).
func WithCleanFunc ¶ added in v0.5.0
WithCleanFunc sets a closure-based clean function for cross-field validation that needs external dependencies (e.g. database access). The function runs after per-field validation and Clean() (if implemented). It may return a *burrow.ValidationError for field-level errors or a plain error for non-field errors.
func WithExclude ¶
WithExclude excludes named fields (by Go struct field name) from the form.
func WithInitial ¶
WithInitial sets initial field values by form name.
func WithReadOnly ¶ added in v0.5.0
WithReadOnly marks named fields (by Go struct field name) as read-only. Read-only fields are rendered as plain text instead of input elements.
Source Files