form

Documentation

Overview

Package form implements sending and submitting data forms.

Index

• Constants
• Variables
• type Data
  • func Cancel(title, instructions string) *Data
  • func New(f ...Field) *Data
  • func (d *Data) ForFields(f func(FieldData))
  • func (d *Data) Get(id string) (v interface{}, ok bool)
  • func (d *Data) GetBool(id string) (b, ok bool)
  • func (d *Data) GetJID(id string) (j jid.JID, ok bool)
  • func (d *Data) GetJIDs(id string) (j []jid.JID, ok bool)
  • func (d *Data) GetString(id string) (s string, ok bool)
  • func (d *Data) GetStrings(id string) (s []string, ok bool)
  • func (d *Data) Instructions() string
  • func (d *Data) Len() int
  • func (d *Data) MarshalXML(e *xml.Encoder, start xml.StartElement) error
  • func (d *Data) Raw(id string) (v []string, ok bool)
  • func (d *Data) Set(id string, v interface{}) (ok bool, err error)
  • func (d *Data) Submit() (submission xml.TokenReader, ok bool)
  • func (d *Data) Title() string
  • func (d *Data) TokenReader() xml.TokenReader
  • func (d *Data) UnmarshalXML(decoder *xml.Decoder, start xml.StartElement) error
  • func (d *Data) WriteXML(w xmlstream.TokenWriter) (int, error)
• type Field
  • func Boolean(id string, o ...Option) Field
  • func Fixed(o ...Option) Field
  • func Hidden(id string, o ...Option) Field
  • func Instructions(s string) Field
  • func JID(id string, o ...Option) Field
  • func JIDMulti(id string, o ...Option) Field
  • func List(id string, o ...Option) Field
  • func ListMulti(id string, o ...Option) Field
  • func Text(id string, o ...Option) Field
  • func TextMulti(id string, o ...Option) Field
  • func TextPrivate(id string, o ...Option) Field
  • func Title(s string) Field
• type FieldData
• type FieldType
• type Iter
• type Option
  • func Desc(s string) Option
  • func Label(s string) Option
  • func ListItem(label, value string) Option
  • func Value(s string) Option
• type Type

Constants

const NS = "jabber:x:data"

NS is the data forms namespace.

Variables

var (
	Feature = info.Feature{Var: NS}
)

A list of service discovery features that are supported by this package.

Types

type Data

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

Data represents a data form.

func Cancel

func Cancel(title, instructions string) *Data

Cancel returns a data form that can be used to cancel an interaction.

func New

func New(f ...Field) *Data

New builds a new data form from the provided options.

func (*Data) ForFields

func (d *Data) ForFields(f func(FieldData))

ForFields iterates over the fields of the form and calls a function for each one, passing it information about the field.

func (*Data) Get

func (d *Data) Get(id string) (v interface{}, ok bool)

Get looks up the value submitted for a form field. If the value has not been set yet and no default value exists, ok will be false.

func (*Data) GetBool

func (d *Data) GetBool(id string) (b, ok bool)

GetBool is like Get except that it asserts that the form submission is a bool. If the form submission was not a bool or is not set, ok will be false.

func (*Data) GetJID

func (d *Data) GetJID(id string) (j jid.JID, ok bool)

GetJID is like Get except that it asserts that the form submission is a JID. If the form submission was not a JID or is not set, ok will be false.

func (*Data) GetJIDs

func (d *Data) GetJIDs(id string) (j []jid.JID, ok bool)

GetJIDs is like Get except that it asserts that the form submission is a slice of JIDs. If the form submission was not a JID slice or is not set, ok will be false.

func (*Data) GetString

func (d *Data) GetString(id string) (s string, ok bool)

GetString is like Get except that it asserts that the form submission is a string (regardless of whether it was a single line or multi-line submission). If the form submission was not a string or is not set, ok will be false.

func (*Data) GetStrings

func (d *Data) GetStrings(id string) (s []string, ok bool)

GetStrings is like Get except that it asserts that the form submission is a slice of strings. If the form submission was not a string slice or is not set, ok will be false.

func (*Data) Instructions

func (d *Data) Instructions() string

Instructions returns the instructions set on the form.

func (*Data) Len

func (d *Data) Len() int

Len returns the number of fields on the form.

func (*Data) MarshalXML

func (d *Data) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML satisfies the xml.Marshaler interface for *Data.

func (*Data) Raw

func (d *Data) Raw(id string) (v []string, ok bool)

Raw looks up the value parsed for a form field as it appeared in the XML.

func (*Data) Set

func (d *Data) Set(id string, v interface{}) (ok bool, err error)

Set sets the form field to the provided value. If the value is of the incorrect type for the form field an error is returned. If no form field with the given name exists, ok will be false. It is permitted to send back fields that did not exist in the original form so this is not an error, but most implementations will ignore them.

func (*Data) Submit

func (d *Data) Submit() (submission xml.TokenReader, ok bool)

Submit returns a form that can be used to submit the original data. If a value has not been set for all required fields ok will be false.

func (*Data) Title

func (d *Data) Title() string

Title returns the title of the form.

func (*Data) TokenReader

func (d *Data) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler for Data.

func (*Data) UnmarshalXML

func (d *Data) UnmarshalXML(decoder *xml.Decoder, start xml.StartElement) error

UnmarshalXML satisfies the xml.Unmarshaler interface for *Data.

func (*Data) WriteXML

func (d *Data) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo for Data.

type Field

type Field func(*Data)

An Field is used to define the behavior and appearance of a data form.

var (
	// Result marks a form as the result type.
	// For more information see TypeResult.
	Result Field = result
)

func Boolean

func Boolean(id string, o ...Option) Field

Boolean fields enable an entity to gather or provide an either-or choice between two options.

func Fixed

func Fixed(o ...Option) Field

Fixed is intended for data description (e.g., human-readable text such as "section" headers) rather than data gathering or provision.

func Hidden

func Hidden(id string, o ...Option) Field

Hidden fields are not shown by the form-submitting entity, but instead are returned, generally unmodified, with the form.

func Instructions

func Instructions(s string) Field

Instructions adds new textual instructions to the form.

func JID

func JID(id string, o ...Option) Field

JID enables an entity to gather or provide a Jabber ID.

func JIDMulti

func JIDMulti(id string, o ...Option) Field

JIDMulti enables an entity to gather or provide multiple Jabber IDs.

func List

func List(id string, o ...Option) Field

List enables an entity to gather or provide a single entry from a list.

func ListMulti

func ListMulti(id string, o ...Option) Field

ListMulti enables an entity to gather or provide one or more entries from a list.

func Text

func Text(id string, o ...Option) Field

Text enables an entity to gather or provide a line of text.

func TextMulti

func TextMulti(id string, o ...Option) Field

TextMulti enables an entity to gather or provide multiple lines of text.

func TextPrivate

func TextPrivate(id string, o ...Option) Field

TextPrivate enables an entity to gather or provide a line of text that should be obscured in the submitting entities interface (eg. with multiple asterisks).

func Title

func Title(s string) Field

Title sets a form's title.

type FieldData

type FieldData struct {
	Type     FieldType
	Var      string
	Label    string
	Desc     string
	Required bool

	// Raw is the value of the field as it came over the wire with no type
	// information.
	// Generally speaking, Get methods on form should be used along with the field
	// data's Var value to fetch fields and Raw should be ignored.
	// Raw is mostly provided to access fixed type fields that do not have a
	// variable name (and therefore cannot be referenced or set).
	Raw []string
}

FieldData represents values from a single field in a data form. The Var field can then be passed to the Get and Set functions on the form to modify the field.

type FieldType

type FieldType string

FieldType is the type of fields in a dataform. For more information see the constants defined in this package.

const (
	// TypeBoolean enables an entity to gather or provide an either-or choice
	// between two options.
	TypeBoolean FieldType = "boolean"

	// TypeFixed is intended for data description (e.g., human-readable text such
	// as "section" headers) rather than data gathering or provision.
	TypeFixed FieldType = "fixed"

	// TypeHidden is for fields that are not shown to the form-submitting entity,
	// but instead are returned with the form.
	TypeHidden FieldType = "hidden"

	// TypeJIDMulti enables an entity to gather or provide multiple JIDs.
	TypeJIDMulti FieldType = "jid-multi"

	// TypeJID enables an entity to gather or provide a single JID.
	TypeJID FieldType = "jid-single"

	// TypeListMulti enables an entity to gather or provide one or more options
	// from among many.
	TypeListMulti FieldType = "list-multi"

	// TypeList enables an entity to gather or provide one option from among many.
	TypeList FieldType = "list-single"

	// TypeTextMulti enables an entity to gather or provide multiple lines of
	// text.
	TypeTextMulti FieldType = "text-multi"

	// TypeTextPrivate enables an entity to gather or provide a single line or
	// word of text, which shall be obscured in an interface (e.g., with multiple
	// instances of the asterisk character).
	TypeTextPrivate FieldType = "text-private"

	// TypeText enables an entity to gather or provide a single line or word of
	// text, which may be shown in an interface.
	TypeText FieldType = "text-single"
)

type Iter

type Iter interface {
	ForForms(node string, f func(*Data) error) error
}

Iter is the interface implemented by types that implement disco form extensions.

type Option

type Option func(*field)

A Option is used to define the behavior and appearance of a form field.

var (
	// Required flags the field as required in order for the form to be considered
	// valid.
	Required Option = required
)

func Desc

func Desc(s string) Option

Desc provides a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field). Desc should not contain newlines (the \n and \r characters), since layout is the responsibility of a user agent. However, it does nothing to prevent them from being added.

func Label

func Label(s string) Option

Label defines a human-readable name for the field.

func ListItem

func ListItem(label, value string) Option

ListItem adds a list item with the provided label and value. It has no effect on any non-list field type.

func Value

func Value(s string) Option

Value defines the default value for the field. Fields of type ListMulti, JidMulti, TextMulti, and Hidden may contain more than one Value; all other field types will only use the first Value.

type Type

type Type string

Type is a form type. For more information see the constants defined in this package.

const (
	// TypeForm indicates that the form-processing entity is asking the
	// form-submitting entity to complete a form.
	TypeForm Type = "form"

	// TypeSubmit indicates that the form-submitting entity is submitting data to
	// the form-processing entity.
	TypeSubmit Type = "submit"

	// TypeCancel indicates that the form-submitting entity has cancelled
	// submission of data to the form-processing entity.
	TypeCancel Type = "cancel"

	// TypeResult indicates that the form-processing entity is returning data
	// (e.g., search results) to the form-submitting entity, or the data is a
	// generic data set.
	TypeResult Type = "result"
)