h1. soo_page_numbers

This is a plugin for "Textpattern":http://textpattern.com. It displays customisable navigation widgets for article list pages.

* "Support forum topic":https://forum.textpattern.io/viewtopic.php?id=31217
* "Author site":http://ipsedixit.net/txp/86/soo_page_numbers
* "GitHub":https://github.com/jsoo/soo_page_numbers

notextile. 


h2. Contents

* "Overview":#overview
* "Tags":#tags
** "soo_page_links":#soo_page_links
** "soo_page_count":#soo_page_count
** "soo_prev_page":#soo_prev_page
* "History":#history

notextile. 

h2(#overview). Overview

Display page navigation widgets and information for article list pages. (Inspired by @rsx_page_number@, an old plugin from Txp's early days.)

Version 0.3.0 includes a Textpack to localize pre-formatted text output such as "Page {current} of {total}". Currently includes 21 languages.

NB: Version 0.4.0 did away with the requirement for an external library plugin, but by moving to native Txp URI handling this changed behavior on sites with custom URI schemes. 0.4.1 restores that behavior. Note that the @p@ (image ID) query parameter is not preserved; this is intentional.

%(warning)Note:% If you have more than one pagination-capable tag on the page (@article@ if not @status="sticky"@, or any of @images@, @file_download_list@, or @linklist@ if both @limit@ and @pageby@ are set) *soo_page_numbers* will take its values from the first such tag. This is true no matter where you put any *soo_page_numbers* tags.

h2(#tags). Tags

h3(#soo_page_links). soo_page_links

Display a "Google-style" page navigation widget, i.e., a group of numbered links representing pages.

pre. 

h4. Attributes

* @placeholder@ _(text)_ %(default)default% @…@
Text to place on either end of the central page range (when there are many pages)
* @window_size@ _(integer)_ %(default)default% @5@
Size of central page range
* @showalways@ _(boolean)_ %(default)default% @0@
Whether or not to show anything when the list is a single page
* @active_class@ _(HTML class)_ %(default)default% @here@
Class for the current page number's tag (the @break@ tag, if any, otherwise @span@)
* @wraptag@ _(text)_ %(default)default% empty
HTML tag name (no brackets) to wrap the output
* @class@ _(text)_ %(default)default% empty
"HTML class name(s)":http://www.w3.org/TR/html401/struct/global.html#adef-class for the @wraptag@.
* @html_id@ _(text)_ %(default)default% empty
"HTML id":http://www.w3.org/TR/html401/struct/global.html#adef-id for the @wraptag@.
* @break@ _(mixed)_ %(default)default% empty
HTML tag name (no brackets) to wrap or text to place between adjacent page numbers. If @wraptag@ and @break@ are set, @break@ is assumed to be a tag name. Otherwise it is treated as text (so don't use @break="br"@).

h3(#soo_page_count). soo_page_count

pre. 

h4. Attributes

* @format@ _(format string)_ %(default)default% @ "{prev} Page {current} of {total} {next}" @
Tag will output this string (in your language, if among the 21 included) after replacing @{prev}@, @{next}@, @{first}@, and @{last}@ with links, and @{current}@ and @{total}@ with page numbers
* @prev@ _(text)_ %(default)default% @«@ («)
Link text for the @{prev}@ link
* @next@ _(text)_ %(default)default% @»@ (»)
Link text for the @{next}@ link
* @first@ _(text)_ %(default)default% @|«@ (|«)
Link text for the @{first}@ link
* @last@ _(text)_ %(default)default% @»|@ (»|)
Link text for the @{last}@ link
* @showalways@ _(boolean)_ %(default)default% @0@
Whether or not to show @{prev}@ and @{next}@ on the first and last pages, respectively, or anything at all when the list is a single page
* @wraptag@ _(XHTML tag name, no brackets)_ optional tag to wrap the output

h3(#soo_prev_page). soo_prev_page, soo_next_page

Shortcuts for @soo_page_count@ when all you want is a single link. For example, @soo_prev_page@ is a shortcut for @@.

h4. Attributes

In addition to @soo_page_count@ attributes, each of these tags also accepts a @text@ attribute for setting the link text. The following tags are equivalent:

pre. 


h2(#history). Version History

h3. 0.4.2 (2020-03-09)

* Fixed longstanding bug that used to be harmless but turned lethal in Txp 4.8.0

h3. 0.4.1 (2017-03-10)

* New URI handling algorithm, reverting to version 0.3 behavior, but as a freestanding plugin

h3. 0.4.0 (2017-03-04)

* Refactored to eliminate the requirement for an external library plugin. (NB: this means, inter alia, that the @p@ (image ID) query parameter is no longer preserved in page links.)

h3. 0.3.2 (2017-02-15)

* Textpattern 4.6 compatibility update

h3. 0.3.1 (2012-01-27)

* @soo_page_count@ (hence also @soo_prev_page@ and @soo_next_page@) now preserve non-Txp query params for "next" and "prev" links.

h3. 0.3.0 (2011-01-18)

* Plugin now includes a Textpack to localize pre-formatted text output such as "Page {current} of {total}". Currently includes 21 languages.

h3. 0.2.7 (2010-02-11)

* Fixed Textpattern notice about non-existent attribute when using @soo_prev_page@ or @soo_next_page@ (functionality not affected)

h3. 0.2.6 (2009-11-23)

* @soo_page_links@ now restores the @'pg'@ query parameter to its initial state, to avoid conflicts with other context-dependent plugins

h3. 0.2.5 (2009-10-21)

* New attributes and shortcut tags for @soo_page_count@

h3. 0.2.4 (2009-07-16)

* Fixed @showalways@ bug when an article list returns 0 pages (e.g. empty category)

h3. 0.2.3 (2009-07-09)

* Improved context check to prevent raw tag output

h3. 0.2.2 (2009-07-09)

* When both @wraptag@ and @break@ are set, non-linked text items (i.e., current page number or placeholder text) are no longer wrapped in @span@ tags, and @active_class@ is applied to the @break@ element containing the current page number.
* Both tags now do a context check and show nothing if the page is not an article list

h3. 0.2.1 (2009-07-07)

* Changed file name and one tag name 
* The @showalways@ attribute of @soo_page_count@ now also affects output when the article list is only one page
* @soo_page_links@ has also been given the @showalways@ attribute
* Scrapped @soo_article_count@, which was inherently buggy (as is the @rsx_to_of@ it was based on)

h3. 0.2 (2009-05-22)

Not publicly released. Code overhaul, fixed to work with any query string

h3. 0.1 (ages ago) 

Not publicly released, not very good either, just a sorry hack of what was probably a quick one-off plugin to begin with (it was early days for Txp).