gowww/app is a full featured HTTP framework for any web app.
It greatly increases productivity by providing helpers at all levels while maintaining best performance.

• Start
• Routing
  • Path parameters
    • Named
    • Regular expressions
    • Wildcard
  • Groups
  • Errors
• Context
  • Request
  • Response
  • Values
• Views
  • Data
    • Built-in
  • Functions
    • Built-in
• Validation
• Internationalization
• Static files
• Running
• Middlewares

Start

1. Install Go

2. Install gowww/app:

   go get github.com/gowww/app

3. Import it in your new app:

   import "github.com/gowww/app"

Routing

There are methods for common HTTP methods:

app.Get("/", func(c *app.Context) {// Write response for GET /})app.Post("/", func(c *app.Context) {// Write response for POST /})app.Put("/", func(c *app.Context) {// Write response for PUT /})app.Patch("/", func(c *app.Context) {// Write response for PATCH /})app.Delete("/", func(c *app.Context) {// Write response for DELETE /})

Path parameters

Named

A named parameter begins with: and matches any value until the next/ in path.

To retrieve the value, askContext.PathValue.
It will return the value as a string (empty if the parameter doesn't exist).

Example, with a parameterid:

app.Get("/users/:id", func(c *app.Context) {id := c.PathValue("id")fmt.Fprintf(w, "Page of user #%s", id)}))

Regular expressions

If a parameter must match an exact pattern (digits only, for example), you can also set aregular expression constraint just after the parameter name and another::

app.Get(`/users/:id:^\d+$`, func(c *app.Context) {id := c.PathValue("id")fmt.Fprintf(w, "Page of user #%s", id)}))

If you don't need to retrieve the parameter value but only use a regular expression, you can omit the parameter name.

Wildcard

A trailing slash behaves like a wildcard by matching the beginning of the request path and keeping the rest as a parameter value, under*:

rt.Get("/files/", func(c *app.Context) {filepath := c.PathValue("*")fmt.Fprintf(w, "Get file %s", filepath)}))

For more details, seegowww/router.

Groups

A routing group works like the top-level router but prefixes all subroute paths:

api := app.Group("/api"){v1 := api.Group("/v1"){v1.Get("/user", func(c *app.Context) { /* Write response for GET /api/v1/user */ })v1.Get("/item", func(c *app.Context) { /* Write response for GET /api/v1/item */ })}v2 := api.Group("/v2"){v2.Get("/user", func(c *app.Context) { /* Write response for GET /api/v2/user */ })v2.Get("/item", func(c *app.Context) { /* Write response for GET /api/v2/item */ })}}

Errors

You can set a custom "not found" handler withNotFound:

app.NotFound(func(c *app.Context) {c.Status(http.StatusNotFound)c.View("notFound")})

The app is also recovered from panics so you can set a custom "serving error" handler (which is used only when the response is not already written) withError and retrieve the recovered error value withContext.Error:

app.Error(func(c *app.Context) {c.Status(http.StatusInternalServerError)if c.Error() == ErrCannotOpenFile {c.View("errorStorage")return}c.View("error")})

Context

AContext is always used inside aHandler.
It contains the original request and response writer but provides all the necessary helpers to access them:

Request

UseContext.Req to access the original request:

app.Get("/", func(c *app.Context) {r := c.Req})

UseContext.FormValue to access a value from URL or body.
You can also useContext.HasFormValue to check its existence:

app.Get("/", func(c *app.Context) {if c.HasFormValue("id") {id := c.FormValue("id")}})

Response

UseContext.Res to access the original response writer:

app.Get("/", func(c *app.Context) {w := c.Res})

UseContext.Text orContext.Bytes to send a string:

app.Get("/", func(c *app.Context) {c.Text("Hello")c.Bytes([]byte("World"))})

UseContext.JSON to send a JSON formatted response (if implemented by argument,JSON() interface{} will be used):

app.Get(`/users/:id:^\d+$/files/`, func(c *app.Context) {c.JSON(map[string]interface{}{"userID":   c.PathValue("id"),"filepath": c.PathValue("*"),})})

UseContext.Status to set the response status code:

app.Get("/", func(c *app.Context) {c.Status(http.StatusCreated)})

UseContext.NotFound to send a "not found" response:

app.Get("/", func(c *app.Context) {c.NotFound()})

UseContext.Panic to log an error and send a "serving error" response:

app.Get("/", func(c *app.Context) {c.Panic("database connection failed")})

UseContext.Redirect to redirect the client:

app.Get("/old", func(c *app.Context) {c.Redirect("/new", http.StatusMovedPermanently)})

UseContext.Push to initiate an HTTP/2 server push:

app.Get("/", func(c *app.Context) {c.Push("/static/main.css", nil)})

Values

You can use context values kept inside the context for future usage downstream (like views or subhandlers).

UseContext.Set to set a value:

app.Get("/", func(c *app.Context) {c.Set("clientCountry", "UK")})

UseContext.Get to retrieve a value:

app.Get("/", func(c *app.Context) {clientCountry := c.Get("clientCountry")})

Views

Views are standardGo HTML templates and must be stored inside theviews directory.
They are automatically parsed during launch.

UseContext.View to send a view:

app.Get("/", func(c *app.Context) {c.View("home")})

Data

Use aViewData map to pass data to a view.

You can also useGlobalViewData to set data for all views:

app.GlobalViewData(app.ViewData{"appName": "My app",})app.Get("/", func(c *app.Context) {user := &User{ID:   1,Name: "John Doe",}c.View("home", app.ViewData{"user": user,})})

Inviews/home.gohtml:

{{define "home"}}<h1>Hello {{.user.Name}} ({{.c.Req.RemoteAddr}}) and welcome on {{.appName}}!</h1>{{end}}

Built-in

This data is always passed to the views, out of the box:

Functions

UseGlobalViewFuncs to set functions for all views:

app.GlobalViewFuncs(app.ViewFuncs{"pathescape": url.PathEscape,})app.Get("/posts/new", func(c *app.Context) {c.View("postsNew")})

Inviews/posts.gohtml:

{{define "postsNew"}}<a href="/sign-in?return-to={{pathescape "/posts/new"}}">Sign in</a>{{end}}

Built-in

In addition to the functions provided by the standardtemplate package, these function are also available out of the box:

Validation

Validation is handled bygowww/check.

Firstly, make aChecker withrules for keys:

userChecker := check.Checker{"email":   {check.Required, check.Email, check.Unique(db, "users", "email", "?")},"phone":   {check.Phone},"picture": {check.MaxFileSize(5000000), check.Image},}

The rules order is significant so for example, it's smarter to check the format of a value before its uniqueness, avoiding some useless database requests.

UseContext.Check to check the request against a checker:

errs := c.Check(userChecker)

UseErrors.Empty orErrors.NotEmpty to know if there are errors and handle them like you want.
You can also translate error messages withContext.TErrors:

if errs.NotEmpty() {c.Status(http.StatusBadRequest)c.View(view, app.ViewData{"errors": errs})return}

But usually, when a check fails, you only want to send a response with error messages.
Here comes theBadRequest shortcut which receives a checker and a view name.
If you don't provide a view name (empty string), the response will be a JSON errors map.

If the check fails, it sets the status to "400 Bad Request", sends the response (view or JSON) and returnstrue, allowing you to exit from the handler:

app.Post("/join", func(c *app.Context) {if c.BadRequest(userChecker, "join") {return}// Handle request confidently})

In views, you can retrieve theTranslatedErrors map under keyerrors which is nevernil in view data:

<input type="email" name="email" value="{{.email}}">{{if .errors.Has "email"}}<div class="error">{{.errors.First "email"}}</div>{{end}}

Internationalization

Internationalization is handled bygowww/i18n.

Firstly, make your translations map (string to string, for each language):

locales := i18n.Locales{language.English: {"hello": "Hello!",},language.French: {"hello": "Bonjour !",},}

UseLocalize to register it and set the default locale (used as a fallback):

app.Localize(locales, language.English)

MethodsContext.T,Context.Tn,Context.THTML andContext.TnHTML are now operational.
As theContext is always part of the view data, you can use these methods in views:

<h1>{{.c.T "hello"}}</h1>

Static files

Static files must be stored inside thestatic directory.
They are automatically accessible from the/static/ path prefix.

Running

CallRun at the end of your main function:

app.Run()

By default, your app will listen and serve on:8080.
But you can change this address by using flag-a when running your app:

./myapp -a :1234

Middlewares

Custom middlewares can be used if they are compatible with standard interfacenet/http.Handler.
They can be set for:

• The entire app:

  app.Run(hand1, hand2, hand3)

• A group:

  api := app.Group("/api", hand1, hand2, hand3)

• A single route:

  api := app.Get("/", func(c *app.Context) {// Write response for GET /}, hand1, hand2, hand3)

First handler wraps the second and so on.

package mainimport ("log""net/http""github.com/gowww/app""github.com/gowww/i18n""golang.org/x/text/language")func main() {var locales = i18n.Locales{language.English: {"hello": "Hello!",},language.French: {"hello": "Bonjour !",},}app.Localize(locales, language.English)app.Get("/", func(c *app.Context) {c.View("home")})app.Post("/user/:id/files/", func(c *app.Context) {c.Status(http.StatusCreated)c.JSON(map[string]interface{}{"id":       c.PathValue("id"),"filepath": c.PathValue("*"),})})v1 := app.Group("/v1"){v1.Get("/user", func(c *app.Context) { c.Text("User for V1") })v1.Get("/item", func(c *app.Context) { c.Text("Item for V1") })}v2 := app.Group("/v2"){v2.Get("/user", func(c *app.Context) { c.Text("User for V2") })v2.Get("/item", func(c *app.Context) { c.Text("Item for V2") })}if !app.EnvProduction() {log.Printf("Developing app on %s\n", app.Address())}app.Run()}

Constants¶

Variables¶

Functions¶

func Address()string

func Delete(pathstring, handlerHandler, middlewares ...Middleware)

func Encrypter()crypto.Encrypter

func EnvProduction()bool

func Error(handlerHandler)

func Get(pathstring, handlerHandler, middlewares ...Middleware)

func GlobalViewData(dataViewData)

func GlobalViewFuncs(funcsViewFuncs)

func Localize(locsi18n.Locales, fallbacklanguage.Tag, parsers ...i18n.Parser)

func NotFound(handlerHandler)

func Patch(pathstring, handlerHandler, middlewares ...Middleware)

func Post(pathstring, handlerHandler, middlewares ...Middleware)

func Put(pathstring, handlerHandler, middlewares ...Middleware)

func Route(method, pathstring, handlerHandler, middlewares ...Middleware)

func Run(mm ...Middleware)

func Secret(keystring)

func Secure(o *secure.Options)

Types¶

type Context struct {Reshttp.ResponseWriterReq *http.Request}

func (c *Context) BadRequest(checkercheck.Checker, viewstring, data ...ViewData)bool

package mainimport ("net/http""github.com/gowww/app""github.com/gowww/check")func main() {userChecker := check.Checker{"email": {check.Required, check.Email},"phone": {check.Phone},}app.Post("/users", func(c *app.Context) {if c.BadRequest(userChecker, "") {return}c.Status(http.StatusCreated)})}

func (c *Context) Bytes(b []byte)

func (c *Context) Check(checkercheck.Checker)check.Errors

func (c *Context) Cookie(namestring)string

func (c *Context) DeleteCookie(namestring)

func (c *Context) Error()error

func (c *Context) FmtNumber(n interface{})string

func (c *Context) FormValue(keystring)string

func (c *Context) Get(key interface{}) interface{}

func (c *Context) HasFormValue(keystring)bool

func (c *Context) JSON(v interface{})

func (c *Context) Locale()language.Tag

func (c *Context) Log(msgstring)

func (c *Context) NotFound()

func (c *Context) Panic(errerror)

func (c *Context) PathValue(keystring)string

func (c *Context) Push(targetstring, opts *http.PushOptions)

func (c *Context) Redirect(urlstring, statusint)

func (c *Context) Set(key, val interface{})

func (c *Context) SetCookie(cookie *http.Cookie)

func (c *Context) Status(codeint) *Context

func (c *Context) T(keystring, a ...interface{})string

func (c *Context) TErrors(errscheck.Errors)check.TranslatedErrors

func (c *Context) THTML(keystring, a ...interface{})template.HTML

func (c *Context) Text(sstring)

func (c *Context) Textf(sstring, a ...interface{})

func (c *Context) Tn(keystring, nint, args ...interface{})string

func (c *Context) TnHTML(keystring, nint, args ...interface{})template.HTML

func (c *Context) View(namestring, data ...ViewData)

.the GlobalViewData.cthe Context.errorsthe translated errors map

func (c *Context) Write(b []byte) (int,error)

type Handler func(*Context)

func (hHandler) ServeHTTP(whttp.ResponseWriter, r *http.Request)

type Middleware func(http.Handler)http.Handler

type RouterGroup struct {// contains filtered or unexported fields}

func Group(pathstring, middlewares ...Middleware) *RouterGroup

func (rg *RouterGroup) Delete(pathstring, handlerHandler, middlewares ...Middleware)

func (rg *RouterGroup) Get(pathstring, handlerHandler, middlewares ...Middleware)

func (rg *RouterGroup) Group(pathstring, middlewares ...Middleware) *RouterGroup

func (rg *RouterGroup) Patch(pathstring, handlerHandler, middlewares ...Middleware)

func (rg *RouterGroup) Post(pathstring, handlerHandler, middlewares ...Middleware)

func (rg *RouterGroup) Put(pathstring, handlerHandler, middlewares ...Middleware)

func (rg *RouterGroup) Route(method, pathstring, handlerHandler, middlewares ...Middleware)

type ViewData map[string]interface{}

type ViewFuncs map[string]interface{}