docpad-plugin-paged
v2.6.0
Published
DocPad plugin which adds the ability to render a document out to multiple pages
Downloads
633
Maintainers
Readme
This plugin provides DocPad with Paging. Documents can declare a number of pages that should be rendered for the document, or a collection over which the document should be rendered repeatedly.
Install this DocPad plugin by entering docpad install paged into your terminal.
Usage
Explanation
The Paged plugin works by scanning the meta data of your document and looking for the isPaged: true
meta data attribute.
- If you are wanting to page a listing of documents, then you would want to pass over the
pagedCollection: 'collectionName'
meta data attribute with the collection name being whatever collection you are listing. - If you are wanting to split the current document into multiple pages, then you want to specify the
pageCount: 5
meta data attribute, where 5 is how many pages you want to have - You can also specify the
pageSize: 5
meta data attribute (defaults to1
) which indicates how many max items should be listed on an individual page
That being done, paged will scan your documents in the renderBefore
action and clone your paged document for each page that will be needed. Setting the following attributes for each page document:
{
count: 10 # total number of pages
size: 5 # expected number of documents per page
number: 0 # current page number
startIdx: 0 # position of the first item in this page
endIdx: 5 # position of the last item in this page
pages: [50,1] # document ids for each of the pages
}
You will interact with the paged plugin via the following template helpers that the paged plugin defines for you:
hasPrevPage(document ?= @getDocument())
hasNextPage(document ?= @getDocument())
getPrevPage(document ?= @getDocument())
getNextPage(document ?= @getDocument())
getPagedUrl(pageNumber ?= 0, document ?= @getDocument())
It is important to note, that as the paged plugin clones the original document and injects the clones directly into the DocPad database, the extra pages (the clones) could appear in your content listings. To avoid this, be sure that your content listings filter out everything that has: isPagedAuto: true
. For instance, a custom posts collection with the change applied would probably look like this:
module.exports =
collections:
posts: ->
@getCollection('html').findAllLive(
relativeOutDirPath: 'posts'
isPagedAuto: $ne: true
)
Example: Paging a Collection Listing
Here is an example where we say create a src/documents/posts.html.eco
file that pages out our posts
custom collection.
It will create documents for each page for the posts
collection in groups of 3. The first 3 documents in the collection will be rendered into a file called posts.html
as normal, then the remaining documents from the collection will be rendered into subsequent files posts.1.html
, posts.2.html
, posts.3.html
etc.
---
title: 'Home'
layout: 'default'
isPaged: true
pagedCollection: 'posts'
pageSize: 3
---
<!-- Page Content -->
<% for document in @getPageCollection('posts').toJSON(): %>
<article id="post" class="post">
<h1><a href='<%=document.url%>'><%= document.title %></a></h1>
<div class="post-date"><%= document.date.toLocaleDateString() %></div>
<div class="post-content">
<%- document.contentRenderedWithoutLayouts %>
</div>
</article>
<% end %>
<!-- Page Listing -->
<div class="pagination">
<ul>
<!-- Previous Page Button -->
<% unless @hasPrevPage(): %>
<li class="disabled"><span>Prev</span></li>
<% else: %>
<li><a href="<%= @getPrevPage() %>">Prev</a></li>
<% end %>
<!-- Page Number Buttons -->
<% for pageNumber in [[email protected]]: %>
<% if @document.page.number is pageNumber: %>
<li class="active"><span><%= pageNumber + 1 %></span></li>
<% else: %>
<li><a href="<%= @getPagedUrl(pageNumber) %>"><%= pageNumber + 1 %></a></li>
<% end %>
<% end %>
<!-- Next Page Button -->
<% unless @hasNextPage(): %>
<li class="disabled"><span>Next</span></li>
<% else: %>
<li><a href="<%= @getNextPage() %>">Next</a></li>
<% end %>
</ul>
</div>
Example: Splitting a Document into Multiple Pages
In this example we will split up a document say src/documents/posts/awesome.html.eco
into 3 pages that have a max of 3 items per page.
---
title: 'Awesome Pages Post'
layout: 'default'
isPaged: true
pageCount: 3
pageSize: 1
---
<!-- Page Content -->
<% if @document.page.number is 0: %>
first awesome page
<% else if @document.page.number is 1: %>
second awesome page
<% else if @document.page.number is 2: %>
third awesome page
<% end %>
<!-- Page Listing -->
<div class="pagination">
<ul>
<!-- Previous Page Button -->
<% unless @hasPrevPage(): %>
<li class="disabled"><span>Prev</span></li>
<% else: %>
<li><a href="<%= @getPrevPage() %>">Prev</a></li>
<% end %>
<!-- Page Number Buttons -->
<% for pageNumber in [[email protected]]: %>
<% if @document.page.number is pageNumber: %>
<li class="active"><span><%= pageNumber + 1 %></span></li>
<% else: %>
<li><a href="<%= @getPagedUrl(pageNumber) %>"><%= pageNumber + 1 %></a></li>
<% end %>
<% end %>
<!-- Next Page Button -->
<% unless @hasNextPage(): %>
<li class="disabled"><span>Next</span></li>
<% else: %>
<li><a href="<%= @getNextPage() %>">Next</a></li>
<% end %>
</ul>
</div>
Configure
For information on customising your plugin configuration you can refer to the DocPad FAQ
You can customise the URL format by setting custom preferences. The default configuration is:
split: true
prefix: ''
index: 1
compatibility: true
The examples below are with the Clean URLs Plugin installed to remove the file extensions, but each option also works without it. Each option is also compatible with CLean URLs Plugin's static redirection generation.
split
split: true
: The url will be split into multiple parts
For normal documents (e.g. archives.html), the generated url pattern will be:
- /archives/
- /archives/2/
- /archives/3/
- /archives/4/
- etc...
For a document named index.html, the generated url pattern will be:
- /
- /2/
- /3/
- /4/
- etc...
split: false
: The url will be one single part
For normal documents (e.g. archives.html), the generated url pattern will be:
- /archives
- /archives.2/
- /archives.3/
- /archives.4/
- etc...
For a document named index.html, the generated url pattern will be:
- /
- index.2/
- index.3/
- index.4/
- etc...
index
Set index
to set the page number for the index page.
For example, after setting index: 1
, the generated url pattern will be:
- /archives/
- /archives/2/
- /archives/3/
- /archives/4/
- etc...
After setting index: 0
, the generated url pattern will be:
- /archives/
- /archives/1/
- /archives/2/
- /archives/3/
- etc...
prefix
Set prefix
to add a prefix path to the page numbers.
For example, after setting prefix: 'page'
, the generated url pattern will be:
- /archives/
- /archives/page/2/
- /archives/page/3/
- /archives/page/4/
- etc...
compatibility
Set compatibility: true
to maintain backwards compatibility with the older URL structure.
For example, when combined with prefix: 'page'
and index: 1
, the generated url will be:
- /archives/
- /archives/page/2/ (also available at /archives.1/)
- /archives/page/3/ (also available at /archives.2/)
- /archives/page/4/ (also available at /archives.3/)
NOTE: There is one configuration combination in which backwards-compatibility will not be enabled:
split: false
index: [anything other than 0]
prefix: ''
compatibility: true
Setting your configuration to the above will not create the secondary url for each page, to prevent it clashing with the primary url.
Set compatibility: false
to prevent the additional urls being generated.
Combining settings
The settings can be combined to create alternative URL structure. For example, if we configure the plugin with the following options:
split: false
prefix: 'page.'
index: 0
The generated url pattern will be:
- /archives
- /archives.page.1/
- /archives.page.2/
- /archives.page.3/
- etc...
Discover the release history by heading on over to the HISTORY.md file.
Discover how you can contribute by heading on over to the CONTRIBUTING.md file.
These amazing people are maintaining this project:
No sponsors yet! Will you be the first?
These amazing people have contributed code to this project:
Discover how you can contribute by heading on over to the CONTRIBUTING.md file.
Unless stated otherwise all works are:
and licensed under: