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="↑" class="prev" /> <txp:soo_image_select aspect_ratio="2-1" ext="jpg" limit="3" sort="date desc" /> <txp:soo_image_next class="next">↓</txp:soo_image_next> <txp:soo_image html_id="sooGalleryMain" /> <p id="sooGalleryCaption"><txp:soo_image_caption /></p>
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 ←
(←) and soo_image_next
has a default link_text
of →
(→).
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)