soo_image user guide Page 9 of 16


Select images for display via other soo_image tags. Select specific images by name or id; search for images by author, category, aspect ratio, or file type, retrieve article image(s), or select images from Txp 4.3.0’s new image context. Each selected image will be passed to the image form or container contents.

Can be used almost anywhere, but do not use recursively, i.e. inside another soo_image image form or soo_image_select container tag. In general you must place soo_image_select above any other soo_image tags if soo_image_select is expected to provide the image context for the other tags. (soo_image pagination tags are an exception, and can be placed anywhere.)

Use as a single tag (in which case the form attribute is required)

<txp:soo_image_select />

or as a container (in which case form and listform will be overridden)

... *soo_image* tags and other content


Unless otherwise stated, all attributes default to unset (“0” or empty).

Note that name will override id, and either of these will override author, category, aspect_ratio, and ext. If none of these is declared, inside an article form soo_image_select looks for the article image(s) (and so requires an article context). And if neither applies, soo_image_select checks for global image context (new in Txp 4.3.0).

author, category, aspect_ratio, and ext can be used together for a complex selection. Each attribute accepts a comma-separated list, and within each attribute the result is an OR (disjunctive) search, widening the search. However, across attributes the result is an AND (conjunctive) search, narrowing the search. E.g., <txp:soo_image_select category="a,b" author="c" /> searches for images that are either in category “a” or “b”, but only those that are by author “c”.

form and listform are overridden by the tag contents when soo_image_select is used as a container tag.

Image selection attributes

Form output attributes

Example usage

Retrieve article images

<txp:soo_image_select />

When used in article context without any selection attributes, soo_image_select defaults to retrieving article images. To assign multiple images to an article, use a comma-separated list in the article-image field.

Global image context

New in Txp 4.3.0, pages can have URLs such as, i.e. global image context. When used outside article context and without selection attributes, soo_image_select retrieves images belonging to the current category.

Simple selection with specified image form

<txp:soo_image_select category="wildflowers" listform="simple_gallery" />

Retrieve all images in the “wildflowers” category; if more than one image is found, use the “simple_gallery” image list form for output. (If only one image is found, the default image form will be used.)

Complex selection

<txp:soo_image_select ext="jpg" author="joeblow, janedoe" />

Retrieve all jpg images authored by “joeblow” or “janedoe”

Direct selection as container tag

<txp:soo_image_select id="24,26,25">
<txp:soo_image />

Retrieve images 24, 26, and 25, in that order. Bypass default image form and display full-size images.

aspect_ratio syntax

<txp:soo_image_select aspect_ratio="1" />

Retrieve all images with an aspect ratio of 1 (i.e., square images)

<txp:soo_image_select aspect_ratio="+4:3" />

Retrieve all images with an aspect ratio of 4:3 or greater (i.e., wide images)

<txp:soo_image_select aspect_ratio="2/3-3/4" />

Retrieve all images with an aspect ratio between 2:3 and 3:4 (i.e., tall images)