Form

ctx.Request.Form provides access to the form sent by the client during the current request.

Form automatically analyzes the request body when the header Content-Type corresponds to application/x-www-form-urlencoded or multipart/form-data.

requests with Content-Type: application/json are not processed by Form. To access and process JSON data, check Body.

gox

func POST(ctx *gox.Context) gox.Page {
    name, _ := ctx.Request.Form.Fields.Get("name")
    avatar, _ := ctx.Request.Form.Files.Get("avatar")

    return <p>{{ name }}</p>
}

Form offers support to traditional HTML forms and HTTP or REST API client. When the request comes from an interface developed with GOX, it is recommended to use Actions, as they provide a more organic and robust system for receiving information sent from the browser.

Structure

ctx.Request.Form implement the following API:

text

Form
{
    Fields Collection[string]
    Files Collection[File]
}

Properties

Property	Description
Fields	It contains all the text fields sent by the client.
Files	Contains all files sent using forms `multipart/form-data`.

Fields

ctx.Request.Form.Fields provides access to all the text fields sent by the client.

The fields of the form correspond to the values sent by HTML forms with the content types application/x-www-form-urlencoded and multipart/form-data.

gox

func POST(ctx *gox.Context) gox.Page {
    email, ok := ctx.Request.Form.Fields.Get("email")

    if !ok {
        return <p>Email required.</p>
    }

    return <p>{{ email }}</p>
}

Structure

ctx.Request.Form.Fields implement the following API:

text

Fields
{
    Get(key string) (string, bool)
    GetAll(key string) []string
    Has(key string) bool
    IsEmpty() bool
    Count() int
    Keys() []string
    Values() []string
    Entries() map[string][]string
}

All methods are read only.

Methods

Method	Description
Get()	Returns the first value associated with a field.
GetAll()	Returns all values associated with a field.
Has()	It indicates if a field exists.
IsEmpty()	It indicates whether the collection contains fields.
Count()	Returns the number of available fields.
Keys()	Give back the names of all the fields.
Values()	Returns the first value associated with each field.
Entries()	Returns all fields along with their values.

Get()

Firma:func (Fields) Get(key string) (string, bool)

Get() returns the first value associated with a field.

gox

func POST(ctx *gox.Context) gox.Page {
    email, ok := ctx.Request.Form.Fields.Get("email")

    if !ok {
        return <p>Email required.</p>
    }

    return <p>{{ email }}</p>
}

When the field does not exist, the second returned value will be false.

Use Get() when you only need to read a specific field.

GetAll()

Firma:func (Fields) GetAll(key string) []string

GetAll() returns all values associated with a field.

gox

func POST(ctx *gox.Context) gox.Page {
    tags := ctx.Request.Form.Fields.GetAll("tags")

    return <ul>
        <:for tag range={{ tags }}>
            <li>{{ tag }}</li>
        </:for>
    </ul>
}

This method is useful when the same field can appear several times within the form.

Has()

Firma:func (Fields) Has(key string) bool

Has() indicates if a field exists.

gox

func POST(ctx *gox.Context) gox.Page {
    if ctx.Request.Form.Fields.Has("remember") {
        return <p>Remember me enabled.</p>
    }

    return <p>Remember me disabled.</p>
}

Has() It only checks the existence of the field.

IsEmpty()

Firma:func (Fields) IsEmpty() bool

IsEmpty() indicates whether the collection does not contain fields.

gox

func POST(ctx *gox.Context) gox.Page {
    if ctx.Request.Form.Fields.IsEmpty() {
        return <p>No fields received.</p>
    }

    return <p>Fields available.</p>
}

A form may not contain fields when only files are sent or when the request does not include form data.

Count()

Firma:func (Fields) Count() int

Count() returns the number of available fields.

gox

func POST(ctx *gox.Context) gox.Page {
    total := ctx.Request.Form.Fields.Count()

    return <p>{{ total }}</p>
}

Each field name counts as a single element within the collection.

Keys()

Firma:func (Fields) Keys() []string

Keys() return the names of all fields.

gox

func POST(ctx *gox.Context) gox.Page {
    keys := ctx.Request.Form.Fields.Keys()

    return <ul>
        <:for key range={{ keys }}>
            <li>{{ key }}</li>
        </:for>
    </ul>
}

It can be used to inspect the names of all fields sent by the client.

Values()

Firma:func (Fields) Values() []string

Values() returns the first value associated with each field.

gox

func POST(ctx *gox.Context) gox.Page {
    values := ctx.Request.Form.Fields.Values()

    return <ul>
        <:for value range={{ values }}>
            <li>{{ value }}</li>
        </:for>
    </ul>
}

If you need to keep all the values associated with each field, use Entries().

Entries()

Firma:func (Fields) Entries() map[string][]string

Entries() returns all fields along with all their values.

gox

func POST(ctx *gox.Context) gox.Page {
    fields := ctx.Request.Form.Fields.Entries()

    // fields["email"]
    // fields["tags"]
    // fields["remember"]

    return <p>{{ len(fields) }}</p>
}

Each map key represents the name of a field and its associated value contains all the values received for that field.

Files

ctx.Request.Form.Files provides access to all files sent by the client using forms multipart/form-data.

Each file received is represented by an object File.

gox

func POST(ctx *gox.Context) gox.Page {
    avatar, ok := ctx.Request.Form.Files.Get("avatar")

    if !ok {
        return <p>No avatar uploaded.</p>
    }

    return <p>{{ avatar.Name() }}</p>
}

Structure

ctx.Request.Form.Files implement the following API:

text

Files
{
    Get(key string) (gox.File, bool)
    GetAll(key string) []gox.File
    Has(key string) bool
    IsEmpty() bool
    Count() int
    Keys() []string
    Values() []gox.File
    Entries() map[string][]gox.File
}

All methods are read only.

Methods

Method	Description
Get()	Returns the first file associated with a field.
GetAll()	Returns all files associated with a field.
Has()	It indicates whether a field contains files.
IsEmpty()	It indicates whether the collection contains files.
Count()	Returns the number of fields with files.
Keys()	Returns the names of all the fields containing files.
Values()	Returns the first file associated with each field.
Entries()	Returns all files along with your associated fields.

Get()

Firma:func (Files) Get(key string) (gox.File, bool)

Get() returns the first file associated with a field.

gox

func POST(ctx *gox.Context) gox.Page {
    avatar, ok := ctx.Request.Form.Files.Get("avatar")

    if !ok {
        return <p>No avatar uploaded.</p>
    }

    return <p>{{ avatar.Name() }}</p>
}

When the field does not exist, the second returned value will be false.

Use Get() when you only need to read a specific file.

GetAll()

Firma:func (Files) GetAll(key string) []gox.File

GetAll() returns all files associated with a field.

gox

func POST(ctx *gox.Context) gox.Page {
    photos := ctx.Request.Form.Files.GetAll("photos")

    return <p>{{ len(photos) }}</p>
}

This method is useful when the same field allows multiple files to be sent.

Has()

Firma:func (Files) Has(key string) bool

Has() indicates if a field contains files.

gox

func POST(ctx *gox.Context) gox.Page {
    if ctx.Request.Form.Files.Has("resume") {
        return <p>Resume uploaded.</p>
    }

    return <p>No resume uploaded.</p>
}

Has() It only checks the existence of the field.

IsEmpty()

Firma:func (Files) IsEmpty() bool

IsEmpty() indicates whether the collection does not contain files.

gox

func POST(ctx *gox.Context) gox.Page {
    if ctx.Request.Form.Files.IsEmpty() {
        return <p>No files received.</p>
    }

    return <p>Files available.</p>
}

The collection will be empty when the request does not include files.

Count()

Firma:func (Files) Count() int

Count() returns the number of fields that contain files.

gox

func POST(ctx *gox.Context) gox.Page {
    total := ctx.Request.Form.Files.Count()

    return <p>{{ total }}</p>
}

Each field name counts as a single element within the collection.

Keys()

Firma:func (Files) Keys() []string

Keys() returns the names of all the fields that contain files.

gox

func POST(ctx *gox.Context) gox.Page {
    keys := ctx.Request.Form.Files.Keys()

    return <ul>
        <:for key range={{ keys }}>
            <li>{{ key }}</li>
        </:for>
    </ul>
}

It can be used to inspect the names of all the fields that contain files.

Values()

Firma:func (Files) Values() []gox.File

Values() returns the first file associated with each field.

gox

func POST(ctx *gox.Context) gox.Page {
    files := ctx.Request.Form.Files.Values()

    return <p>{{ len(files) }}</p>
}

If you need to keep all the files associated with each field, use Entries().

Entries()

Firma:func (Files) Entries() map[string][]gox.File

Entries() returns all files along with all associated fields.

gox

func POST(ctx *gox.Context) gox.Page {
    files := ctx.Request.Form.Files.Entries()

    // files["avatar"]
    // files["documents"]
    // files["photos"]

    return <p>{{ len(files) }}</p>
}

Each map key represents the name of a field and its associated value contains all the files received for that field.

Full example

The following example shows several common operations on a form received by the server.

gox

func POST(ctx *gox.Context) gox.Page {
    form := ctx.Request.Form

    name, _ := form.Fields.Get("name")
    email, _ := form.Fields.Get("email")
    avatar, _ := form.Files.Get("avatar")

    return <main>
        <p>Nombre: {{ name }}</p>
        <p>Correo electrónico: {{ email }}</p>
        <p>Avatar: {{ avatar.Name() }}</p>

        <p>Total de campos: {{ form.Fields.Count() }}</p>
        <p>Total de campos con archivos: {{ form.Files.Count() }}</p>
    </main>
}

Best practices

Use Fields to access text fields.
Use Files to access files sent through forms multipart/form-data.
Check the boolean value returned by Get() when a field may not exist.
Use GetAll() when the same name can appear several times.
Use Entries() when you need to go through the whole collection.
Use Actions when you are not working with traditional HTTP client or REST API.
Always value the information received before using it.

Next step

Continue with the documentation for Body to learn how to access the unprocessed content of the body of an HTTP request.

Body

Form

Structure

Properties

Fields

Structure

Methods

Get()

GetAll()

Has()

IsEmpty()

Count()

Keys()

Values()

Entries()

Files

Structure

Methods

Get()

GetAll()

Has()

IsEmpty()

Count()

Keys()

Values()

Entries()

Full example

Best practices

See also

Next step