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.