struc2frm

README

struc2frm

Golang Struct to HTML Form

• Package struc2frm converts or transforms a
  golang struct type into an HTML input form.

• All your admin and backend forms generated directly from golang structs.

• HTML input field info is taken from the form struct tag.

• Decode() and DecodeMultipartForm() transform the HTTP request data back into an instance of the struct type used for the HTML code.

• Decode() and DecodeMultipartForm() also check the
  auto-generated form token against CSRF attacks.

• Fully functional example-webserver in directory systemtest;
  compile and run, then
  Main example
  File upload example

Example use

type entryForm struct {
    Department  string `json:"department,omitempty"    form:"subtype='select',accesskey='p',onchange='true',title='loading items'"`
    Separator01 string `json:"separator01,omitempty"   form:"subtype='separator'"`
    HashKey     string `json:"hashkey,omitempty"       form:"maxlength='16',size='16',suffix='changes randomness'"`
    Groups      int    `json:"groups,omitempty"        form:"min=1,max='100',maxlength='3',size='3'"`
    Items       string `json:"items,omitempty"         form:"subtype='textarea',cols='22',rows='12',maxlength='4000',title='add times - delimited by newline (enter)'"`
    Group01     string `json:"group01,omitempty"       form:"subtype='fieldset'"`
    Date        string `json:"date,omitempty"          form:"subtype='date',nobreak=true,min='1989-10-29',max='2030-10-29'"`
    Time        string `json:"time,omitempty"          form:"subtype='time',maxlength='12',size='12'"`
    Group02     string `json:"group02,omitempty"       form:"subtype='fieldset'"`
    DateLayout  string `json:"date_layout,omitempty"   form:"accesskey='t',maxlength='16',size='16',pattern='[0-9\\.\\-/]{10}',placeholder='2006/01/02 15:04'"` // 2006-01-02 15:04
    CheckThis   bool   `json:"checkthis,omitempty"     form:"suffix='without consequence'"`

    // Requires distinct way of form parsing
    // Upload     []byte `json:"upload,omitempty"       form:"accesskey='u',accept='.xlsx'"`
}

// getting a converter
s2f := struc2frm.New()  // or clone existing one
s2f.ShowHeadline = true // set options
s2f.AddOptions("department", []string{"ub", "fm"}, []string{"UB", "FM"})

// init values
frm := entryForm{
    HashKey: time.Now().Format("2006-01-02"),
    Groups:  4,
    Date:    time.Now().Format("2006-01-02"),
    Time:    time.Now().Format("15:04"),
}

// pulling in values from http request
populated, err := Decode(req, &frm)
if populated && err != nil {
    s2f.AddError("global", fmt.Sprintf("cannot decode form: %v<br>\n <pre>%v</pre>", err, indentedDump(r.Form)))
    log.Printf("cannot decode form: %v<br>\n <pre>%v</pre>", err, indentedDump(r.Form))
}

if populated {
    // business logic
}

// render to HTML
fmt.Fprint(w, s2f.HTML(frm))

Usage - specific field types

• Use float64 or int to create number inputs - with attributes min=1,max=100,step=2.
  Notice that step=2 defines maximum precision; uneven numbers become invalid.
  This is an HTML5 restriction.

• string supports attribute placeholder='2006/01/02 15:04' to show a pattern to the user (placeholder).

• string supports attribute pattern='[0-9\\.\\-/]{10}' to restrict the entry to a regular expression.

• Use attributes maxlength='16' and size='16'
  determine width and maximum content length respectively for input and textarea.
  Attribute size determines height for select/dropdown elements.

• Use string field with subtype textarea and attributes cols='32',rows='22'

• Use string field with subtype date and attributes min='1989-10-29' or max=...

• Use string field with subtype time

• Use bool to create a checkbox

Input settings for mobile phones

• inputmode="numeric" opens the numbers keyboard on mobile phones

• autocapitalize=off switches off first letter upper casing

Separator and fieldset

These are dummmy fields for formatting only

• Every string field with subtype separator is rendered into a horizontal line

• Every string field with subtype fieldset is rendered into grouping box with label

Select / dropdown inputs

• Use string field with subtype select

• Use size=1 or size=5 to determine the height

• Use AddOptions() to fill input[select] elements

• Use DefaultOptionKey() to pre-select an option other than the first on clean forms

• Use onchange='true' for onchange submit

General

• Every field can have an attribute label=...,
  appearing before the input element,
  if not specified, json:"[name]..." is labelized and used

• Every field can have an attribute suffix=...,
  appearing after the input element

• Every field can have an attribute title=...
  for mouse-over tooltips

• Values inside of label='...', suffix='...', title='...', placeholder='...', pattern='...'
  need , instead of ,

• Every field can have an attribute accesskey='t'
  Accesskeys are not put into the label, but into the input tag

• Every field can have an attribute nobreak='true'
  so that the next input remains on the same line

Submit button

If your form only has select inputs with onchange='this.form.submit()'
then no submit button is shown.

This can be overridden by setting struc2frm.New().ShowSubmit to true.

File upload

• input[file] must have golang type []byte

• input[file] should be named upload
  and requires ParseMultipartForm() instead of ParseForm()

• DecodeMultipartForm() and ExtractUploadedFile() are helper funcs
  to extract file upload data

Example

type entryForm struct {
    TextField string `json:"text_field,omitempty"   form:"maxlength='16',size='16'"`
    // Requires distinct way of form parsing
    Upload []byte `json:"upload,omitempty"          form:"accesskey='u',accept='.txt',suffix='*.txt files'"`
}

s2f := struc2frm.New()  // or clone existing one
s2f.ShowHeadline = true // set options
s2f.Indent = 80


// init values
frm := entryForm{
    TextField: "some-init-text",
}

populated, err := DecodeMultipartForm(req, &frm)
if populated && err != nil {
    s2f.AddError("global", fmt.Sprintf("cannot decode multipart form: %v<br>\n <pre>%v</pre>", err, indentedDump(req.Form)))
    log.Printf("cannot decode multipart form: %v<br>\n <pre>%v</pre>", err, indentedDump(req.Form))
}

bts, excelFileName, err := ExtractUploadedFile(req)
if err != nil {
    fmt.Fprintf(w, "Cannot extract file from POST form: %v<br>\n", err)
}

fileMsg := ""
if populated {
    fileMsg = fmt.Sprintf("%v bytes read from excel file -%v- <br>\n", len(bts), excelFileName)
    fileMsg = fmt.Sprintf("%vFile content is --%v-- <br>\n", fileMsg, string(bts))
} else {
    fileMsg = "No upload filename - or empty file<br>\n"

}

fmt.Fprintf(
    w,
    defaultHTML,
    s2f.HTML(frm),
    fileMsg,
)

See handler-file-upload_test.go on how to programmatically POST a file and key-values.

CSS Styling

• Styling is done via CSS selectors
  and can be customized
  by changing or appending struc2frm.New().CSS

• If you already have good styles in your website,
  set CSS = ""

div.struc2frm {
    padding: 4px;
}
div.struc2frm  input {
    margin:  4px;
}

The media query CSS block in default struc2frm.New().CSS
can be used to change the label width depending on screen width.

Label width can also be changed by setting
via struc2frm.New().Indent and struc2frm.New().IndentAddenum to none-zero values.

div.struc2frm-34323168 H3 {
    margin-left: 116px; /* programmatically set via s3f.Indent for each form */
}

/* change specific inputs */
div.struc2frm label[for="time"] {
    min-width: 20px;
}
div.struc2frm select[name="department"] {
    background-color: darkkhaki;
}

Technical stuff

Language	files	blank	comment	code
Go	5	123	68	672
Markdown	1	61	0	150
CSS	1	26	8	120
HTML	1	6	1	30

• Default CSS is init-loaded from an in-package file default.css,
  mostly to have syntax highlighting while editing it.

TODO

• Support for focus() first input element and
  focus() on first input element having an error

• Low Prio: Add field type option group
  meanwhile use select / dropdown

Documentation

Overview

Package struc2frm creates an HTML input form for a given struct type; see README.md for details.

Index

• func Decode(r *http.Request, ptr2Struct interface{}) (populated bool, err error)
• func DecodeMultipartForm(r *http.Request, ptr2Struct interface{}) (populated bool, err error)
• func ExtractUploadedFile(r *http.Request, names ...string) (bts []byte, fname string, err error)
• func FileUploadH(w http.ResponseWriter, req *http.Request)
• func FormH(w http.ResponseWriter, req *http.Request)
• func HTML(intf interface{}) template.HTML
• func New() *s2FT
• func ParseMultipartForm(r *http.Request) error
• type Completable

Functions

func Decode

func Decode(r *http.Request, ptr2Struct interface{}) (populated bool, err error)

Decode decodes the form into an instance of struct and checks the token against CSRF attacks (https://en.wikipedia.org/wiki/Cross-site_request_forgery)

func DecodeMultipartForm

func DecodeMultipartForm(r *http.Request, ptr2Struct interface{}) (populated bool, err error)

DecodeMultipartForm decodes the form into an instance of struct and checks the token against CSRF attacks (https://en.wikipedia.org/wiki/Cross-site_request_forgery)

func ExtractUploadedFile

func ExtractUploadedFile(r *http.Request, names ...string) (bts []byte, fname string, err error)

ExtractUploadedFile extracts a file from an HTTP POST request. It needs the request form to be prepared with ParseMultipartForm.

func FileUploadH

func FileUploadH(w http.ResponseWriter, req *http.Request)

FileUploadH is an http handler func for file upload

func FormH

func FormH(w http.ResponseWriter, req *http.Request)

FormH is an example http handler func

func HTML

func HTML(intf interface{}) template.HTML

HTML takes a struct instance and uses the default formatter to turns it into an HTML form.

func New

func New() *s2FT

New converter

func ParseMultipartForm

func ParseMultipartForm(r *http.Request) error

ParseMultipartForm parses an HTTP request form with file attachments

Types

type Completable

type Completable interface {
	Complete() bool
}

Completable structs can be rendered as HTML list