Pagination within a single article

  1. Background
  2. Page breaks & titles
  3. Page display and links
  4. Navigation, conditionals, & search
  5. Full plugin help text


In Textpattern (hereafter Txp) an article is a single page. Period, definitively, no ifs, ands, or buts. Txp offers lots of useful ways of listing and cross-linking those articles, but only as distinct single-page documents. There’s no built-in way to create a unified multiple-page document and have it behave as such all across Txp. That’s as true on the admin side as it is on the public side.

Txp is of course easy to customise through its excellent plugin system. I’m sure there are other content management systems with native support for multi-page documents, but as a Txp user since its initial release my first instinct is to find a way to bend it to my needs than to seek out and learn a new system. That is, if not too much bending is required.

A bridge too far

Not that I am categorically opposed to heavy mods. Multidoc, my previous attempt to address this problem, stretches Txp pretty far. It allows you to construct documents with any number of pages and any level of structural depth, and on the public side it is mostly transparent. The admin side is a bit of a mess, though, especially in that the pages of a Multidoc document can end up scattered all through the default Txp article admin panel. This could be polished up, but would involve a lot more work than I intend to put into it at this point. For a plugin, it is a massive piece of code, making little use of core Txp classes and functions. As useful as I think Multidoc is (and I still use it), I have to admit that fundamentally it works over and against Txp rather than with it, and I am no longer interested in that approach.

A new approach

Multidoc came about the way it did because I started with a quite specific goal—enable complex document structure in Txp—and then relentlessly pounded this square peg into the round hole that is Txp. My new plugin, soo_page_break (which powers this document) was the outcome of a different thought process.

Instead of an ambitious and detailed goal, I started with a modest and general goal: achieve some kind of article pagination, however simple. Then, instead of letting that goal drive development, I set parallel goals of relying on Txp native code wherever possible, while making the plugin behave as unobtrusively as possible. This was not just to keep the code small and easy to maintain, but more importantly to make the plugin feel like a natural and modest extension of core Txp behaviour. The resulting process was a back and forth between both ends of the problem: on the Txp side, consider not just what can be done, but what can be done elegantly. On the plugin side, have a flexible concept and let it evolve along with the code.

Plugin or core feature?

Having recently peered behind the Txp curtain after a few years of neglect, I was delighted to discover a still-active project, one moving in a very positive direction. The simple expedient of moving the project to GitHub has made development much more transparent and easy to contribute to. Scanning the issues queue I noticed an old plea for paged articles, and this got me thinking about how this might work as a core feature vs. a plugin.

And I think this really is doable as a core feature. But I decided to start with a plugin anyway. It’s a proof-of-concept for a new feature, but if that doesn’t make the grade it will remain available as a plugin. And in general it’s much easier to work out ideas in a plugin. Changes to core should not be made lightly, and a lot of careful consideration goes into details of where things go and how they work, even what they’re named.

Posted 2017-03-09 (last modified 2017-03-10)

Page 1 of 6