[plugin] [ORPHAN] etz_pg for paginated articles

Etz Haim · 2005-02-09 21:48:42

Splits articles in pages, assigns names to them, and produces controls for page navigation.

Usage:

Put a newline, a [page] (lowercase; case matters) and then another newline (whitespace also matters!) where you want to insert a page break.
In your article form, put a <txp:etz_pg_body /> where you’d put <txp:body />.
Also in the article from, insert a <txp:etz_pg_pages /> to insert your navigation controls.
Add some style with CSS.

To optionally assign titles to the generated pages, you have to:

Name a custom field etz_pg_subs (lowercase; case matters), via the “Advanced preferences” of Textpattern’s admin interface.
Go to the paginate article’s edit page, and click on “Advanced options”.
In the etz_pg_subs custom field, for an article with, let’s say, four pages, write “This is page one|This is page two|This is page three|And last but not least, page four”. The names of the pages are separated with vertical bars. Note that the number of the vertical bars must be equal to the number of the [page] separators in the body article.

Available tags:

This version of the plugin comes fully loaded with everything you need to add a new level of structure and navigation to your TXP site!

Fundamental:

<txp:etz_pg_body /> replaces <txp:body />. Available attributes are:
- pgerr specifies a custom “Invalid page number” message. This is also useful to define a message in a language other than English.
- notrim if set to non-zero disables the XHTML validation hack. You shouldn’t have to use this under normal circumstances.

Navigation:

<txp:etz_pg_pages /> inserts the plugin’s standard navigation controls. These can be a list of page names, provided that you have assigned page names manually (read above), or simply a list of page numbers by default. Available attributes are:
- always will create navigation controls even if the article isn’t paginated
- start, prev, next, end which define the text for the respective navigation links.
- noextremes if set to non-zero disables start and end links.
- noadjacents if set to non-zero disables prev and next links.
- nonumbers if set to non-zero disables navigation by page numbers, or by page names, provided that you have assigned page names manually (read above).
- usenumbers if set to non-zero will use only page numbers for navigation, even if you have assigned page names manually (read above). This is always overriden by the one above.
- id sets the name of the <ul> id HTML attribute (default: pages).
<txp:etz_pg_switchmode /> inserts a smart link that enables you to switch from split view to whole article view, and vice versa. Available attributes are:
- id sets the name of the <ul> id HTML attribute (default: switchmode).
- all sets the text for the link to the whole article view mode (default: “all pages”). This is also useful to define a message in a language other than English.
- split sets the text for the link to the split article view mode (default: “split in pages”). This is also useful to define a message in a language other than English.
<txp:etz_pg_custom /> provides a custom navigation component, which is especially useful if page names have been assigned. It a custom text message e.g. containing the title of the page, optionally linking to page. Available attributes are:
- text, which defines the output text. Defaults to the template variable %t (lowercase; case matters), which corresponds to the title of the referenced page. Another template variable available is %n, which corresponds to the referenced page’s number.
- mode, which can either be optionally rel (“relative”) or abs (“absolute”, default). abs means that the page attribute refers to the absolute page number; a negative number, e.g. -1 will denote the last page of the article, -2 before-last etc. rel, on the contrary, denotes that page is an offset (either positive or negative) from the current page.
- page, as implied by the above, is an integer (default: 0).
- link if set to non-zero enables a link to the referenced page.
- title defines the text in the HTML “title” variable for the link. Just like the text attribute described above, it defaults to %t, accepting the exact same syntax.

Conditionals:

<txp:etz_pg_if_split> and <txp:etz_pg_if_not_split> are conditionals to tell whether the article is currently displayed in the split mode, or not.
<txp:etz_pg_if_paginated> and <txp:etz_pg_if_not_paginated> are conditionals to tell whether the article has a split mode, or not.
<txp:etz_pg_if_start> and <txp:etz_pg_if_not_start> are conditionals to tell whether the start of the article is currently displayed, or not.
<txp:etz_pg_if_end> and <txp:etz_pg_if_not_end> are conditionals to tell whether the end of the article is currently displayed, or not.
<txp:etz_pg_if_titles> and <txp:etz_pg_if_not_titles> are conditionals to tell whether page titles have been assigned, or not.

Other:

<txp:etz_pg_current /> returns the current page’s number in split mode, or “all pages” if all pages are displayed.
- all can set another message to replace the default “all pages”. This is also useful to define a message in a language other than English.
<txp:etz_pg_totalpages /> returns the total pages number.

Requirements:

The latest stable version of Textpattern. (It will probably work with the latest SVN version as well.)
PHP version 5 or above.

Known problems:

Relies on an ugly hack in order not to break XHTML validation.
[page] separators get indexed in search (workaround).

History:

Once a fork of DarkWulf’s hfw_pg_* plugin, this plugin is almost a complete rewrite of its predecessor. Notable enhancements are:

Works in any site structure
Outputs a standard set of navigation controls as an unordered list, suitable for styling.
Configurable links for start, previous, next and end.
Provides a smart link that enables you to switch from split view to whole article view, and vice versa.
Additional custom navigation elements.
A lot of conditionals add logic to your article forms.
On clean URL mode, produces canonical URLs.
Works with the latest TXP.
No more of the stupid ?pg=1 url suffix.
Supports page titles, as of version 0.8.
Produces valid XHTML.

License

The plugin’s documentation is licensed under the GNU Free Documentation License.
The plugin itself is licensed under the GNU General Public License.

Demo
Download version 0.10.2 now!

This software is both free as in beer and free as in freedom. If you like it or think it’s useful, you may consider bying me something from my wishlist.

Last edited by Etz Haim (2007-10-23 18:38:58)

andreas · 2005-02-09 22:03:53

Great, thanks a lot!

Rufnex · 2005-02-10 08:42:00

Great work, thx! I’ve a suggestion about the navigation. if we use a attribut for the [page] tag, e.g.

[page title=“My first paragraph”]

then in the navigatiion block we could use the titel tags as arrangement if you like (done by another parameter) .. jut an idea ;o)

Etz Haim · 2005-02-10 12:04:49

Released updated version 0.3 of the plugin. This is mainly a code cleanup release.

Changelog:

Defined <txp:etz_pg_thispage /> and <txp:etz_pg_totalpages />.
pgerr attribute of <txp:etz_pg_body /> enables to specify a custom “Invalid page number” error message.
notrim attribute of <txp:etz_pg_pages /> if set to non-zero disables the XHTML validation hack. Use this one with caution.
More advanced logic avoids redundant string manipulations and (theoretically) saves processor time.
current class defined for the current page’s <li>.
Cleaner code, of course.

NOTE: To update to this version, you have to update your CSS stylesheet(s) to use the current <li> class.

Last edited by Etz Haim (2005-02-11 09:10:11)

andreas · 2005-02-10 21:15:57

I can’t seem to open your archive file. Get the error message “Can’t read from this file”.

Could you perhaps post a plain text file? Thanks.

Your updates sound excellent, looking forward to trying it out.

Etz Haim · 2005-02-10 21:36:48

Download and install a file archiver that supports the GZip format. If your platform is win32, I suggest 7-zip.

andreas · 2005-02-11 05:58:46

I use PwerArchiver which supports GZip as well but for some reason it wasn’t able to extract your file. 7zip worked, though. Thanks.

Etz Haim · 2005-02-17 22:48:17

Released updated version 0.5 introducing new feature:

<txp:etz_pg_switchmode /> and the ability to display whole article in a single view.
<txp:etz_pg_if_split> and <txp:etz_pg_if_not_split> are who new conditionals, and are part of the new API where <txp:etz_pg_if_paginated> and <txp:etz_pg_if_not_paginated> assume a slightly different role (RTFM).

How to upgrade from version 0.3:

You have to update your CSS stylesheet(s) to the new class and id names defined by the plugin.
If you use the <txp:etz_pg_if_paginated> and <txp:etz_pg_if_not_paginated> conditionals in your article form(s) you may have to change them to <txp:etz_pg_if_split> and <txp:etz_pg_if_not_split>, depending and what you need them for.

Etz Haim · 2005-02-18 00:15:24

A possible workaround for a known bug: If you have an english language website and you don’t what [page] separators to get indexed in your searches, consider editing the plugin code and replacing [page] in the etz_pg_break() function with something impossible to be included in a search, eg. [2adf5211] (part of an MD5 digest actually). Then, change all your articles accordingly. Make sure your replacement does not have any meaningful substrings.

kartav · 2005-03-09 19:05:17

I have a question:
is it possible to insert some ‘page’ tags in article and after that somehow to get whole page on single page? It would be useful to have some link like “To get whole article”, e.g. for printing or saving…

andreas · 2005-03-09 19:20:22

<blockquote>is it possible to insert some ‘page’ tags in article and after that somehow to get whole page on single page? It would be useful to have some link like “To get whole article

Last edited by andreas (2005-03-09 19:20:54)

kartav · 2005-03-10 05:42:34

andreas,

Thanks a lot.

Textpattern CMS

Textpattern CMS support forum

#1 2005-02-09 21:48:42