A go package which provides functions for validating and serializing html forms. It is intended to be compiled to javascript via gopherjs and run in the browser. Form works great as a stand-alone package or in combination with other Humble packages.
Form is written in pure go. It feels like go, follows go idioms when possible, and compiles with the go tools. But it is meant to be compiled to javascript and run in the browser.
Form works with IE9+ (with a polyfill for typed arrays) and all other modern browsers. Form compiles to javascript via gopherjs and this is a gopherjs limitation.
Form is regularly tested with the latest versions of Firefox, Chrome, and Safari on Mac OS. Each major or minor release is tested with IE9+ and the latest versions of Firefox and Chrome on Windows.
Install form like you would any other go package:
go get github.com/go-humble/form
You will also need to install gopherjs if you don't already have it. The latest version is recommended. Install gopherjs with:
go get -u github.com/gopherjs/gopherjs
Finally, you will need to install the gopherjs dom bindings:
go get -u honnef.co/go/js/dom
The first thing you'll want to do is create a Form
object. To do this, you can
get an html form element using a query selector and then pass it as an argument
to the Parse
function.
// Use a query selector to get the form element.
document := dom.GetWindow().Document()
formEl := document.QuerySelector("#form")
// Parse the form element and get a form.Form object in return.
f, err := form.Parse(formEl)
if err != nil {
// Handle err.
}
You can validate the inputs in the form by using the Validate
method.
Validate
expects an input name as an argument and returns an InputValidation
object, which has chainable methods for validating a single input.
Here's an example:
// Validate the form inputs.
f.Validate("name").Required()
f.Validate("age").Required().IsInt().Greater(0).LessOrEqual(99)
// Check if there were any validation errors.
if f.HasErrors() {
for _, err := range fmr.Errors {
// Do something with each error.
}
}
See the
documentation on the InputValidation
type
for more validation methods.
You can use helper methods to get the value for an input and convert it to a go type. For example, here's how you can get the value for an input field named "age" converted to an int:
age, err := f.GetInt("age")
if err != nil {
// Handle err.
}
See the
documentation on the Form
type
for more helper methods.
You can bind a form to any struct by using the
Bind
method. Bind
compares the names of the fields of the struct to the names of the form inputs.
When it finds a match, it attempts to set the value of the struct field to the
input value.
Suppose you had a form that looked like this:
<form>
<input name="name" >
<input name="age" type="number" >
</form>
And a Person
struct with the following definition:
type Person struct {
Name string
Age int
}
You could then bind the form to a Person
using the Bind
method:
person := &Person{}
if err := f.Bind(person); err != nil {
// Handle err.
}
Bind
creates a one-way, one-time binding. Changes to the form input values
will not automatically update person, nor will changes to person automatically
change the form input values.
Bind
supports most primative types and pointers to primative types. If your
struct contains a type that is not supported, you can implement the
Binder
or
InputBinder
interfaces to define custom behavior.
Form uses the karma test runner to test the code running in actual browsers.
The tests require the following additional dependencies:
- node.js (If you didn't already install it above)
- karma
- karma-qunit
Don't forget to also install the karma command line tools with npm install -g karma-cli
.
You will also need to install a launcher for each browser you want to test with,
as well as the browsers themselves. Typically you install a karma launcher with
npm install -g karma-chrome-launcher
. You can edit the config file at
karma/test-mac.conf.js
or create a new one (e.g. karma/test-windows.conf.js
)
if you want to change the browsers that are tested on.
Once you have installed all the dependencies, start karma with
karma start karma/test-mac.conf.js
(or your customized config file, if
applicable). Once karma is running, you can keep it running in between tests.
Next you need to compile the test.go file to javascript so it can run in the browsers:
gopherjs build karma/go/form_test.go -o karma/js/form_test.js
Finally run the tests with karma run karma/test-mac.conf.js
(changing the name
of the config file if needed).
If you are on a unix-like operating system, you can recompile and run the tests
in one go by running the provided bash script: ./karma/test.sh
.
See CONTRIBUTING.md
Form is licensed under the MIT License. See the LICENSE file for more information.