NAME

App::Dapper::Collections - Category pages, tag pages and pagination.

DESCRIPTION

After the source files are read, Dapper can generate a page for each category and each tag, and split long lists of pages across several pages.

Category and tag pages are turned on in _config.yml, and are rendered with the layout you name:

category_pages:
  layout: category        # _layout/category.html
  urlpattern: /:category/ # the default
  per_page: 10            # optional: split into pages of 10
tag_pages:
  layout: tag
  urlpattern: /tags/:tag/ # the default

Each generated page has page.title (the category or tag), page.category or page.tag, and page.posts (its pages, newest first). With per_page, page.posts holds just the pages for that page, and paginator describes the whole set. The URL of each one is in site.category_pages and site.tag_pages, so layouts can link to them:

<a href="[% site.tag_pages.$tag %]">[% tag %]</a>

Any page can list pages across several pages with paginate in its front matter:

paginate:
  category: blog     # or tag: perl; leave both out for every post
  per_page: 10

In its layout (or its content, with template: true), paginator.items holds that page's share of the posts, newest first.

The paginator

paginator.items          the pages to show on this page
paginator.page           this page's number, starting at 1
paginator.per_page       pages per page
paginator.total_pages    how many pages there are
paginator.total_items    how many items there are
paginator.previous_url   the URL of the previous page (if there is one)
paginator.next_url       the URL of the next page (if there is one)
paginator.first_url, paginator.last_url
paginator.pages          a list of { number, url } for every page

Page 1 keeps the page's own URL; page 2 is at page/2/ below it.

generate

Takes the Dapper object, adds category and tag pages to the site if they are turned on, and expands every paginated page into its set of pages.

list_pages

Takes the Dapper object, the kind of list (category or tag), the hash of names to pages, the hash to record each list page's URL in, and the settings from _config.yml. Returns the generated pages.

paginate

Takes the Dapper object and a page. If the page has paginate settings, returns the page followed by its further pages, each with a paginator; otherwise returns the page unchanged.

items_for

Takes the site and pagination settings, and returns the pages to paginate, newest first: those in the category or with the tag, or every page with a category if neither is given.

base_url

Takes a URL and returns the directory the further pages go in: /blog/ stays /blog/, and /archive.html becomes /archive/.

set_filename

Takes the Dapper object and a page with a url, and sets the page's filename and dirname from it. A URL ending in / is written as an index file.