Error pages

GOX allows you to customize the generated responses when an request ends with an HTTP error.

These pages are used to answer errors like 403, 404 or 500in addition to any other state code between 400 and 599.

Error pages use the same capabilities as any other gox.Page, so they can build templates, use components and access the gox.Context.

Special file

Error pages are defined in a special file located in the directory pages/.

text
pages/
└── .error.gox

This file can declare one or more error handlers.

gox
module error

import "github.com/gox-lang/gox"

func Default(ctx *gox.Context) gox.Page {
    return <span>
        {{ ctx.Error.GetStatusCode() }}
        -
        {{ ctx.Error.GetStatusMessage() }}
    </span>
}

func Error404(ctx *gox.Context) gox.Page {
    return <span>Página no encontrada.</span>
}

func Error500(ctx *gox.Context) gox.Page {
    return <span>Error interno del servidor.</span>
}

GOX automatically detects this file during boot and uses it to respond HTTP errors.

Specific handlers

Each function represents a specific HTTP status code.

gox
func Error403(ctx *gox.Context) gox.Page
gox
func Error404(ctx *gox.Context) gox.Page
gox
func Error500(ctx *gox.Context) gox.Page

When an request ends with a given status code, GOX tries to run the corresponding handler.

Default handler

In addition to specific handlers, a function can be declared Default.

gox
func Default(ctx *gox.Context) gox.Page {
    return <span>
        {{ ctx.Error.GetStatusCode() }}
        -
        {{ ctx.Error.GetStatusMessage() }}
    </span>
}

GOX uses this handler when there is no specific function for the generated status code.

Handler resolution

When an error occurs, GOX tries to solve the response using the following order.

text
Error<status>
        ↓
Default
        ↓
Respuesta interna del servidor

For example, a mistake 404 use the next flow.

text
Error404
        ↓
Default
        ↓
Respuesta interna

Error context

During the execution of an error page, ctx.Error contains information on the error that caused the response.

gox
func Error404(ctx *gox.Context) gox.Page {

    return <main>
        <h1>{{ ctx.Error.GetStatusCode() }}</h1>

        <p>{{ ctx.Error.GetStatusMessage() }}</p>
    </main>
}

On a normal page, ctx.Error It usually is nil.

The complete documentation for this object is found in Error.

End a response with an error

A page can also end the response by using ctx.Response.DoneWith.

gox=
func GET(ctx *gox.Context) gox.Page {

    if !CurrentUser(ctx).IsAdmin() {
        ctx.Response.DoneWith(403)
    }

    return <h1>Panel de administración</h1>
}

When the status code represents an HTTP error, GOX interrupts the execution of the page and runs the corresponding handler defined in .error.gox.

Custom response

DoneWith also allows to respond immediately using a specific component.

gox
func AccessDenied() gox.Component {
    return <h1>Access denied</h1>
}

func GET(ctx *gox.Context) gox.Page {

    if !CurrentUser(ctx).IsAdmin() {
        ctx.Response.DoneWith(
            403,
            AccessDenied,
        )
    }

    return <h1>Panel de administración</h1>
}

When a component is provided, GOX directly uses that content as a response and does not run the handlers defined in .error.gox.

Lifecycle

The error pages are part of the normal GOX response cycle.

For this reason, they can only be executed as long as the HTTP response has not yet started to be sent to the client.

Once GOX starts writing the response body, it is no longer possible to replace it with a custom error page.

Integration with Go

Error pages are normal Go functions.

They can use components, auxiliary functions, structures, interfaces and any other language feature to build the response.

gox
func Error500(ctx *gox.Context) gox.Page {

    support := "[email protected]"

    return <main>
        <h1>Internal Server Error</h1>

        <p>
            Contact {{ support }}
        </p>
    </main>
}

Best practices

  • Define a handler Default to cover any non-personalized status code.
  • Create specific handlers only when the response must be different.
  • Use ctx.Response.DoneWith to end the response when the error is part of the normal flow of the application.
  • Use ctx.Error only within the error pages.
  • Avoid revealing internal application information in error responses.

To learn more about PagesSee your documentation. To learn more about ContextSee your documentation. To learn more about Response, check your documentation.

See also

Next step

Continue with the documentation for Context to learn how to access the request, response, session and other features available during the execution of a page.

Context