soo_image user guide Page 4 of 16

Pagination

Summary:

Navigation links for large galleries

For large image sets soo_image provides pagination controls. For example (formatting div elements not shown):

<txp:soo_image_prev link_text="&uarr;" class="prev" />
<txp:soo_image_select aspect_ratio="2-1" ext="jpg" limit="3" sort="date desc" />
<txp:soo_image_next class="next">&darr;</txp:soo_image_next>
<txp:soo_image html_id="sooGalleryMain" />
<p id="sooGalleryCaption"><txp:soo_image_caption /></p>

Claytonia, aka Spring Beauty

Note that the paging tags, soo_image_prev and soo_image_next, can be used either as single tags or containers. As single tags they output link_text as the link text; as containers link_text is overridden by the tag contents. soo_image_prev has a default link_text of &larr; (←) and soo_image_next has a default link_text of &rarr; (→).

New in version 1.0.b.2, soo_image_page_count displays information about the current page and total number of pages in the gallery. For example:

<txp:soo_image_page_count format="Page {current} of {total}" />

Page 1 of 5

Also note the attributes used in the soo_image_select tag. aspect_ratio doesn’t format the image; it searches for images with the specified aspect ratio. In this case the search is for images with an aspect ratio between 2 and 1. The ext attribute accepts a comma-separated list of file types. author does the same vis-à-vis image author, as does category for category. When these attributes are used in combination, the result is an AND (conjunctive) search, i.e., each successive attribute narrows the search. So this gallery shows only jpg images within the specified range of aspect ratios.

The paging tags are intended to be used where you have only one gallery per URL. It could work with multiple galleries, but unless each gallery has the same number of pages you will get some anomalies.

You probably don’t want to combine pagination and random sorting, because each page request will generate a new random sequence.

As of version 1.0.b.1, both pagination tags can be placed anywhere on the page, even before the associated soo_image_select tag.

Aside: persistent context

The code example above includes a soo_image tag making use of persistent context. That is, the tag doesn’t have id or name set, it is not in an image form (or soo_image_select container tag), and this article doesn’t have any article images assigned. So on initial page load the soo_image tag picks up the first image selected by the previous soo_image_select tag (or, if the page was accessed via the link to gallery feature, the linked image). Without persistent context this gallery would require a second soo_image_select tag for the full-size image, and the link_to feature wouldn’t work correctly.

But if you don’t want this behavior there are two ways to disable it: in the plugin’s preferences, or by putting persistent_context="0" in the soo_image_select tag. You might prefer this for a complex page combining galleries and article lists with article images, to prevent unwanted images appearing for articles without an assigned image (although there are other ways to work around this issue).

See image context for more details about persistent context.

Posted 2009-04-29 (last modified 2010-07-02)