Documentation
¶
Overview ¶
Package pagination implements helper functions for request handlers which present results organized in numbered pages.
This package can only be used with named handlers (registered via app.App.HandleNamed) and having patterns with no optional groups. (e.g. no "(something)?").
Paging in this package assumes the following:
- Pages start at 1.
- The first page URL does not include the page number.
- Other pages end with someprefix-<page-number>-somesuffix (see Pattern).
- A URL with the page number set to 0 or 1 produces a redirect.
- A URL with the page number > the available number of pages produces a 404.
A typical handler using this package would look something like this.
Registered as: App.HandleNamed("/popular/" + pagination.Pattern("", "/") + "$", PopularHandler, "popular")
func PopularHandler(ctx *app.Context) {
const itemsPerPage = 15
q := ctx.Orm().Query(... some conditions ...)
count := q.Table(o.NameTable("Item")).MustCount()
p := pagination.New(ctx, int(count), itemsPerPage)
if p == nil {
// Request had an invalid page number and has been
// already served
return
}
var items []*Item
p.Page(p.Page(), itemsPerPage).MustAll(&items)
data := map[string]interface{}{
"Items": items,
"Page": p.Page(),
"Paginator": p.Paginator(),
}
ctx.MustExecute("items.html", data)
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Pattern ¶
Pattern returns the pattern required to append to an existing pattern in order to perform pagination using this package. The prefix argument will be part of the URL just before the page.
For example, with a handler pattern like "/popular/"
- Pattern("", "/") will generate pages like "/popular/7/"
- Pattern("", "") will generate pages like "/popular/7"
- Pattern("page-", "/") will generate pages like "/popular/page-7/"
To register a handler with the pattern, someone might write:
myapp.HandleNamed("/popular/" + pagination.Pattern("", "/") + "$", PopularHandler, "popular")
Where myapp is a gnd.la/app.App instance.
Types ¶
type Pager ¶
type Pager struct {
// The handler name to reverse
Name string
// Parameters to pass to reverse *BEFORE* the page
// number. The page number will be appended to this
// slice, so it must be always the last parameter
Parameters []interface{}
// The current Context received in your handler.
Ctx *app.Context
}
Pager implements the paginator.Pager interface, using Context.Reverse to obtain the page URL. The handler pattern MUST end with an optional group which contains a captured group named "page". The rest of parameters MUST be mandatory and might or might not be named.
In practice, this means the pattern must not have any optional groups except the one containing the page and must end with something like:
(?:(?P<page>\\d+)/)?$
Note that the optional group might contain anything else. e.g. this pattern would also be valid.
(?:page-(?P<page>\\d+)/)?$
One complete pattern might look like this:
App.HandleNamed("^/c/(\\d+)/(?:(?P<page>\\d+)/)?$", ListHandler, "category")
The Parameters field must contain all values to be passed to Context.Reverse except the page number itself. The Pager will append the page number for each page != 1.
Note that most users should not use this type directly, but rather use the more complete Pagination type from this package.
type Pagination ¶
type Pagination struct {
// contains filtered or unexported fields
}
Pagination is an opaque type encapsulating the pagination data Callers should just create a new Pagination from an app.Context using New and retrieve the current page using its Pagination.Page method.
func New ¶
func New(ctx *app.Context, itemCount int, itemsPerPage int) *Pagination
New returns a new *Pagination for the given app.Context, item count and number of items per page. If there's a programming error, this function will panic. If this function returns nil, an invalid page was specified e.g. (user typed a URL with the 0 or 1 page number) and you should consider the request as served and not write anything else to the app.Context.
func (*Pagination) Page ¶
func (p *Pagination) Page() int
Page returns the current page number. Note that pages start at 1.
func (*Pagination) Paginator ¶
func (p *Pagination) Paginator() *paginator.Paginator
Paginator returns a new *paginator.Paginator prepared to be rendered by a template.
Source Files