soo_image user guide Page 9 of 16 « »

soo_image_select

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; or retrieve article image(s). 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)

<txp:soo_image_select>
... *soo_image* tags and other content
</txp:soo_image_select>

Attributes

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, soo_image_select looks for the article image(s) and so requires an article context.

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

• name (text)
  Txp name (from Content->Images) of image to select for display. Will accept a comma-separated list for multiple images.
• id (integer)
  Txp ID (from Content->Images) for image selection. Will accept a comma-separated list for multiple images; multiple id values can also be entered as ranges (“id:id” or “id-id”), including multiple ranges, preserving order (e.g., “44-46, 11:9” equivalent to “44,45,46,11,10,9”)
• aspect_ratio (text)
  Image aspect ratio (width:height), written as a number (e.g. “1.5”) or ratio (e.g. “3:2” or “3/2”). Optionally prefix “+” to get greater than or equal to specified aspect ratio, or “−” to get less than or equal to (e.g., “+3:2” returns images with an aspect ratio of 3:2 or greater). Or, optionally give two ratios separated by “−” to specify a range (e.g., “1-2”, “4:3-3:2”, etc.)
• author (text)
  Comma-separated list of author names (login names) for image selection.
• category (text)
  Comma-separated list of categories for image selection.
• ext (filename extension)
  Comma-separated list of file types for image selection, e.g. “png,jpg”.
• limit (integer)
  Limit on number of images to return per page. Defaults to “0”, no limit.
• sort (MySQL sort value)
  Sort order to use when selecting by author, category, aspect_ratio and/or ext. Defaults to “name asc” (alphabetical by image name). Other possibilities include “date desc” (most recent first) and “rand” or “random” (random). sort is overriden when selection is by name, id, or article image.
• pagination (boolean)
  Enabled by default. Set pagination="0" to prevent this tag from changing or using pagination variables. In general this is only needed when using multiple soo_image_select tags on a single page, and where more than one of these tags has a limit set.
• persistent_context (boolean)
  Enabled by default, so that later soo_image tags will find the first selected image if they don’t find something else first. Set persistent_context="0" to prevent this behavior.

Form output attributes

• form (text) Required (except when using soo_image_select as a container tag)
  Name of Txp form to apply to the image(s). Defaults to “soo_image” (or the plugin’s preference value, if you have assigned one).
• listform (text)
  Name of Txp form to use if multiple images are retrieved. Defaults to the same value as form (or whatever value you have assigned to the global array).
• break (text)
  HTML tag name (no brackets) or text to separate multiple images.
• wraptag (HTML tag name)
  HTML tag name (no brackets) for element to wrap the image(s).
• class (text)
  HTML class name for the wraptag.
• html_id (text)
  HTML id for the wraptag.

Example usage

Retrieve article images

<txp:soo_image_select />

When used 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. If used in this way, soo_image_select requires article context.

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 />
</txp:soo_image_select>

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)

• soo_image user guide
• Up
• Prev
• Next
• Download
• License