forms

README

forms

Description

forms makes form creation and handling easy. It allows the creation of form without having to write HTML code or bother to make the code Bootstrap compatible. You can just create your form instance and add / populate / customize fields based on your needs. Or you can let forms do that for you starting from any object instance.

To integrate forms forms into your application simply pass the form object to the template and call its Render method. In your code:

tmpl.Execute(buf, map[string]interface{}{"form": form})

In your template:

{{ if .form }}{{ .form.Render }}{{ end }}

Installation

To install this package simply:

go get github.com/coscms/forms

Forms

There are two predefined styles for forms: base HTML forms and Bootstrap forms: they have different structures and predefined classes. Style aside, forms can be created from scratch or starting from a base instance.

From scratch

You can create a form instance by simply deciding its style and providing its method and action:

form := NewForm("base", POST, "/action.html")

Now that you have a form instance you can customize it by adding classes, parameters, CSS values or id. Each method returns a pointer to the same form, so multiple calls can be chained:

form.SetId("TestForm").AddClass("form").AddCss("border", "auto")

Obviously, elements can be added as well:

form.Elements(fields.TextField("text_field"))

Elements can be either FieldSets or Fields: the formers are simply collections of fields translated into a <fieldset></fieldset> element. Elements are added in order, and they are displayed in the exact same order. Note that single elements can be removed from a form referencing them by name:

form.RemoveElement("text_field")

Typical usage looks like this:

form := NewForm("base", POST, "/action.html").Elements(
	fields.TextField("text_field").SetLabel("Username"),
	FieldSet("psw_fieldset",
		fields.PasswordField("psw1").AddClass("password_class").SetLabel("Password 1"),
		fields.PasswordField("psw2").AddClass("password_class").SetLabel("Password 2"),
		),
	fields.SubmitButton("btn1", "Submit"),
	)

validation:

type User struct {
	Username 	string	`valid:"Required;AlphaDash;MaxSize(30)"`
	Password1 	string	`valid:"Required"`
	Password2	string	`valid:"Required"`
}

u := &User{}
form.SetModel(u) //Must set model
valid, passed := form.valid()
if !passed { 
	// validation does not pass
}
_ = valid

Details about validation, please visit: https://github.com/coscms/xweb/blob/master/validation/README.md

A call to form.Render() returns the following form:

<form method="POST" action="/action.html">
	<label>Username</label>
	<input type="text" name="text_field">
	<fieldset>
		<label>Password 1</label>
		<input type="password" name="psw1" class="password_class ">
		<label>Password 2</label>
		<input type="password" name="psw2" class="password_class ">
	</fieldset>
	<button type="submit" name="btn1">Submit</button>
</form>

From model instance

Instead of manually creating a form, it can be automatically created from an existing model instance: the package will try to infer the field types based on the instance fields and fill them accordingly. Default type-to-field mapping is as follows:

• string: TextField
• bool: Checkbox
• time.Time: DatetimeField
• int: NumberField
• struct: recursively parse

You can customize field behaviors by adding tags to instance fields. Without tags this code:

type User struct {
	Username 	string
	Password1 	string
	Password2	string
}

u := &User{}

form := NewFormFromModel(u, "bootstrap3", POST, "/action.html")

validation:

valid, passed := form.valid()
if !passed { 
	// validation does not pass
}
_ = valid

form.Render()

would yield this HTML form:

<form method="POST" action="/action.html">
	<label>Username</label>
	<input type="text" name="Username">
	<label>Password1</label>
	<input type="text" name="Password1">
	<label>Password2</label>
	<input type="text" name="Password2">
	<button type="submit" name="submit">Submit</button>
</form>

A submit button is added by default.

Notice that the form is still editable and fields can be added, modified or removed like before.

When creating a form from a model instance, field names are created by appending the field name to the baseline; the baseline is empty for single level structs but is crafted when nested structs are found: in this case it becomes the field name followed by a dot. So for example, if the struct is:

type A struct {
	field1 	int
	field2 	int
}

type B struct {
	field0 	int
	struct1	A
}

The final form will contain fields "field0", "struct1.field1" and "struct1.field2".

Tags

Struct tags can be used to slightly modify automatic form creation. In particular the following tags are parsed:

• form_options: can contain the following keywords separated by Semicolon (;)
  • -: skip field, do not convert to HTML field
  • checked: for Checkbox fields, check by default
  • multiple: for select fields, allows multiple choices
• form_widget: override custom widget with one of the following
  • text
  • hidden
  • textarea
  • password
  • select
  • datetime
  • date
  • time
  • number
  • range
  • radio
  • checkbox
  • static (simple text)
• form_fieldset: define fieldset name
• form_sort: sort number (asc, 0 ~ total-1)
• form_choices: defines options for select and radio input fields
  • radio/checkbox example(format: id|value): 1|Option One|2|Option 2|3|Option 3
  • select example(format: group|id|value): G1|A|Option A|G1|B|Option B
    • "" group is the default one and does not trigger a rendering.
• form_max: max value (number, range, datetime, date and time fields)
• form_min: min value (number, range, datetime, date and time fields)
• form_step: step value (range field)
• form_rows: number of rows (textarea field)
• form_cols: number of columns (textarea field)
• form_value: input field value (used if field is empty)
• form_label: label for input field

The code would therefore be better like this:

type User struct {
	Username 	string
	Password1 	string 	`form_widget:"password" form_label:"Password 1"`
	Password2	string 	`form_widget:"password" form_label:"Password 2"`
	SkipThis	int 	`form_options:"-"`
}

u := User{}

form := NewFormFromModel(u, "bootstrap3", POST, "/action.html")
form.Render()

which translates into:

<form method="POST" action="/action.html">
	<label>Username</label>
	<input type="text" name="Username">
	<label>Password 1</label>
	<input type="password" name="Password1">
	<label>Password 2</label>
	<input type="password" name="Password2">
	<button type="submit" name="submit">Submit</button>
</form>

Fields

Field objects in forms implement the fields.FieldInterface which exposes methods to edit classes, parameters, tags and CSS styles. See the documentation for details.

Most of the field widgets have already been created and integrate with Bootstrap. It is possible, however, to define custom widgets to render fields by simply assigning an object implementing the widgets.WidgetInterface to the Widget field.

Also, error messages can be added to fields via the AddError(err) method: in a Bootstrap environment they will be correctly rendered.

Text fields

This category includes text, password, textarea and hidden fields. They are all instantiated by providing the name, except the TextAreaField which also requires a dimension in terms of rows and columns.

f0 := fields.TextField("text")
f1 := fields.PasswordField("password")
f2 := fields.HiddenField("hidden")
f3 := fields.TextAreaField("textarea", 30, 50)

Option fields

This category includes checkbox, select and radio button fields. Checkbox field requires a name and a set of options to populate the field. The options are just a set of InputChoice (Id-Value pairs) objects:

opts := []fields.InputChoice{
	fields.InputChoice{Id:"A", Val:"Option A"},
	fields.InputChoice{Id:"B", Val:"Option B"},
}
f := fields.CheckboxField("checkbox", opts)
f.AddSelected("A", "B")

Radio buttons, instead, require a name and a set of options to populate the field. The options are just a set of InputChoice (Id-Value pairs) objects:

opts := []fields.InputChoice{
	fields.InputChoice{Id:"A", Val:"Option A"},
	fields.InputChoice{Id:"B", Val:"Option B"},
}
f := fields.RadioField("radio", opts)

Select fields, on the other hand, allow option grouping. This can be achieved by passing a map[string][]InputChoice in which keys are groups containing choices given as values; the default (empty) group is "", which is not translated into any <optgroup></optgroup> element.

opts := map[string][]fields.InputChoice{
	"": []fields.InputChoice{fields.InputChoice{"A", "Option A"}},
	"group1": []fields.InputChoice{
		fields.InputChoice{Id:"B", Val:"Option B"},
		fields.InputChoice{Id:"C", Val:"Option C"},
	}
}
f := fields.SelectField("select", opts)

Select fields can allow multiple choices. To enable this option simply call the MultipleChoice() method on the field and provide the selected choices via AddSelected(...string):

f.MultipleChoice()
f.AddSelected("A", "B")

Number fields

Number and range fields are included. Number field only require a name to be instantiated; minimum and maximum values can optionally be set by adding min and max parameters respectively.

f := fields.NumberField("number")
f.SetParam("min", "1")

Range fields, on the other hand, require both minimum and maximum values (plus the identifier). The optional "step" value is set via SetParam.

f := fields.RangeField("range", 1, 10)
f.SetParam("step", "2")

Datetime fields

Datetime, date and time input fields are defined in go-form-it.

f0 := fields.DatetimeField("datetime")
f1 := fields.DateField("date")
f2 := fields.TimeField("time")

Values can be set via SetValue method; there's no input validation but format strings are provided to ensure the correct time-to-string conversion.

t := time.Now()
f0.SetValue(t.Format(fields.DATETIME_FORMAT))
f1.SetValue(t.Format(fields.DATE_FORMAT))
f2.SetValue(t.Format(fields.TIME_FORMAT))

Buttons

Buttons can be created calling either the Button, SubmitButton or ResetButton constructor methods and providing a text identifier and the content of the button itself.

btn0 := fields.Button("btn", "Click me!")

License

forms is released under the MIT license. See LICENSE.

Documentation

Overview

This package provides form creation and rendering functionalities, as well as FieldSet definition. Two kind of forms can be created: base forms and Bootstrap3 compatible forms; even though the latters are automatically provided the required classes to make them render correctly in a Bootstrap environment, every form can be given custom parameters such as classes, id, generic parameters (in key-value form) and stylesheet options.

Index

• Constants
• Variables
• func Html5Validate(valid string, f fields.FieldInterface)
• func ValidationEngine(valid string, f fields.FieldInterface)
• type FieldSetType
  • func FieldSet(name string, elems ...fields.FieldInterface) *FieldSetType
  • func (f *FieldSetType) AddClass(class string) *FieldSetType
  • func (f *FieldSetType) AddTag(tag string) *FieldSetType
  • func (f *FieldSetType) Data() map[string]interface{}
  • func (f *FieldSetType) Disable() *FieldSetType
  • func (f *FieldSetType) Elements(elems ...FormElement) *FieldSetType
  • func (f *FieldSetType) Enable() *FieldSetType
  • func (f *FieldSetType) Field(name string) fields.FieldInterface
  • func (f *FieldSetType) Name() string
  • func (f *FieldSetType) RemoveClass(class string) *FieldSetType
  • func (f *FieldSetType) RemoveTag(tag string) *FieldSetType
  • func (f *FieldSetType) Render() template.HTML
  • func (f *FieldSetType) SetData(key string, value interface{})
  • func (f *FieldSetType) SetTmpl(tmpl string) *FieldSetType
  • func (f *FieldSetType) Sort(sortList ...string) *FieldSetType
  • func (f *FieldSetType) Sort2Last(fieldsName ...string) *FieldSetType
  • func (f *FieldSetType) SortAll(sortList ...string) *FieldSetType
  • func (f *FieldSetType) String() string
• type Form
  • func NewForm(style string, args ...string) *Form
  • func NewFormFromModel(m interface{}, style string, args ...string) *Form
  • func (f *Form) AddClass(class string) *Form
  • func (f *Form) AddCss(key, value string) *Form
  • func (f *Form) Data() map[string]interface{}
  • func (f *Form) DeleteParam(key string) *Form
  • func (f *Form) Elements(elems ...FormElement) *Form
  • func (f *Form) Field(name string) fields.FieldInterface
  • func (f *Form) FieldSet(name string) *FieldSetType
  • func (f *Form) Fields() []FormElement
  • func (f *Form) Html(value interface{}) template.HTML
  • func (f *Form) NewFieldSet(name string, elems ...fields.FieldInterface) *FieldSetType
  • func (f *Form) RemoveClass(class string) *Form
  • func (f *Form) RemoveCss(key string) *Form
  • func (f *Form) RemoveElement(name string) *Form
  • func (f *Form) Render() template.HTML
  • func (f *Form) SetData(key string, value interface{})
  • func (f *Form) SetId(id string) *Form
  • func (f *Form) SetModel(m interface{}) *Form
  • func (f *Form) SetParam(key, value string) *Form
  • func (f *Form) Sort(sortList ...string) *Form
  • func (f *Form) Sort2Last(fieldsName ...string) *Form
  • func (f *Form) SortAll(sortList ...string) *Form
  • func (f *Form) String() string
  • func (f *Form) Valid(args ...string) (valid *validation.Validation, passed bool)
• type FormElement

Constants

const (
	POST = "POST"
	GET  = "GET"
)

Form methods: POST or GET.

Variables

var ValidTagFn func(string, fields.FieldInterface) = Html5Validate

Functions

func Html5Validate

func Html5Validate(valid string, f fields.FieldInterface)

func ValidationEngine

func ValidationEngine(valid string, f fields.FieldInterface)

Types

type FieldSetType

type FieldSetType struct {
	AppendData map[string]interface{}
	// contains filtered or unexported fields
}

FieldSetType is a collection of fields grouped within a form.

func FieldSet

func FieldSet(name string, elems ...fields.FieldInterface) *FieldSetType

FieldSet creates and returns a new FieldSetType with the given name and list of fields. Every method for FieldSetType objects returns the object itself, so that call can be chained.

func (*FieldSetType) AddClass

func (f *FieldSetType) AddClass(class string) *FieldSetType

AddClass saves the provided class for the fieldset.

func (*FieldSetType) AddTag

func (f *FieldSetType) AddTag(tag string) *FieldSetType

AddTag adds a no-value parameter (e.g.: "disabled", "checked") to the fieldset.

func (*FieldSetType) Data

func (f *FieldSetType) Data() map[string]interface{}

func (*FieldSetType) Disable

func (f *FieldSetType) Disable() *FieldSetType

Disable adds tag "disabled" to the fieldset, making it unresponsive in some environment (e.g.: Bootstrap).

func (*FieldSetType) Elements

func (f *FieldSetType) Elements(elems ...FormElement) *FieldSetType

Elements adds the provided elements to the fieldset.

func (*FieldSetType) Enable

func (f *FieldSetType) Enable() *FieldSetType

Enable removes tag "disabled" from the fieldset, making it responsive.

func (*FieldSetType) Field

func (f *FieldSetType) Field(name string) fields.FieldInterface

Field returns the field identified by name. It returns an empty field if it is missing.

func (*FieldSetType) Name

func (f *FieldSetType) Name() string

Name returns the name of the fieldset.

func (*FieldSetType) RemoveClass

func (f *FieldSetType) RemoveClass(class string) *FieldSetType

RemoveClass removes the provided class from the fieldset, if it was present. Nothing is done if it was not originally present.

func (*FieldSetType) RemoveTag

func (f *FieldSetType) RemoveTag(tag string) *FieldSetType

RemoveTag removes a tag from the fieldset, if it was present.

func (*FieldSetType) Render

func (f *FieldSetType) Render() template.HTML

Render translates a FieldSetType into HTML code and returns it as a template.HTML object.

func (*FieldSetType) SetData

func (f *FieldSetType) SetData(key string, value interface{})

func (*FieldSetType) SetTmpl

func (f *FieldSetType) SetTmpl(tmpl string) *FieldSetType

func (*FieldSetType) Sort

func (f *FieldSetType) Sort(sortList ...string) *FieldSetType

Sort("field1:1,field2:2") or Sort("field1:1","field2:2")

func (*FieldSetType) Sort2Last

func (f *FieldSetType) Sort2Last(fieldsName ...string) *FieldSetType

func (*FieldSetType) SortAll

func (f *FieldSetType) SortAll(sortList ...string) *FieldSetType

SortAll("field1,field2") or SortAll("field1","field2")

func (*FieldSetType) String

func (f *FieldSetType) String() string

type Form

type Form struct {
	AppendData map[string]interface{}
	// contains filtered or unexported fields
}

Form structure.

func NewForm

func NewForm(style string, args ...string) *Form

func NewFormFromModel

func NewFormFromModel(m interface{}, style string, args ...string) *Form

NewFormFromModel returns a base form inferring fields, data types and contents from the provided instance. A Submit button is automatically added as a last field; the form is editable and fields can be added, modified or removed as needed. Tags can be used to drive automatic creation: change default widgets for each field, skip fields or provide additional parameters. Basic field -> widget mapping is as follows: string -> textField, bool -> checkbox, time.Time -> datetimeField, int -> numberField; nested structs are also converted and added to the form.

func (*Form) AddClass

func (f *Form) AddClass(class string) *Form

AddClass associates the provided class to the Form.

func (*Form) AddCss

func (f *Form) AddCss(key, value string) *Form

AddCss add a CSS value (in the form of option-value - e.g.: border - auto) to the form.

func (*Form) Data

func (f *Form) Data() map[string]interface{}

func (*Form) DeleteParam

func (f *Form) DeleteParam(key string) *Form

DeleteParm removes the parameter identified by key from form parameters list.

func (*Form) Elements

func (f *Form) Elements(elems ...FormElement) *Form

Elements adds the provided elements to the form.

func (*Form) Field

func (f *Form) Field(name string) fields.FieldInterface

Field returns the field identified by name. It returns an empty field if it is missing.

func (*Form) FieldSet

func (f *Form) FieldSet(name string) *FieldSetType

Field returns the field identified by name. It returns an empty field if it is missing.

func (*Form) Fields

func (f *Form) Fields() []FormElement

Fields returns all field

func (*Form) Html

func (f *Form) Html(value interface{}) template.HTML

func (*Form) NewFieldSet

func (f *Form) NewFieldSet(name string, elems ...fields.FieldInterface) *FieldSetType

FieldSet creates and returns a new FieldSetType with the given name and list of fields. Every method for FieldSetType objects returns the object itself, so that call can be chained.

func (*Form) RemoveClass

func (f *Form) RemoveClass(class string) *Form

RemoveClass removes the given class (if present) from the Form.

func (*Form) RemoveCss

func (f *Form) RemoveCss(key string) *Form

RemoveCss removes CSS style from the form.

func (*Form) RemoveElement

func (f *Form) RemoveElement(name string) *Form

RemoveElement removes an element (identified by name) from the Form.

func (*Form) Render

func (f *Form) Render() template.HTML

Render executes the internal template and renders the form, returning the result as a template.HTML object embeddable in any other template.

func (*Form) SetData

func (f *Form) SetData(key string, value interface{})

func (*Form) SetId

func (f *Form) SetId(id string) *Form

SetId set the given id to the form.

func (*Form) SetModel

func (f *Form) SetModel(m interface{}) *Form

func (*Form) SetParam

func (f *Form) SetParam(key, value string) *Form

SetParam adds the given key-value pair to form parameters list.

func (*Form) Sort

func (f *Form) Sort(sortList ...string) *Form

Sort("field1:1,field2:2") or Sort("field1:1","field2:2")

func (*Form) Sort2Last

func (f *Form) Sort2Last(fieldsName ...string) *Form

func (*Form) SortAll

func (f *Form) SortAll(sortList ...string) *Form

SortAll("field1,field2") or SortAll("field1","field2")

func (*Form) String

func (f *Form) String() string

func (*Form) Valid

func (f *Form) Valid(args ...string) (valid *validation.Validation, passed bool)

type FormElement

type FormElement interface {
	Render() template.HTML
	Name() string
	String() string
	SetData(key string, value interface{})
	Data() map[string]interface{}
}

FormElement interface defines a form object (usually a Field or a FieldSet) that can be rendered as a template.HTML object.