form

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

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

Examples

Constants

View Source 
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 

func IsMultipart(r *http.Request) bool

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 Element 

type Element interface {
	HasError() bool
}

Element is a form field.

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) GetError 

func (e *File) GetError() string

GetError returns the field's error.

func (*File) GetValue 

func (e *File) GetValue() *FileHeader

GetValue returns the uploaded file, or nil.

func (*File) HasError 

func (e *File) HasError() bool

HasError reports whether the field has an error.

func (*File) IsNotNull 

func (e *File) IsNotNull() bool

IsNotNull reports whether a file was uploaded.

func (*File) Process 

func (e *File) 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 (*File) SetError 

func (e *File) SetError(err string)

SetError sets the field's error.

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]) GetError 

func (e *Input[T]) GetError() string

GetError returns the field's error.

func (*Input[T]) GetFormValue 

func (e *Input[T]) GetFormValue() string

GetFormValue returns the text posted for the field, so a value that did not parse can be shown again.

func (*Input[T]) GetValue 

func (e *Input[T]) GetValue() T

GetValue returns the field's value.

func (*Input[T]) HasError 

func (e *Input[T]) HasError() bool

HasError reports whether the field has an error.

func (*Input[T]) IsNotNull 

func (e *Input[T]) IsNotNull() bool

IsNotNull reports whether the field has a value, set or posted.

func (*Input[T]) Process 

func (e *Input[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 (*Input[T]) SetError 

func (e *Input[T]) SetError(err string)

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.

func (*Input[T]) SetValue 

func (e *Input[T]) SetValue(v T)

SetValue sets the field's value.

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]) GetError 

func (e *Select[T]) GetError() string

GetError returns the field's error.

func (*Select[T]) GetOptions 

func (e *Select[T]) GetOptions() []SelectOptionElement[T]

GetOptions returns the field's options.

func (*Select[T]) GetValue 

func (e *Select[T]) GetValue() T

GetValue returns the field's value.

func (*Select[T]) HasError 

func (e *Select[T]) HasError() bool

HasError reports whether the field has an error.

func (*Select[T]) IsNotNull 

func (e *Select[T]) IsNotNull() bool

IsNotNull reports whether the field has a value, set or posted.

func (*Select[T]) Process 

func (e *Select[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 (*Select[T]) SetError 

func (e *Select[T]) SetError(err string)

SetError sets the field's error.

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

func (*Select[T]) SetValue 

func (e *Select[T]) SetValue(v T)

SetValue sets the field's value.

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.

func (SelectOption[T]) WriteHtml 

func (o SelectOption[T]) WriteHtml(w io.Writer, isSelected func(v T) bool) error

WriteHtml writes the option as an <option> element.

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.

func (SelectOptionGroup[T]) WriteHtml 

func (o SelectOptionGroup[T]) WriteHtml(w io.Writer, isSelected func(v T) bool) error

WriteHtml writes the group as an <optgroup> element.

type Textarea 

type Textarea struct {
	// contains filtered or unexported fields
}

Textarea is a <textarea> field.

func (*Textarea) GetError 

func (e *Textarea) GetError() string

GetError returns the field's error.

func (*Textarea) GetValue 

func (e *Textarea) GetValue() string

GetValue returns the field's text.

func (*Textarea) HasError 

func (e *Textarea) HasError() bool

HasError reports whether the field has an error.

func (*Textarea) IsNotNull 

func (e *Textarea) IsNotNull() bool

IsNotNull reports whether the field has a value, set or posted.

func (*Textarea) Process 

func (e *Textarea) 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 (*Textarea) SetError 

func (e *Textarea) SetError(err string)

SetError sets the field's error.

func (*Textarea) SetValue 

func (e *Textarea) SetValue(v string)

SetValue sets the field's text.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.