Documentation
¶
Overview ¶
Package form holds the typed fields of a page's forms. For <ssr:form name="add"> in a template, aicoded generate writes FormAddValues: a BaseFormValues and one field for each <ssr:input>, <ssr:select> and <ssr:textarea> in the form, such as Input[string], Select[int] or File. Generated code reads the posted values into the fields; the page's data provider sets initial values and options and reads the results in two hooks:
- InitAdd runs every time the page shows the form, and on a post after the form's token is checked and before the posted values are read. Set default values with SetValue and the options of every select with SetOptions.
- ProcessAdd runs only for the posted form, and only when every field is valid: required fields are filled, numbers parse and each select value is one of its enabled options. Check there what only the server knows, such as whether a login is taken. Set an error on a field with its SetError, or on the whole form with BaseFormValues.SetError, and return nil to show the form again with the errors; return web.Redirect to show the result.
A posted form is at most 32 MiB. A form with a file field is posted as multipart/form-data; read an uploaded file with the Open method of its FileHeader.
Read more in the guide docs/guides/forms.md and the task docs/tasks/add-form.md, which aicoded explain and the MCP tool howto print as guides/forms and tasks/add-form.
Index ¶
- Constants
- func IsMultipart(r *http.Request) bool
- type BaseFormValues
- func (f *BaseFormValues) GetError() string
- func (f *BaseFormValues) HasError() bool
- func (f *BaseFormValues) ID() string
- func (f *BaseFormValues) IsValidated() bool
- func (f *BaseFormValues) MarkValidated()
- func (f *BaseFormValues) Prepare(id, token string)
- func (f *BaseFormValues) SetElements(elements []Element)
- func (f *BaseFormValues) SetError(err string)
- func (f *BaseFormValues) Token() string
- type Element
- type ElementValueType
- type File
- type FileHeader
- type FileMultiple
- func (e *FileMultiple) GetError() string
- func (e *FileMultiple) GetValue() []*FileHeader
- func (e *FileMultiple) HasError() bool
- func (e *FileMultiple) IsNotNull() bool
- func (e *FileMultiple) Process(r *http.Request, name string, isMultipart, isRequired bool)
- func (e *FileMultiple) SetError(err string)
- type Input
- func (e *Input[T]) GetError() string
- func (e *Input[T]) GetFormValue() string
- func (e *Input[T]) GetValue() T
- func (e *Input[T]) HasError() bool
- func (e *Input[T]) IsNotNull() bool
- func (e *Input[T]) Process(r *http.Request, name string, isMultipart, isRequired bool)
- func (e *Input[T]) SetError(err string)
- func (e *Input[T]) SetValue(v T)
- type InputMultiple
- func (e *InputMultiple[T]) GetError() string
- func (e *InputMultiple[T]) GetFormValue() string
- func (e *InputMultiple[T]) GetValue() map[T]struct{}
- func (e *InputMultiple[T]) HasError() bool
- func (e *InputMultiple[T]) IsNotNull() bool
- func (e *InputMultiple[T]) Process(r *http.Request, name string, isMultipart, isRequired bool)
- func (e *InputMultiple[T]) SetError(err string)
- func (e *InputMultiple[T]) SetValue(v map[T]struct{})
- type Select
- func (e *Select[T]) GetError() string
- func (e *Select[T]) GetOptions() []SelectOptionElement[T]
- func (e *Select[T]) GetValue() T
- func (e *Select[T]) HasError() bool
- func (e *Select[T]) IsNotNull() bool
- func (e *Select[T]) Process(r *http.Request, name string, isMultipart, isRequired bool)
- func (e *Select[T]) SetError(err string)
- func (e *Select[T]) SetOptions(o []SelectOptionElement[T])
- func (e *Select[T]) SetValue(v T)
- type SelectMultiple
- func (e *SelectMultiple[T]) GetError() string
- func (e *SelectMultiple[T]) GetOptions() []SelectOptionElement[T]
- func (e *SelectMultiple[T]) GetValue() map[T]struct{}
- func (e *SelectMultiple[T]) HasError() bool
- func (e *SelectMultiple[T]) IsNotNull() bool
- func (e *SelectMultiple[T]) Process(r *http.Request, name string, isMultipart, isRequired bool)
- func (e *SelectMultiple[T]) SetError(err string)
- func (e *SelectMultiple[T]) SetOptions(o []SelectOptionElement[T])
- func (e *SelectMultiple[T]) SetValue(v map[T]struct{})
- type SelectOption
- type SelectOptionElement
- type SelectOptionGroup
- type Textarea
- func (e *Textarea) GetError() string
- func (e *Textarea) GetValue() string
- func (e *Textarea) HasError() bool
- func (e *Textarea) IsNotNull() bool
- func (e *Textarea) Process(r *http.Request, name string, isMultipart, isRequired bool)
- func (e *Textarea) SetError(err string)
- func (e *Textarea) SetValue(v string)
Examples ¶
Constants ¶
const ( // MessageRequiredField is the error of a required field left empty. MessageRequiredField = "This field is required" // MessageInvalidOption is the error of a select whose submitted value is not one of its // options. MessageInvalidOption = "Choose one of the options" // MultipartFormData is the content type of a form that carries files. MultipartFormData = "multipart/form-data" )
Variables ¶
This section is empty.
Functions ¶
func IsMultipart ¶
IsMultipart reports whether r carries a multipart/form-data body.
Generated code only.
Types ¶
type BaseFormValues ¶
type BaseFormValues struct {
// contains filtered or unexported fields
}
BaseFormValues is what every form has besides its fields: its id, the viewer's form token, a form-wide error and whether the posted values were checked.
func (*BaseFormValues) GetError ¶
func (f *BaseFormValues) GetError() string
GetError returns the error about the form as a whole.
func (*BaseFormValues) HasError ¶
func (f *BaseFormValues) HasError() bool
HasError reports whether the form or any of its fields has an error.
func (*BaseFormValues) ID ¶
func (f *BaseFormValues) ID() string
ID returns the form's id, as posted in the hidden input web.FormField.
func (*BaseFormValues) IsValidated ¶
func (f *BaseFormValues) IsValidated() bool
IsValidated reports whether the form was submitted and its values checked.
func (*BaseFormValues) MarkValidated ¶
func (f *BaseFormValues) MarkValidated()
MarkValidated records that the posted values were checked. Generated code calls it.
Generated code only.
func (*BaseFormValues) Prepare ¶
func (f *BaseFormValues) Prepare(id, token string)
Prepare sets the form's id and the viewer's token, which the rendered form carries in hidden inputs. Generated code calls it.
Generated code only.
func (*BaseFormValues) SetElements ¶
func (f *BaseFormValues) SetElements(elements []Element)
SetElements sets the fields HasError looks at. Generated code calls it.
Generated code only.
func (*BaseFormValues) SetError ¶
func (f *BaseFormValues) SetError(err string)
SetError sets an error about the form as a whole.
func (*BaseFormValues) Token ¶
func (f *BaseFormValues) Token() string
Token returns the token posted in the hidden input web.CSRFField.
type ElementValueType ¶
type ElementValueType interface {
string | int | int8 | int16 | int32 | int64 | uint | uint8 | uint16 | uint32 | uint64 | float32 | float64 | bool
}
ElementValueType lists the value types a form field can have.
type File ¶
type File struct {
// contains filtered or unexported fields
}
File is a file <input> field.
func (*File) GetValue ¶
func (e *File) GetValue() *FileHeader
GetValue returns the uploaded file, or nil.
type FileHeader ¶
type FileHeader struct {
*multipart.FileHeader
}
FileHeader describes an uploaded file. Open reads its content.
type FileMultiple ¶
type FileMultiple struct {
// contains filtered or unexported fields
}
FileMultiple is a file <input multiple> field.
func (*FileMultiple) GetError ¶
func (e *FileMultiple) GetError() string
GetError returns the field's error.
func (*FileMultiple) GetValue ¶
func (e *FileMultiple) GetValue() []*FileHeader
GetValue returns the uploaded files.
func (*FileMultiple) HasError ¶
func (e *FileMultiple) HasError() bool
HasError reports whether the field has an error.
func (*FileMultiple) IsNotNull ¶
func (e *FileMultiple) IsNotNull() bool
IsNotNull reports whether Process ran for a multipart form, even one without files.
func (*FileMultiple) Process ¶
func (e *FileMultiple) Process(r *http.Request, name string, isMultipart, isRequired bool)
Process reads the field from the parsed form in r. Generated code calls it.
Generated code only.
func (*FileMultiple) SetError ¶
func (e *FileMultiple) SetError(err string)
SetError sets the field's error.
type Input ¶
type Input[T ElementValueType] struct { // contains filtered or unexported fields }
Input is a single-valued <input> field.
func (*Input[T]) GetFormValue ¶
GetFormValue returns the text posted for the field, so a value that did not parse can be shown again.
func (*Input[T]) Process ¶
Process reads the field from the parsed form in r. Generated code calls it.
Generated code only.
func (*Input[T]) SetError ¶
SetError sets the field's error.
Example ¶
Process<Form> runs only when every field is valid, so it checks what only the server knows and sets the error that the page shows next to the field.
package main
import (
"fmt"
"aicoded.dev/framework/web/form"
)
func main() {
taken := map[string]bool{"alice": true, "bob": true}
var login form.Input[string] // a field of the generated Form<Name>Values
login.SetValue("alice") // as the viewer posted it
if taken[login.GetValue()] {
login.SetError("This login is taken.")
}
fmt.Println(login.HasError(), login.GetError())
}
Output: true This login is taken.
type InputMultiple ¶
type InputMultiple[T ElementValueType] struct { // contains filtered or unexported fields }
InputMultiple is an <input> field that takes several values, such as a group of checkboxes sharing a name.
func (*InputMultiple[T]) GetError ¶
func (e *InputMultiple[T]) GetError() string
GetError returns the field's error.
func (*InputMultiple[T]) GetFormValue ¶
func (e *InputMultiple[T]) GetFormValue() string
GetFormValue returns "": a multi-valued field keeps no posted text.
func (*InputMultiple[T]) GetValue ¶
func (e *InputMultiple[T]) GetValue() map[T]struct{}
GetValue returns the field's values.
func (*InputMultiple[T]) HasError ¶
func (e *InputMultiple[T]) HasError() bool
HasError reports whether the field has an error.
func (*InputMultiple[T]) IsNotNull ¶
func (e *InputMultiple[T]) IsNotNull() bool
IsNotNull reports whether the field has values, set or posted.
func (*InputMultiple[T]) Process ¶
func (e *InputMultiple[T]) Process(r *http.Request, name string, isMultipart, isRequired bool)
Process reads the field from the parsed form in r. Generated code calls it.
Generated code only.
func (*InputMultiple[T]) SetError ¶
func (e *InputMultiple[T]) SetError(err string)
SetError sets the field's error.
func (*InputMultiple[T]) SetValue ¶
func (e *InputMultiple[T]) SetValue(v map[T]struct{})
SetValue sets the field's values.
type Select ¶
type Select[T ElementValueType] struct { // contains filtered or unexported fields }
Select is a single-valued <select> field. A posted value must be one of its options.
func (*Select[T]) GetOptions ¶
func (e *Select[T]) GetOptions() []SelectOptionElement[T]
GetOptions returns the field's options.
func (*Select[T]) Process ¶
Process reads the field from the parsed form in r. Generated code calls it after the form's options are set.
Generated code only.
func (*Select[T]) SetOptions ¶
func (e *Select[T]) SetOptions(o []SelectOptionElement[T])
SetOptions sets the options a viewer can choose from.
Example ¶
Init<Form> sets the options of a select, alone or in groups. A viewer can post only the value of an enabled option; any other value gets form.MessageInvalidOption.
package main
import (
"fmt"
"slices"
"aicoded.dev/framework/web/form"
)
func main() {
var team form.Select[string] // a field of the generated Form<Name>Values
team.SetOptions([]form.SelectOptionElement[string]{
form.SelectOption[string]{Value: "ops", Label: "Operations"},
form.SelectOptionGroup[string]{Label: "Sales", Options: []form.SelectOptionElement[string]{
form.SelectOption[string]{Value: "sales-eu", Label: "Europe"},
form.SelectOption[string]{Value: "sales-us", Label: "Americas", Disabled: true},
}},
})
for _, v := range []string{"ops", "sales-eu", "sales-us", "hr"} {
offered := slices.ContainsFunc(team.GetOptions(), func(o form.SelectOptionElement[string]) bool { return o.Allows(v) })
fmt.Println(v, offered)
}
}
Output: ops true sales-eu true sales-us false hr false
type SelectMultiple ¶
type SelectMultiple[T ElementValueType] struct { // contains filtered or unexported fields }
SelectMultiple is a <select multiple> field. Every posted value must be one of its options.
func (*SelectMultiple[T]) GetError ¶
func (e *SelectMultiple[T]) GetError() string
GetError returns the field's error.
func (*SelectMultiple[T]) GetOptions ¶
func (e *SelectMultiple[T]) GetOptions() []SelectOptionElement[T]
GetOptions returns the field's options.
func (*SelectMultiple[T]) GetValue ¶
func (e *SelectMultiple[T]) GetValue() map[T]struct{}
GetValue returns the field's values.
func (*SelectMultiple[T]) HasError ¶
func (e *SelectMultiple[T]) HasError() bool
HasError reports whether the field has an error.
func (*SelectMultiple[T]) IsNotNull ¶
func (e *SelectMultiple[T]) IsNotNull() bool
IsNotNull reports whether the field has values, set or posted.
func (*SelectMultiple[T]) Process ¶
func (e *SelectMultiple[T]) Process(r *http.Request, name string, isMultipart, isRequired bool)
Process reads the field from the parsed form in r. Generated code calls it after the form's options are set.
Generated code only.
func (*SelectMultiple[T]) SetError ¶
func (e *SelectMultiple[T]) SetError(err string)
SetError sets the field's error.
func (*SelectMultiple[T]) SetOptions ¶
func (e *SelectMultiple[T]) SetOptions(o []SelectOptionElement[T])
SetOptions sets the options a viewer can choose from.
func (*SelectMultiple[T]) SetValue ¶
func (e *SelectMultiple[T]) SetValue(v map[T]struct{})
SetValue sets the field's values.
type SelectOption ¶
type SelectOption[T ElementValueType] struct { Value T Label string Disabled bool }
SelectOption is one option of a select field.
func (SelectOption[T]) Allows ¶
func (o SelectOption[T]) Allows(v T) bool
Allows reports whether v is this option's value and the option is enabled.
type SelectOptionElement ¶
type SelectOptionElement[T ElementValueType] interface { // WriteHtml writes the element's markup, marking the options for which isSelected holds. WriteHtml(w io.Writer, isSelected func(v T) bool) error // Allows reports whether v is an option a viewer can choose. Allows(v T) bool }
SelectOptionElement is an option or a group of options of a select field.
type SelectOptionGroup ¶
type SelectOptionGroup[T ElementValueType] struct { Label string Disabled bool Options []SelectOptionElement[T] }
SelectOptionGroup is a labelled group of options of a select field.
func (SelectOptionGroup[T]) Allows ¶
func (o SelectOptionGroup[T]) Allows(v T) bool
Allows reports whether the group is enabled and one of its options allows v.
type Textarea ¶
type Textarea struct {
// contains filtered or unexported fields
}
Textarea is a <textarea> field.
func (*Textarea) Process ¶
Process reads the field from the parsed form in r. Generated code calls it.
Generated code only.
Source Files