Context
Every time GOX runs a page or an Action, it creates a gox.Context associated with that request.
The Context collects all the information needed to process the current request and build the response. From it it it it is possible to access the HTTP request, modify the response, work with the session, read the received body and consult information about any errors associated with the request.
In other words, everything related to the current request is within the gox.Context.
Although gox.Context exposes some properties used internally by the GOX runtime, this documentation focuses only on the public API designed for application development.
Access to the Context
The Context is always received as a parameter for a page or an Action.
func GET(ctx *gox.Context) gox.Page {
return <h1>Hello GOX</h1>
}func Login(form LoginForm, ctx *gox.Context) gox.Action {
return "OK"
}Each request is given its own instance of gox.Contextand so the information contained therein corresponds to the request being implemented at that time.
Pages and Actions use the same type of Context. The difference between the two mechanisms is in the way of declaring their functions, processing their parameters and building their responses. Pages and Actions.
Context components
gox.Context It brings together different specialized properties, each responsible for a specific part of the life cycle of the request.
| Property | Description |
|---|---|
Request | Information on the current HTTP request. |
Response | It allows to configure and finish the HTTP response. |
Session | Access to the session associated with the request. |
Body | Reading and transformation of the body received. |
Error | Information about the current error when it exists. |
Each of these properties has its own documentation and can be used independently.
Most applications use ctx.Request and ctx.Response during the usual processing of requests, while Session, Body and Error are available when the application flow requires them.
Request
ctx.Request provides access to information received from the client.
It is possible to consult the HTTP method, the requested URL, the route parameters, the IP address, the headers, cookies, the query parameters and the rest of the information related to the request.
func GET(ctx *gox.Context) gox.Page {
ip := ctx.Request.IP()
return <span>{{ ip }}</span>
}See the full documentation at Request.
Response
ctx.Response allows to configure the response before GOX sends it to the client.
It can be used to set headers, modify the HTTP status code, create cookies, redirect or immediately complete the request by DoneWith.
func GET(ctx *gox.Context) gox.Page {
if !CurrentUser(ctx).IsAdmin() {
ctx.Response.DoneWith(403)
}
return <h1>Panel de administración</h1>
}When DoneWith receives an error code and no custom response is provided, GOX can run the corresponding handler defined in pages/.error.gox.
See the full documentation at Response and Error pages.
Session
ctx.Session provides access to the session associated with the current request.
It can be used to store persistent information between different requests, such as the authenticated user, the status of an operation or the preferences of the application.
func GET(ctx *gox.Context) gox.Page {
var userID string
if ok, err := ctx.Session.Get("user_id", &userID); err != nil || !ok {
return <span>Guest</span>
}
return <span>{{ userID }}</span>
}Get receives the key you want to consult and a pointer where GOX will write the stored value.
The Boolean value indicates whether the key exists, while the error reports whether a problem occurred during the reading of the session.
See the full documentation at Session.
Body
ctx.Body simplifies the reading and transformation of the body of the request.
It allows you to obtain the content received as text or bytes, convert it directly to a Go structure or write it to another destination.
func POST(ctx *gox.Context) gox.Page {
text := ctx.Body.ToText()
return <pre>{{ text }}</pre>
}See the full documentation at Body.
Error
When an request ends with an error, GOX makes additional information available by ctx.Error.
During the execution of a normal page, this value is usually nil. Within an error page contains information about the error that caused the response.
func Error404(ctx *gox.Context) gox.Page {
return <h1>
{{ ctx.Error.GetStatusCode() }}
-
{{ ctx.Error.GetStatusMessage() }}
</h1>
}Error handlers are declared within the special file:
pages/.error.goxSee the full documentation at Error and Error pages.
Lifecycle
The Context exists only during the execution of the current request.
Once the response is completed, the Context should not be stored or used later.
var saved *gox.Context
func GET(ctx *gox.Context) gox.Page {
saved = ctx
return "Hello"
}Save a reference to the Context for use after the request is finished can produce unexpected behaviors and is not supported.
The Context must always remain within the scope of the page, Action or auxiliary function that is processing the current request.
Integration with Go
gox.Context It's a normal Go pointer.
It can be moved to other functions or packages as long as the request remains active.
func GET(ctx *gox.Context) gox.Page {
LogRequest(ctx)
return "Hello GOX"
}
func LogRequest(ctx *gox.Context) {
// ...
}This allows to organize the logic of the application using normal Go functions, packages, structures and interfaces, without depending on global variables or shared states.
Best practices
- Keep the Context within the scope of the current request.
- Use
ctx.Requestfor information received from the client. - Configure and finish the response by
ctx.Response. - Use
ctx.Sessionto store information to be maintained between requests. - Use
ctx.Bodyto read and transform the body received. - See
ctx.Erroronly where there is an error associated with the request. - Avoid directly using properties intended for the internal operation of GOX.
- See the specific documentation for each property to know your entire API.