mirror of
https://github.com/kataras/iris.git
synced 2025-01-23 02:31:04 +01:00
add forms chapter
Gerasimos (Makis) Maropoulos
parent
dcbf3a897b
commit
050edceb37
212
Forms.md
Normal file
212
Forms.md
Normal file
|
|
@ -0,0 +1,212 @@
|
|||
Form, post data and uploaded files can be retrieved using the following Context's methods.
|
||||
|
||||
```go
|
||||
// FormValueDefault returns a single parsed form value by its "name",
|
||||
// including both the URL field's query parameters and the POST or PUT form data.
|
||||
//
|
||||
// Returns the "def" if not found.
|
||||
FormValueDefault(name string, def string) string
|
||||
// FormValue returns a single parsed form value by its "name",
|
||||
// including both the URL field's query parameters and the POST or PUT form data.
|
||||
FormValue(name string) string
|
||||
// FormValues returns the parsed form data, including both the URL
|
||||
// field's query parameters and the POST or PUT form data.
|
||||
//
|
||||
// The default form's memory maximum size is 32MB, it can be changed by the
|
||||
// `iris.WithPostMaxMemory` configurator at main configuration passed on `app.Run`'s second argument.
|
||||
//
|
||||
// NOTE: A check for nil is necessary.
|
||||
FormValues() map[string][]string
|
||||
|
||||
// PostValueDefault returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name".
|
||||
//
|
||||
// If not found then "def" is returned instead.
|
||||
PostValueDefault(name string, def string) string
|
||||
// PostValue returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name"
|
||||
PostValue(name string) string
|
||||
// PostValueTrim returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", without trailing spaces.
|
||||
PostValueTrim(name string) string
|
||||
// PostValueInt returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as int.
|
||||
//
|
||||
// If not found returns -1 and a non-nil error.
|
||||
PostValueInt(name string) (int, error)
|
||||
// PostValueIntDefault returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as int.
|
||||
//
|
||||
// If not found returns or parse errors the "def".
|
||||
PostValueIntDefault(name string, def int) int
|
||||
// PostValueInt64 returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as float64.
|
||||
//
|
||||
// If not found returns -1 and a no-nil error.
|
||||
PostValueInt64(name string) (int64, error)
|
||||
// PostValueInt64Default returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as int64.
|
||||
//
|
||||
// If not found or parse errors returns the "def".
|
||||
PostValueInt64Default(name string, def int64) int64
|
||||
// PostValueInt64Default returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as float64.
|
||||
//
|
||||
// If not found returns -1 and a non-nil error.
|
||||
PostValueFloat64(name string) (float64, error)
|
||||
// PostValueInt64Default returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as float64.
|
||||
//
|
||||
// If not found or parse errors returns the "def".
|
||||
PostValueFloat64Default(name string, def float64) float64
|
||||
// PostValueInt64Default returns the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name", as bool.
|
||||
//
|
||||
// If not found or value is false, then it returns false, otherwise true.
|
||||
PostValueBool(name string) (bool, error)
|
||||
// PostValues returns all the parsed form data from POST, PATCH,
|
||||
// or PUT body parameters based on a "name" as a string slice.
|
||||
//
|
||||
// The default form's memory maximum size is 32MB, it can be changed by the
|
||||
// `iris.WithPostMaxMemory` configurator at main configuration passed on `app.Run`'s second argument.
|
||||
PostValues(name string) []string
|
||||
// FormFile returns the first uploaded file that received from the client.
|
||||
//
|
||||
// The default form's memory maximum size is 32MB, it can be changed by the
|
||||
// `iris.WithPostMaxMemory` configurator at main configuration passed on `app.Run`'s second argument.
|
||||
FormFile(key string) (multipart.File, *multipart.FileHeader, error)
|
||||
```
|
||||
|
||||
## Multipart/Urlencoded Form
|
||||
|
||||
```go
|
||||
func main() {
|
||||
app := iris.Default()
|
||||
|
||||
app.Post("/form_post", func(ctx iris.Context) {
|
||||
message := ctx.FormValue("message")
|
||||
nick := ctx.FormValueDefault("nick", "anonymous")
|
||||
|
||||
ctx.JSON(iris.Map{
|
||||
"status": "posted",
|
||||
"message": message,
|
||||
"nick": nick,
|
||||
})
|
||||
})
|
||||
|
||||
app.Run(iris.Addr(":8080"))
|
||||
}
|
||||
```
|
||||
|
||||
## Another example: query + post form
|
||||
|
||||
```sh
|
||||
POST /post?id=1234&page=1 HTTP/1.1
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
name=manu&message=this_is_great
|
||||
```
|
||||
|
||||
```go
|
||||
func main() {
|
||||
app := iris.Default()
|
||||
|
||||
app.Post("/post", func(ctx iris.Context) {
|
||||
id := ctx.URLParam("id")
|
||||
page := ctx.URLParamDefault("page", "0")
|
||||
name := ctx.FormValue("name")
|
||||
message := ctx.FormValue("message")
|
||||
// or `ctx.PostValue` for POST, PUT & PATCH-only HTTP Methods.
|
||||
|
||||
app.Logger().Infof("id: %s; page: %s; name: %s; message: %s",
|
||||
id, page, name, message)
|
||||
})
|
||||
|
||||
app.Run(iris.Addr(":8080"))
|
||||
}
|
||||
```
|
||||
|
||||
```sh
|
||||
id: 1234; page: 1; name: manu; message: this_is_great
|
||||
```
|
||||
|
||||
## Upload files
|
||||
|
||||
Iris Context offers a helper for uploading files (saving files to host system's hard disk from request file data). Read more about the `Context.UploadFormFiles` method below.
|
||||
|
||||
UploadFormFiles uploads any received file(s) from the client
|
||||
to the system physical location "destDirectory".
|
||||
|
||||
The second optional argument "before" gives caller the chance to
|
||||
modify the *miltipart.FileHeader before saving to the disk,
|
||||
it can be used to change a file's name based on the current request,
|
||||
all FileHeader's options can be changed. You can ignore it if
|
||||
you don't need to use this capability before saving a file to the disk.
|
||||
|
||||
Note that it doesn't check if request body streamed.
|
||||
|
||||
Returns the copied length as int64 and
|
||||
a not nil error if at least one new file
|
||||
can't be created due to the operating system's permissions or
|
||||
`net/http.ErrMissingFile` if no file received.
|
||||
|
||||
If you want to receive & accept files and manage them manually you can use the `Context.FormFile`
|
||||
instead and create a copy function that suits your needs, the below is for generic usage.
|
||||
|
||||
The default form's memory maximum size is 32MB, it can be changed by the `iris#WithPostMaxMemory` configurator at main configuration passed on `app.Run`'s second argument.
|
||||
|
||||
```go
|
||||
UploadFormFiles(destDirectory string,
|
||||
before ...func(Context, *multipart.FileHeader)) (n int64, err error)
|
||||
```
|
||||
|
||||
Example Code:
|
||||
|
||||
```go
|
||||
const maxSize = 5 << 20 // 5MB
|
||||
|
||||
func main() {
|
||||
app := iris.Default()
|
||||
app.Post("/upload", iris.LimitRequestBodySize(maxSize), func(ctx iris.Context) {
|
||||
//
|
||||
// UploadFormFiles
|
||||
// uploads any number of incoming files ("multiple" property on the form input).
|
||||
//
|
||||
|
||||
// The second, optional, argument
|
||||
// can be used to change a file's name based on the request,
|
||||
// at this example we will showcase how to use it
|
||||
// by prefixing the uploaded file with the current user's ip.
|
||||
ctx.UploadFormFiles("./uploads", beforeSave)
|
||||
})
|
||||
|
||||
app.Run(iris.Addr(":8080"))
|
||||
}
|
||||
|
||||
func beforeSave(ctx iris.Context, file *multipart.FileHeader) {
|
||||
ip := ctx.RemoteAddr()
|
||||
// make sure you format the ip in a way
|
||||
// that can be used for a file name (simple case):
|
||||
ip = strings.Replace(ip, ".", "_", -1)
|
||||
ip = strings.Replace(ip, ":", "_", -1)
|
||||
|
||||
// you can use the time.Now, to prefix or suffix the files
|
||||
// based on the current time as well, as an exercise.
|
||||
// i.e unixTime := time.Now().Unix()
|
||||
// prefix the Filename with the $IP-
|
||||
// no need for more actions, internal uploader will use this
|
||||
// name to save the file into the "./uploads" folder.
|
||||
file.Filename = ip + "-" + file.Filename
|
||||
}
|
||||
```
|
||||
|
||||
How to `curl`:
|
||||
|
||||
```sh
|
||||
curl -X POST http://localhost:8080/upload \
|
||||
-F "files[]=@./myfile.zip" \
|
||||
-F "files[]=@./mysecondfile.zip" \
|
||||
-H "Content-Type: multipart/form-data"
|
||||
```
|
||||
|
||||
More examples can be found at <https://github.com/kataras/iris/tree/master/_examples/http_request>.
|
||||
1
Home.md
1
Home.md
|
|
@ -21,6 +21,7 @@ This wiki is the main source of documentation for **developers** working with (o
|
|||
* [[API Versioning]]
|
||||
* [[Request Authentication]]
|
||||
* [[URL Query Parameters]]
|
||||
* [[Forms]]
|
||||
* [[File Server]]
|
||||
* [[View]]
|
||||
* [[Dependency Injection|dependency-injection]]
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@
|
|||
* [[API Versioning]]
|
||||
* [[Request Authentication]]
|
||||
* [[URL Query Parameters]]
|
||||
* [[Forms]]
|
||||
* [[File Server]]
|
||||
* [[View]]
|
||||
* [[Dependency Injection|dependency-injection]]
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user