Documentation

Overview

    Package form implements sending and submitting data forms.

    Index

    Constants

    View Source
    const NS = "jabber:x:data"

      NS is the data forms namespace.

      Variables

      This section is empty.

      Functions

      This section is empty.

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

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

                              MarshalXML satisfies the xml.Marshaler interface for *Data.

                              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
                                                                    }

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