smd_pagicle

Automatically split long articles into bite-size hunks which visitors can navigate between using the handy pager. The whole article is loaded in one go; the various pages are simply switched into view via jQuery.

Features

• Choose where you split the page; either via some fixed code your authors can enter at chosen break points, or at particular elements on the page (e.g. at each <h2>)
• Choose the jQuery animation effect you wish to apply between pages
• Auto-focus (scroll) back to the top of the document at the start of each virtual page
• Make header and footer elements (which are usually only shown on the top/bottom of the article, respectively) appear on every virtual page

Author / credits

Stef Dawson.

Installation / Uninstallation

Download the plugin from either textpattern.org, or the software page, paste the code into the TXP Admin -> Plugins pane, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To uninstall, simply delete from the Admin -> Plugins page.

Usage

Somewhere on an individual article Page put a call to <txp:smd_pagicle />. Configure the plugin using the following attributes; items with a border round them are mandatory, although the defaults usually suffice:

• container : ID of the DOM wrapper element that holds your article content. Default: #content
• splitat : what you would like to search for in your article. Each time the plugin finds one of these items, a new page will begin. It can either be some text that you embed within your article body (e.g. {PageHere}) or some other content that might appear inside an HTML tag pair. Note that if this is used in tandem with splitwraptag then you should either specify the entire content inside the tag OR use regular expression notation to match part of it. See examples 3 and 4 for more. Default: unset¹
• splitwraptag : an (X)HTML tag without brackets to search for. Can work together with splitat or on its own to search for any particular set of elements inside your container. Default: h2¹
• delete : whether you wish to remove the element at which you chose to splitat / splitwraptag. The default is automatic: for splitat (used on its own) it is set to 1, and for splitwraptag it is set to 0 to preserve the tag and its contents
• header : a reference to the DOM element that contains your article title. This is so it can be repeated at the top of each virtual page. Default: h1
• footer : a reference to the DOM element that contains your article footer. Normally this would contain the article comments, or some related articles that would only be displayed at the very end of the article. If you wish to copy the footer content into the bottom of every virtual page, specify its DOM reference here. Default: unset
• animate : list of jQuery name:value pairs to pass to the animate() function. Each time you click a page number, this animation effect is played. Default: opacity:show²
• focus : a DOM element reference to scroll back to, whenever a page number is clicked from the nav. Can take an optional scroll speed in milliseconds by specifying the speed value after a colon. Default: body:400
• addnavto : DOM element to which to add the page numbers navigation widget. The element you name here — it may be a single element ID or a class so you can add the widget to more than one element — must already be included on your page. Default: #smd_pagnav²
• navclass : class to apply to the navigation container. Default: smd_pages²
• navactive : class to indicate the currently selected page. Default: smd_currpage²
• navdisabled : during the course of navigating pages, the next/prev links are sometimes not required. Since it is not possibe in HTML to ‘disable’ an anchor, this class is applied to the arrows so you may choose to style them differently. Default: smd_disabled²
• navdisplay : which navigation elements to show. Default: f p # n l a Choose from:
  • f: first page («)
  • p: previous page (<)
  • #: the page numbers
  • n: next page (>)
  • l: last page (»)
  • a: show entire document, i.e. turn off paging (All)
• navtext : list of text values to use for each of the chosen items in navdisplay. Specify the item code (f, p, n, l or a) followed by a colon and then the text you want to appear in the nav, e.g. navtext="f:First, l:Last". Any items you do not specify will use the defaults as listed above

¹ at least one of either split or splitwraptag are required.

² if any of these attributes are unset (="") in the tag, they will be reset to their defaults again.

Examples

Example 1

<div id="smd_pagnav"></div>
<txp:smd_pagicle container="#pagemain"
     footer="#navlocal" />

This example will:

• split the document at <h2> tags inside the pagemain container div
• add the page navigation to the smd_pagnav div
• copy the #navlocal element to the bottom of each page

Example 2

<div class="smd_pagination"></div>
<txp:article />
<div class="smd_pagination"></div>
<txp:smd_pagicle container="#pagemain"
     splitat="{newpage}" splitwraptag=""
     addnavto=".smd_pagination" />

This example:

• starts a new page every time the body has the phrase {newpage} in it
• adds the nav above and below the article by using a class name (note the . in .smd_pagination to indicate it is a class not an ID we are referring to)

Also note that splitwraptag has been unset.

Example 3

<div id="smd_pagnav"></div>
<txp:smd_pagicle container="#wrapper"
     splitat="Commentary" splitwraptag="h3"
     focus="h1:1000" />

This example will:

• Only split the document wherever it finds <h3>Commentary</h3> inside the wrapper div
• Scroll up to the <h1> tag and take one second (1000 milliseconds) to do so each time a page number is clicked

Example 4

<div id="smd_pagnav"></div>
<txp:smd_pagicle container="#wrapper"
     splitat=".*red.*" splitwraptag="h3" />

This example will split the document wherever it finds an <h3> tag that has the characters red inside them. The .* is a regular expression wildcard that matches any characters before and after ‘red’.

For example, <h3>Blinkered vision</h3> and <h3>Drederick Tatum</h3> will match, but <h3>Here doggy</h3> will not.

Example 5

<div id="smd_pagnav"></div>
<txp:smd_pagicle container="#wrapper"
     navtext=""f:##first##, l:##last## />

This example:

• Splits the article at <h2> tags
• Adds the navigation to the smd_pagnav div
• Uses MLP snippets to render language-dependent entries for the ‘f’ and ‘l’ nav items

Changelog

• 23 Jun 09 | 0.1 | Initial release
• 24 Jun 09 | 0.2 | Refactored code and removed most of the wrap attributes ; fixed validation issues and visibility of pager in non-paged articles, added ‘all’ and allowed MLP snippet replacement (all thanks ultramega)