Splits a sequence of documents into multiple pages.

This module forms pages from the output documents of the specified modules. Each input document is cloned for each page and metadata related to the pages, including the sequence of documents for each page, is added to each clone. For example, if you have 2 input documents and the result of paging is 3 pages, this module will output 6 documents. Note that if there are no documents to paginate, this module will still output an empty page without any documents inside the page.

Examples

If your input document is a Razor template for a blog archive, you can use Paginate to get pages of 10 blog posts each. If you have 50 blog posts, the result of the Paginate module will be 5 copies of your input archive template, one for each page. Your configuration file might look something like this:

 Pipelines.Add("Posts",
     ReadFiles("*.md"),
     Markdown(),
     WriteFiles("html")
 );

 Pipelines.Add("Archive",
     ReadFiles("archive.cshtml"),
     Paginate(10,
         Documents("Posts")
     ),
     Razor(),
     WriteFiles(string.Format("archive-{0}.html", @doc["CurrentPage"]))
 );

Usage

Paginate(int pageSize, IEnumerable<IModule> modules)

Partitions the result of the specified modules into the specified number of pages. The input documents to Paginate are used as the initial input documents to the specified modules.
- pageSize
  The number of documents on each page.
- modules
  The modules to execute to get the documents to page.
Paginate(int pageSize, params IModule[] modules)

Partitions the result of the specified modules into the specified number of pages. The input documents to Paginate are used as the initial input documents to the specified modules.
- pageSize
  The number of documents on each page.
- modules
  The modules to execute to get the documents to page.

Fluent Methods

Chain these methods together after the constructor to modify behavior.

SkipPages(int count)

Skips a specified number of pages before outputting pages.
- count
  The number of pages to skip.
TakePages(int count)

Only outputs a specific number of pages.
- count
  The number of pages to output.
Where(DocumentConfig predicate)

Limits the documents to be paged to those that satisfy the supplied predicate.
- predicate
  A delegate that should return a bool.
WithPageMetadata(string key, DocumentConfig metadata)

Adds the specified metadata to each page index document. This must be performed within the paginate module. If you attempt to process the page index documents from the paginate module after execution, it will "disconnect" metadata for those documents like Wyam.Common.Meta.Keys.NextPage since you're effectivly creating new documents and the ones those keys refer to will be outdated.
- key
  The key of the metadata to add.
- metadata
  A delegate with the value for the metadata.

Output Metadata

The metadata values listed below apply to individual documents and are created and set by the module as indicated in their descriptions.

Keys.CurrentPage: System.Int32

The index of the current page (1 based).
Keys.HasNextPage: System.Boolean

Whether there is another page after this one.
Keys.HasPreviousPage: System.Boolean

Whether there is another page before this one.
Keys.NextPage: Wyam.Common.Documents.IDocument

The next page.
Keys.PageDocuments: IEnumerable<IDocument>

Contains all the documents for the current page.
Keys.PreviousPage: Wyam.Common.Documents.IDocument

The previous page.
Keys.TotalItems: System.Int32

The total number of items across all pages.
Keys.TotalPages: System.Int32

The total number of pages.