pagination

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

• func Pattern(prefix string, suffix string) string
• type Pager
  • func NewPager(ctx *app.Context) (*Pager, error)
  • func (p *Pager) URL(page int) string
• type Pagination
  • func New(ctx *app.Context, itemCount int, itemsPerPage int) *Pagination
  • func (p *Pagination) Page() int
  • func (p *Pagination) Paginator() *paginator.Paginator

Functions

func Pattern

func Pattern(prefix string, suffix string) string

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.

func NewPager

func NewPager(ctx *app.Context) (*Pager, error)

NewPager returns a new *Pager instance. Note that the Context must satisfy the conditions mentioned in the Pager type documentation. Otherwise an error will be returned.

func (*Pager) URL

func (p *Pager) URL(page int) string

URL returns the given page URL by using gnd.la/app.Context.Reverse.

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.