soo_page_break

Summary:

Pagination within a single article

Page display and links

soo_article_page is a drop-in replacement for Txp’s body tag. On a normal (single-page) article, its output will be exactly the same as that of body. But on an article containing page breaks, it will display only the page indicated by the pg parameter in the URL query string. Obviously we need a way to generate links to those pages.

The other tags in the suite only function correctly when there is a soo_article_page tag somewhere earlier in the document flow. You can use it in quiet mode to run the initialisation without producing output:

<txp:soo_article_page quiet="1" />

soo_article_page_link

The key is the plugin’s other workhorse tag, soo_article_page_link. There are two ways of telling the tag which page to link to: by page number, and by link relationship. While using page number seems simple, it’s not actually very useful in an article form, because you won’t generally know how many pages an article has. It’s much more useful to use the tag’s rel attribute, like so:

<txp:soo_article_page_link rel="prev" text="{prev} {page}" />

which gives the following:

soo_article_page_link understands four rel values: “first”, “prev”, “next”, and “last”. You can use whatever you like for rel, but if it isn’t one of those four values you must indicate the page number manually in the page_number attribute. rel is “next” by default, but if you unset it (rel=""), the tag will generate an appropriate rel value for you.

Note how the text attribute performed text substitution on the values “{prev}” and “{page}”. It does this using Txp’s built-in gTxt() function, which handles internationalisation. Other values subject to replacement are “{next}” (also by gTxt(), “{pg}”, and “{title}”. For example:

<txp:soo_article_page_link text="{page} {pg}: {title}" />

gives this:

Page 5: Navigation, conditionals, & search

Again, the default value for rel is “next”, so I didn’t have to specify that.

If the link relationship is out of range, e.g. rel="next" when you are on the last page, the tag returns empty, unless you have set showalways="1".

As the examples on this page demonstrate, you can use soo_article_page_link directly in the article body. I don’t really recommend it; it’s generally much more useful to set generalised links in the article form, but you can if you want. Just be careful that the tag doesn’t get the Textile treatment.

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

Page 4 of 6