Basic concepts

Summary:

Understanding image context and image forms

In general, soo_image tags require “image context”:”#image_context to produce output. Usually this context comes from the “ soo_image_select”:/txp/66/soo_image_select tag, a master controller you use to select images in much the same way you would use Txp’s native article or article_custom tags to select articles. Like those, soo_image_select does not produce any output on its own. Instead, it selects one or more images based on your criteria and sends them to an image form for processing. This is a form of type misc that is called by soo_image_select and that contains one or more soo_image output tags; it’s analogous to an article form.

Alternately, you can use soo_image_select as a container tag. The tag contents take the place of an image form (again, analogous to how article and article_custom can be used either as single tags with a form or as container tags for direct output).

You don’t have to use soo_image_select, though. Without it, a soo_image tag looks for the article image instead. I’ll drop the following tags directly into this article’s body:

<txp:soo_image link="1" /> Photo by <txp:soo_image_author />

Photo by Jeff Soo

So image context comes first from soo_image_select, then from the article image. I’d get the same output by putting those tags into the article form instead.

You can also use the soo_image tag without any context, by specifying an image name or id:

<txp:soo_image id="25" link="1" />

As these examples show, the soo_image tag can be used as a replacement for Txp’s native image, thumbnail, and article_image tags.

All well and good, but the fun begins when we bring in soo_image_select. Above I showed you how an output tag automatically looks for the article image in the absence of other context. This article actually has multiple images assigned to it; its article-image field contains this: 24,25,26,27. Because soo_image output tags only deal with single images, only the first article image was shown in the example above.

soo_image_select deals with any number of images and sends them through a form (or the contents of the soo_image_select tag) for output. The following code:

<txp:soo_image_select />

reveals all this article’s images:

By default, soo_image_select looks to the article-image field, and sends the results to the default image form (for a single image) or list form (for multiple images). My default image list form contains this:

<txp:soo_image onclick="return sooGallery(this)" />

I haven’t loaded the sooGallery() javascript on this page, so here you just see the linked thumbnails (setting onclick automatically enables the thumbnail and link attributes as well). We’ll get to that, and the onclick attribute, a little later.

soo_image_select is not limited to article images. Note the following:

<txp:soo_image_select category="wildflowers" limit="6" />

    <!-- note use of container tag to bypass default image form -->
<txp:soo_image_select id="28,30,29,33,32,31">
<txp:soo_image thumbnail="1" width="60" />
</txp:soo_image_select>

If instead I select a single image, it will go through my default (single) image form, which will show the full-size image, caption and photographer from the Txp database, and selected EXIF data directly from the image file:

<txp:soo_image_select name="20080617SycamoreRoot.jpg" />

Sycamore, Johnston Mill Nature Preserve by Jeff Soo

Camera	Shutter speed	F-stop	ISO speed	Exposure date	Focal length	Crop factor	Computed FOV
PENTAX K10D	3/1	ƒ/9.5	100	17 June 2008	18mm	1.5	77.4°

<div class="soo_image_single">
<div class="box" style='width:<txp:soo_image_width />px'>
<txp:soo_image />
<txp:soo_if_txp_image>
<span class="caption"><txp:soo_image_caption /></span>
<span class="credit">by <txp:soo_image_author /></span>
</txp:soo_if_txp_image>
</div>
<table cellspacing="0"><tbody>
<txp:soo_exif wraptag="tr" break="th" format="{field}" />
<txp:soo_exif wraptag="tr" break="td" format="{value}" />
</tbody></table>
</div>

Summary: image context and image forms

Most soo_image tags require image context to produce output. (The exceptions are soo_image_select, which is a controller rather than an output tag per se, and soo_image if it is used with a specified id or name value. Also, soo_image conditional tags work anywhere, but will always evaluate to false if there is no image context; note that soo_if_image_count uses a more expansive definition of image context.)

Image context is provided by, in descending order of priority:

Inside an image form, the images selected by soo_image_select
- specified name values, or;
- specified id values, or;
- specified category, author, ext (file type), or aspect_ratio values, or;
- article images, or;
Outside an image form
- (first) article image, or;
- (optionally) first image selected by previous soo_image_select tag (persistent context)

Inside an image form, i.e. a form called by soo_image_select (or the contents of a soo_image_select container tag), all of the selected images will be passed, one at a time, to any soo_image tags. Outside an image form, a soo_image tag only sees the first image in the current context. This will be the first article image or, if there is no article image, the first image from the previous soo_image_select tag.

This last element, the first image from the previous soo_image_select tag, is called persistent context. It is optional because it can be disabled either in preferences or in soo_image_select’s attributes. See pagination for a useful example of persistent context.

As of version 1.0.b.8, soo_image_select also looks to the global image context, new in Txp 4.3.0. This applies when the tag is used without selection attributes (id, name, category, etc.) and outside of article context.

Posted 2009-04-28 (last modified 2022-03-12)