Refactoring options API and documentation

* Enable `noPageOne` configuration (Refs: #5)
* Enable `groupBy` configuration (Refs: #6)
* Enable `pageContents` configuration (Refs: #7)

Together, these options allow disabling page one rendering, grouping by custom logic (E.g. not pagination, but other file information - author, year, id, etc.) and setting default page contents (overriding the empty buffer default).

Author: blakeembrey

.gitignore

@@ -1,3 +1,4 @@
 coverage
 node_modules
 .DS_Store
+npm-debug.log

README.md

@@ -72,6 +72,9 @@ metalsmith.use(pagination({
 * **path** The path to render every page under.
 * **filter** A string or function used to filter files in pagination.
 * **pageMetadata** The metadata to merge with every page.
+* **noPageOne** Set to true to disable rendering of page one, useful in conjunction with first (default: `false`).
+* **pageContents** Set the contents of generated pages (default: `new Buffer('')`). Useful for [metalsmith-in-place](https://npmjs.org/package/metalsmith-in-place) (especially with `pageMetadata`).
+* **groupBy** Set the grouping algorithm manually (default: paginated by `perPage`). Useful for paginating by other factors, like year published (E.g. `date.getFullYear()`).
 
 ### Page Metadata
 
@@ -82,6 +85,7 @@ The `pageMetadata` option is optional. The object passed as `pageMetadata` is me
 Within the template you specified, you will have access to pagination specific helpers:
 
 * **pagination.num** The current page number.
+* **pagination.name** The page name from `groupBy`. It will be the page number string with the default `groupBy`.
 * **pagination.files** All the files for the current page (E.g. an array of `x` articles).
 * **pagination.pages** Links to every page in the collection (E.g. used to render pagination numbers).
 * **pagination.next** The immediately following page, if it exists.

metalsmith-pagination.js

@@ -1,23 +1,25 @@
 var toFn = require('to-function')
-var extend = require('extend')
+var extend = require('xtend')
 
 /**
  * Page collection defaults.
  *
  * @type {Object}
  */
 var DEFAULTS = {
-  perPage: 10
+  perPage: 10,
+  noPageOne: false,
+  pageContents: new Buffer('')
 }
 
 /**
  * Paginate based on the collection.
  *
- * @param  {Object}   opts
+ * @param  {Object}   options
  * @return {Function}
  */
-module.exports = function (opts) {
-  var keys = Object.keys(opts)
+module.exports = function (options) {
+  var keys = Object.keys(options)
 
   return function (files, metalsmith, done) {
     var metadata = metalsmith.metadata()
@@ -26,94 +28,114 @@ module.exports = function (opts) {
     var complete = keys.every(function (name) {
       var collection
 
+      // Catch nested collection reference errors.
       try {
         collection = toFn(name)(metadata)
-      } catch (e) {
-        done(e)
+      } catch (error) {}
 
-        return false
-      }
-
-      // Throw an error if the collection does not exist.
       if (!collection) {
-        done(new TypeError('Collection "' + name + '" does not exist'))
+        done(new TypeError('Collection not found (' + name + ')'))
 
         return false
       }
 
-      var pageOpts = extend({}, DEFAULTS, opts[name])
+      var pageOptions = extend(DEFAULTS, options[name])
       var toShow = collection
+      var groupBy = toFn(pageOptions.groupBy || groupByPagination)
 
-      if (typeof pageOpts.filter === 'function') {
-        toShow = collection.filter(pageOpts.filter)
-      } else if (pageOpts.filter) {
-        toShow = collection.filter(toFn(pageOpts.filter))
+      if (pageOptions.filter) {
+        toShow = collection.filter(toFn(pageOptions.filter))
       }
 
-      var perPage = pageOpts.perPage
-      var pages = collection.pages = []
-      var numPages = Math.ceil(toShow.length / perPage)
+      if (!pageOptions.template && !pageOptions.layout) {
+        done(new TypeError('A template or layout is required (' + name + ')'))
+
+        return false
+      }
 
-      if (!pageOpts.template && !pageOpts.layout) {
-        done(new TypeError('Specify a template or layout for "' + name + '" pages'))
+      if (pageOptions.template && pageOptions.layout) {
+        done(new TypeError(
+          'Template and layout can not be used simultaneosly (' + name + ')'
+        ))
 
         return false
       }
 
-      if (pageOpts.template && pageOpts.layout) {
-        done(new TypeError('You should not specify template and layout for "' +
-          name + '" pages simultaneosly'))
+      if (!pageOptions.path) {
+        done(new TypeError('The path is required (' + name + ')'))
 
         return false
       }
 
-      if (!pageOpts.path) {
-        done(new TypeError('Specify a path for "' + name + '" pages'))
+      // Can't specify both
+      if (pageOptions.noPageOne && !pageOptions.first) {
+        done(new TypeError(
+          'When `noPageOne` is enabled, a first page must be set (' + name + ')'
+        ))
 
         return false
       }
 
-      // Iterate over every page and generate a pages array.
-      for (var i = 0; i < numPages; i++) {
-        var pageFiles = toShow.slice(i * perPage, (i + 1) * perPage)
+      // Put a `pages` property on the original collection.
+      var pages = collection.pages = []
+      var pageMap = {}
+
+      // Sort pages into "categories".
+      toShow.forEach(function (file, index) {
+        var name = groupBy(file, index, pageOptions).toString()
+
+        // Keep pages in the order they are returned. E.g. Allows sorting
+        // by published year to work.
+        if (!pageMap.hasOwnProperty(name)) {
+          // Use the index to calculate pagination, page numbers, etc.
+          var length = pages.length
+
+          var pagination = {
+            name: name,
+            num: length + 1,
+            pages: pages,
+            files: []
+          }
+
+          // Generate the page data.
+          var page = extend(pageOptions.pageMetadata, {
+            template: pageOptions.template,
+            layout: pageOptions.layout,
+            contents: pageOptions.pageContents,
+            path: interpolate(pageOptions.path, pagination),
+            pagination: pagination
+          })
 
-        // Create the pagination object for the current page.
-        var pagination = {
-          num: i + 1,
-          pages: pages,
-          files: extend(pageFiles, { metadata: collection.metadata })
-        }
+          // Copy collection metadata onto every page "collection".
+          pagination.files.metadata = collection.metadata
 
-        // Generate a new file based on the filename with correct metadata.
-        var page = extend({}, pageOpts.pageMetadata, {
-          template: pageOpts.template,
-          layout: pageOpts.layout,
-          contents: new Buffer(''),
-          path: interpolate(pageOpts.path, pagination),
-          pagination: pagination
-        })
-
-        // Create the file.
-        files[page.path] = page
-
-        // Update next/prev references.
-        if (i > 0) {
-          page.pagination.previous = pages[i - 1]
-          pages[i - 1].pagination.next = page
-        }
+          if (length === 0) {
+            if (!pageOptions.noPageOne) {
+              files[page.path] = page
+            }
 
-        // When the first page option is set, render it over the top of the
-        // canonically generated page.
-        if (i === 0 && pageOpts.first) {
-          page = extend({}, page, {
-            path: interpolate(pageOpts.first, page.pagination)
-          })
+            if (pageOptions.first) {
+              // Extend the "first page" over the top of "page one".
+              page = extend(page, {
+                path: interpolate(pageOptions.first, page.pagination)
+              })
+
+              files[page.path] = page
+            }
+          } else {
+            files[page.path] = page
 
-          files[page.path] = page
+            page.pagination.previous = pages[length - 1]
+            pages[length - 1].pagination.next = page
+          }
+
+          pages.push(page)
+          pageMap[name] = pagination
         }
 
-        pages.push(page)
-      }
+        // Files are kept sorted within their own category.
+        pageMap[name].files.push(file)
+      })
 
       return true
     })
@@ -126,9 +148,23 @@ module.exports = function (opts) {
  * Interpolate the page path with pagination variables.
  *
  * @param  {String} path
- * @param  {Object} opts
+ * @param  {Object} data
  * @return {String}
  */
-function interpolate (path, opts) {
-  return path.replace(/:num/g, opts.num)
+function interpolate (path, data) {
+  return path.replace(/:(\w+)/g, function (match, param) {
+    return data[param]
+  })
+}
+
+/**
+ * Group by pagination by default.
+ *
+ * @param  {Object} file
+ * @param  {number} index
+ * @param  {Object} options
+ * @return {number}
+ */
+function groupByPagination (file, index, options) {
+  return Math.ceil((index + 1) / options.perPage)
 }

package.json

@@ -36,7 +36,7 @@
     "standard": "^2.11.0"
   },
   "dependencies": {
-    "extend": "^2.0.0",
-    "to-function": "^2.0.5"
+    "to-function": "^2.0.5",
+    "xtend": "^4.0.0"
   }
 }