soo_page_break: Pagination within an article

jsoo · 2017-03-10 02:53:20

If a mod would kindly add me back to the list of plugin authors and ferry this thread over to its proper home, I would raise a glass in your honour

Scanning the issues list I noticed this old request for multi-page articles. Hey, says me, that sounds right up my alley. Would be a nice project for easing back into Txp. Figured a plugin would be the way to go, whether as a proof-of-concept for a possible core mod or as an ongoing plugin project. And so I bring you:

soo_page_break

This is a suite of tags for handling articles with body text marked up according to a couple of very simple rules: indicate page breaks with “[break]” (or another delimiter of your choice), and somewhere after the break put a heading element (h1, h2, etc.) containing the title for that page.

Unlike some of my past efforts, this is a standalone plugin with no special requirements and no extensions or modifications to the admin side. Meant to be simple, and as Txp-ish as I could make it. Enjoy.

Full details here: http://ipsedixit.net/txp/157/soo_page_break

colak · 2017-03-10 06:37:27

jsoo wrote #304526:

If a mod would kindly add me back to the list of plugin authors and ferry this thread over to its proper home, I would raise a glass in your honour

done:)

Bloke · 2017-03-10 10:51:34

Oh this is just mint, Jeff. It feels so natural. Way better than my failed attempt at doing it in JavaScript years ago (smd_pagicle).

Love that you reuse the pg variable in a backwards-compatible manner. I’d be more than happy to see something of this ilk in core. It’s about time the <txp:body> tag got a couple of attributes, and I think delimiter is wholly appropriate.

The [break] syntax is great for Textiled documents, because you don’t have to worry about escaping it. My immediate thought was that a tag would be a nice addition, but then having to escape it or put a few spaces before the tag to shut Textile up makes it less attractive, so I can see why you went with something different, and that it can be overridden. Sweet.

I can’t speak for the other devs, but if there’s some way to factor this idea into core, I’m all for it. Adding a few attributes to <txp:article> to supoprt pagination, plus the aforementioned <body> attribute(s), an additional attribute or two for <txp:title> to permit pagination support(?) along with a new tag to output page info and ToCs, this could be a winner. Remember our discussion way back about pagination? Might be something of relevance there to steal too, but I can’t recall now if it was a satisfactory solution to beef up pagination all round.

Maybe Oleg can chime in, especially with new tags like <txp:evaluate>, the change to <txp:hide> to allow pre-parsing of content, and the parser changes in 4.7.0, this might be something that can be rolled in natively with minimal new tags and make it feel like it’s always been there.

My only slight reservation is the {syntax} which I have been lambasted for using in the past out of security concerns. Personally, I like it as it’s nice and readable; way more than a tag would be. But the fact such syntax just uses str_replace() or (in my case) strtr() means that it bypasses the tag parser and (I’ve been told, but have yet to see demonstrated) may be used to inject content into the page that later gets evaluated. Maybe your _soo_article_page_replace() function is safe — I don’t know without trying to break it — in which case, yay!

My approach in the past has been to employ a tag that takes a list of ‘items’ to output and has wraptag / break atts so you can output more than one of them. So, your example:

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

would become:

<txp:soo_article_page_link rel="prev" item="prev, page" break=" " />

However, that approach isn’t very flexible if you want to use more than one delimiter for complex layouts, and it breaks the <txp:soo_article_page_nav> tag, because it already uses wraptag and break for the pagination delimiters. Using tag-in-att seems like a horrible way to go:

<txp:soo_article_page_link rel="prev" item='<txp:soo_nav_item item="prev, page" break=" " />' />

Safe, but yuk!

So I don’t know. If this hurdle can be overcome, or we can introduce a safe replacement syntax in core (or can otherwise prove the replacement approach is secure), then I’m all for this becoming a core feature.

Monumentally awesome work, sir.

Last edited by Bloke (2017-03-10 10:53:32)

jsoo · 2017-03-10 14:09:57

Cheers Stef!

Re [break] vs. a tag as the delimiter, actually I started with a tag. It was only after writing up usage examples, with all the many caveats regarding Textile, that I realized that [break] was the way to go. Non-techie users will much prefer that anyway. I could see adding some kind of js widget to add page breaks automatically, but right now that feels like a needless flourish to me.

An idea that just occurred to me is to have Textile handle this in some way, e.g. replacing [break] with <txp:page_break />. I haven’t kept up with Textile development; does it have a plugin architecture so that we could add this without hacking? This would keep the [break] delimiters out of the body in single-page mode. (I didn’t add a single-page mode, because all you need is body for that.)

Re core vs. plugin, I shied away from attempting a core mod not just because a plugin would be a better sketchpad for a proof-of-concept demo, but also because I have no idea where things currently stand with core preText and article processing, and have this nagging suspicion that the latter at least is due for a complete rethink. So I haven’t given a lot of thought as to how to approach this as a core mod. Let’s see what other response this plugin gets.

I was a little hesitant as to {page} syntax in attributes, and I wasn’t even aware of the security concerns. Which, I must admit, I haven’t a clue about. Bypasses the tag parser? By avoiding the second parse pass?

etc · 2017-03-10 14:16:01

I love Jeff’s renewed txp activity, yay, the plugin looks great! Few years ago I’ve posted another article pagination solution using etc_query. But, if we want to have it in core, the pagination “on the fly” does not seem optimal, especially for really long articles. Any chances of doing it on article save, maybe? Then should body be split and stored in another table? It looks like the unlimited custom fields era could make it easier.

Bloke · 2017-03-10 14:29:38

jsoo wrote #304546:

I haven’t kept up with Textile development; does it have a plugin architecture so that we could add this without hacking?

Not as far as I’m aware. It’s on Steve’s ToDo list, and I’m sure he would love to have someone build such a system if you’re ever at a loose end :-)

I wasn’t even aware of the [{page} syntax] security concerns… Bypasses the tag parser? By avoiding the second parse pass?

I don’t know exactly. As I say, I’ve never seen a vulnerability demonstrated in the wild, but I remember Jukka saying on occasion that it might be possible to construct some malicious experience if there was a ever a parser bug discovered (or something: it was over my head). But I trust his judgement, since he knows far more about security than I do.

jsoo · 2017-03-10 14:30:05

[Edit: replying to etc]

Good questions. Not just for performance, but also usability: it is not optimal to edit a long article in a single textarea. So I was thinking the same thing. It’s part of what I was hinting at above, suggesting that doArticle and the whole article model is due for a rethink. Is that on the table? Sounds scary.

Last edited by jsoo (2017-03-10 14:30:36)

jpdupont · 2017-03-16 15:58:18

Hello Jeff !
I plan to use the plugin on a new site. Is it possible to install it for all articles (replace <txp:body/> all over), and give the redactor the possibility to use the [breack page] or not ? No side/performance effect if he use it on a very little number of articles ?

jsoo · 2017-03-16 16:14:31

Hi Jean-Pol:

<txp:soo_article_page /> can be safely used in place of <txp:body />, whether or not the body contains a page break. If there is no break, the tag simply returns the entire body text.

The tag does a regular-expression split on the body of the current article, and this will certainly have a performance cost, although in most cases that cost should be negligible. The worst-case example I can think of would be an article list page with an unusually large number of articles, many of which have a large body text, and for which you are using soo_article_page. However, you’re not likely to need the tag for an article list, other than search results (to get the link to the correct page of the article).

Hope that helps!

jpdupont · 2017-03-16 16:32:31

Thanks Jeff …
Are the nav tags ignored, if no [page break] ?

jsoo · 2017-03-16 16:36:05

That’s correct, except for soo_article_page_link when you have specified showalways="1".

Textpattern CMS

Textpattern CMS support forum

#1 2017-03-10 02:53:20