deblan/go-form
1
0
Fork 0
Code Issues Pull requests Projects Releases 13 Packages Wiki Activity Actions

add doc
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Details
ci/woodpecker/manual/woodpecker Pipeline failed
Details

Browse source
This commit is contained in:
Simon Vieille 2025-07-21 22:36:40 +02:00
commit fcde3eb16f
Signed by: deblan
GPG key ID: 579388D585F70417
10 changed files with 221 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
/public
/.hugo_build.lock

4
content/docs/Installation.md
View file

@ -4,4 +4,6 @@ title: Installation
weight: 2
---
# Installation
```golang
go get gitnet.fr/deblan/go-form
```

48
content/docs/fields/_index.md
View file

@ -1,5 +1,49 @@
---
linkTitle: Input
title: Input
linkTitle: Fields
title: Fields
weight: 3
---
The documentation of field is realised with this program.
```golang {hl_lines=[12,13]}
import (
"bytes"
"fmt"
"html/template"
"gitnet.fr/deblan/go-form/form"
"gitnet.fr/deblan/go-form/theme"
)
func main() {
myForm := form.NewForm(
// the documented field here
// form.NewField...
).
WithName("form").
End()
render := theme.NewRenderer(theme.Html5)
tpl, _ := template.New("example").Funcs(render.FuncMap()).Parse(`{{- form .Form -}}`)
var buffer bytes.Buffer
tpl.Execute(&buffer, map[string]any{
"Form": myForm,
})
fmt.Print(buffer.String())
}
```
## Common options
| Name | type | description | Info |
| ---- | ---- | ---- | ---- |
| `required` | `bool` | Add `required="true"` | Does not apply a constraint |
| `attr` | `map[string]string` | List of extra attributes of the field | |
| `row_attr` | `map[string]string` | List of extra attributes of the field's top container | |
| `label` | `string` | The label of the field | Usually show before the field |
| `label_attr` | `map[string]string` | List of extra attributes of the label | |
| `help` | `string` | Helper of the field | |

11
content/docs/fields/input/_index.md
View file

@ -1,11 +0,0 @@
---
linkTitle: Input
title: Input
weight: 3
---
<table>
<tr>
<td>ok</td>
</tr>
</table>

50
content/docs/fields/input/text.md
View file

@ -1,10 +1,50 @@
---
linkTitle: Text
title: Text
weight: 1
---
<table>
<tr>
<td>ok</td>
</tr>
</table>
## Basic example
{{< tabs items="GO,Result" >}}
{{< tab >}}
```golang
form.NewFieldText("Name")
```
{{< /tab >}}
{{< tab >}}
```html
<form action="" method="POST" >
<div >
<input id="form-name" name="form[Name]" value="" type="text" >
</div>
</form>
```
{{< /tab >}}
{{< /tabs >}}
## Fully featured example
{{< tabs items="GO,Result" >}}
{{< tab >}}
```golang
form.NewFieldText("Name").
WithOptions(
form.NewOption("label", "Name"),
form.NewOption("required", true),
form.NewOption("attr", map[string]string{"data-foo": "foo"}),
form.NewOption("row_attr", map[string]string{"data-bar": "bar"}),
)
```
{{< /tab >}}
{{< tab >}}
```html
<form action="" method="POST" >
<div data-bar="bar">
<label for="form-name" >Name</label>
<input id="form-name" required="required" name="form[Name]" value="" type="text" data-foo="foo">
</div>
</form>
```
{{< /tab >}}
{{< /tabs >}}

65
content/docs/form/_index.md
View file

@ -1,65 +0,0 @@
---
linkTitle: Form
title: Form
weight: 3
---
A form is a struct containing:
* Fields
* Options
* Method
* Action
## Import
```golang
import (
"net/http"
"gitnet.fr/deblan/go-form/form"
)
```
## Usage
```golang
// Let's create a new form
// You can pass *form.Field as arguments
myForm := form.NewForm(field1, field2, ...)
// Add somes fields
myForm.Add(field3, field4, ...)
// Set the method
// <form method="POST" ...>
myForm.WithMethod(http.MethodPost)
// Define the action
// <form action="/" ...>
myForm.WithAction("/")
// Set a name
myForm.WithName("myForm")
// Add options
myForm.WithOptions(option1, option2, ...)
// When all fields are added, call End()
myForm.End()
```
## Attributes
Some options are natively supported in go-form themes.
```golang
myForm.WithOptions(
form.NewOption("help", "A help for the form"),
// <form data-foo="bar" data-bar="bar" ...
form.NewOption("attr", map[string]string{
"data-foo": "foo",
"data-bar": "bar",
}),
)
```

43
content/docs/form/bind.md
View file

@ -1,43 +0,0 @@
---
linkTitle: Bind
title: Bind
weight: 2
---
```golang
import (
"net/http"
"gitnet.fr/deblan/go-form/form"
)
type Person struct {
Name string
Age int
}
func createForm() *form.Form {
f := form.NewForm()
// do stuff
return f
}
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
alice := Person{
Name: "Alice",
Age: 42,
}
myForm := createForm()
if r.Method == myForm.Method {
myForm.HandleRequest(r)
if myForm.IsSubmitted() && myForm.IsValid() {
myForm.Bind(&data)
}
}
})
```

20
content/docs/form/mount.md
View file

@ -1,20 +0,0 @@
---
linkTitle: Mount
title: Mount
weight: 1
---
```golang
type Person struct {
Name string
Age int
}
alice := Person{
Name: "Alice",
Age: 42,
}
// Assuming 2 fields named "Name" and "Age" exist
myForm.Mount(alice)
```

120
content/docs/workflow/_index.md Normal file
View file

@ -0,0 +1,120 @@
---
linkTitle: Workflow
title: Workflow
weight: 2
---
{{% steps %}}
### Import
```golang
import (
"html/template"
"net/http"
"gitnet.fr/deblan/go-form/form"
"gitnet.fr/deblan/go-form/theme"
)
```
### Create a form
```golang
// Let's create a new form
// You can pass *form.Field as arguments
myForm := form.NewForm(field1, field2, ...)
// Add somes fields
myForm.Add(field3, field4, ...)
// Set the method
// <form method="POST" ...>
myForm.WithMethod(http.MethodPost)
// Define the action
// <form action="/" ...>
myForm.WithAction("/")
// Set a name
myForm.WithName("myForm")
// Add options
myForm.WithOptions(option1, option2, ...)
// When all fields are added, call End()
myForm.End()
```
#### Attributes
Some options are natively supported in go-form themes.
```golang
myForm.WithOptions(
form.NewOption("help", "A help for the form"),
// <form data-foo="bar" data-bar="bar" ...
form.NewOption("attr", map[string]string{
"data-foo": "foo",
"data-bar": "bar",
}),
)
```
### Data mounting
This step is not required when you does not want to pre-fill the form.
Your struct can be complexe and the form only map existing properties.
```golang
type Person struct {
Name string
Age int
}
data := Person{
Name: "Alice",
Age: 42,
}
// Assuming 2 fields named "Name" and "Age" exist
myForm.Mount(data)
```
### Rendering
```golang
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
// myForm := form.NewForm(...)
render := theme.NewRenderer(theme.Html5)
tpl, _ := template.New("page").Funcs(render.FuncMap()).Parse(`{{ form .Form }}`)
w.Header().Set("Content-Type", "text/html; charset=utf-8")
tpl.Execute(w, map[string]any{
"Form": myForm,
})
}
```
### Data binding
This is the final step. After the form handles the request, you can check if the form has been submitted, check the values are valid and finally populate your struct.
```golang
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
// data := Person{...}
// myForm := form.NewForm(...)
if r.Method == myForm.Method {
myForm.HandleRequest(r)
if myForm.IsSubmitted() && myForm.IsValid() {
myForm.Bind(&data)
}
}
})
```
{{% /steps %}}

6
hugo.yaml
View file

@ -9,6 +9,7 @@ outputs:
enableRobotsTXT: true
hasCJKLanguage: true
enableInlineShortcodes: true
menu:
main:
@ -43,7 +44,10 @@ params:
# width: 40
# height: 20
# link: /
width: wide
width: full
page:
width: full
theme:
# light | dark | system