image list

From Textbook

Tag reference quick links:

<txp:image_list />

The image_list tag is a single or container tag that Textpattern will use to gather a list of matching images uploaded via the TXP Images tab. Utilising the other image tags in the suite image_info, image_url, image_date and if_thumbnail) you can display simple image galleries from this list.

If used as a container tag, it must be specified as an opening and closing pair of tags, like this:

<txp:image_list>
...contained statements...
</txp:image_list>

This is equivalent to putting the contained statements into a form named "my_form" and using <txp:image_list form="my_form" />.

By default, the tag is context-sensitive, which means that in the absence of any other filter attributes (id, name, category, author, realname, ext, thumbnail), it will grab a list of image IDs from the currently viewed article's article_image field. If it finds nothing there, it will check the URL to see if there is a category list in progress. If it finds nothg there too, the tag will display nothing. See the auto_detect attribute for further information.

Attributes

Tag will accept the following attributes (case-sensitive):

id="integer"

Filter the images by this list of ids assigned at upload. The IDs can be found on the Images tab.

Default: unset.

name="image name"

Filter the images by this list of image names as shown on the Images tab.

Default: unset.

category="image category"

Filter the images by this list of category names as defined in the Categories tab.

author="author (login) ID"

Filter the images by this list of author IDs who uploaded the pictures to Textpattern.

Default: unset.

realname="author name"

Filter the image list so it only includes images uploaded by this list of author real names. The author names may be URL encoded (e.g. realname="John+Smith") and thus could be read from the current site.com/author/author+name URL. Note that this attribute may incur one extra query per name, so if it is possible to use the raw author instead it will be faster.

Default: unset.

ext=".extension"

Filter the images by this list of image extensions, including the leading dot. Example: ext=".jpg, .png"

Default: unset.

thumbnail="boolean"

Filter the image list to only include images that have a thumbnail (1) or not (0).

Default: unset (i.e. all images).

label="text"

Text to display above the list of images as a label.

Default: unset.

labeltag="tag text"

HTML tag to be used to wrap the label, specified without brackets.

Default: unset.

wraptag="tag text"

HTML tag to be used to wrap the img tag, specified without brackets.

Default: unset.

html_id="id number"

The HTML id attribute applied to the wraptag, if set, otherwise to the img tag.

Default: unset.

class="class name"

CSS class attribute applied to the wraptag, if set, otherwise to the img tag.

Default: unset.

break="tag text"

The (X)HTML tag (without brackets) or string to separate each image.

Default: unset.

limit="integer"

The number of images to display per page.

Default: 0 (unlimited).

offset="integer"

The number of images to skip.

Default: 0.

pageby="integer" (or "limit")

The number of images to jump forward or back when an older or newer link is clicked. Without this attribute, pagination is not available; you will simply see limit images. You may specify pageby="limit" to allow pagination to automatically follow the value of the limit attribute. NOTE: newer and older will paginate all content types at once.

Default: unset.

sort="sort value(s)"

How to sort the resulting image list. Specify an image attribute from the ones below and add either asc or desc to sort in ascending or descending order, respectively.

Values:

id (image id#)

name (image name)

category

ext (image extension)

author

alt

caption

date

w (image width)

h (image height)

thumb_w (image thumbnail width)

thumb_h (image thumbnail height)

rand() (random)

Default: name asc

form="form name"

Use specified form for each image. If not used, and the container is empty, the tag will output a list of images that are compatible with image_display.

Default: unset.

auto_detect="string context"

List of Textpattern contexts to consider when automatically searching for images. If you wish to turn off the automatic check, set this to auto_detect="". You can choose from the following contexts:

article to look in the article_image field

category to look in the URL for a category list

author to look in the URL for an author list

Default: article, category, author

Examples

Example 1: varying attributes

This example shows the outcome of various attribute configurations to give you an idea of what to expect from the tag. More concrete examples follow.

<txp:image_list />: uses the current article image field as a list of image IDs. If the article image field is empty, it contains names/URLs, or the tag is used on an article list page, it returns no images. If, however, the tag is used on a category list page (e.g. category/image/photos) then the photos category would be used
<txp:image_list auto_detect="" />: displays all images in the database.
<txp:image_list id="" /> <txp:image_list name="" /> <txp:image_list category="" />: no images displayed. This means that if you did some tag-in-tag magic such as : category='<txp:custom_field name="my_cats" />' it will show no images if the custom field is empty.
<txp:image_list id="2,3,6" />: display images 2, 3, and 6.
<txp:image_list name="lion.jpg, zebra.jpg" />: the named images are displayed.
<txp:image_list name="pengiun.jpg" />: no images are displayed (mis-spelled image name).
<txp:image_list category="mammals, birds" />: all images in the named categories are displayed.
<txp:image_list category=", mammals, birds" />: all images in the named categories and any uncategorized images are displayed.
<txp:image_list category=" " />: just uncategorized images are displayed (note that category="," also works, but a space looks better).
<txp:image_list author="attenborough, morris" />: all images by author (ID) attenborough and morris are displayed.
<txp:image_list realname="David+Attenborough" />: all images by author David Attenborough are displayed. This incurs one extra query to look up the author's ID from the given real name.
<txp:image_list category="mammals, birds" author="attenborough, morris" />: all images in the named categories that are assigned to the named authors are displayed.
<txp:image_list category="mammals, birds" ext=".jpg" />: all jpg images in the named categories are displayed.
<txp:image_list category="mammals, birds" ext=".jpg" author="attenborough, morris" />: all jpg images in the named categories that are assigned to the named authors are displayed.
<txp:image_list ext=".gif" />: all GIF images are displayed.
<txp:image_list category="mammals, birds" thumbnail="1" />: all images in the named categories that have thumbnails assigned to them are displayed.
<txp:image_list thumbnail="1" />: all images that have thumbnails assigned to them are displayed.
<txp:image_list thumbnail="0" />: all images that do not have thumbnails assigned to them are displayed.

Example 2: description goes here

What it does...: ...

Genealogy

Version 4.3.0

tag introduced

Main Topics

image list

From Textbook

Contents

Attributes

Examples

Example 1: varying attributes

Example 2: description goes here

Genealogy

Version 4.3.0

Translations [?]...

Toolbox

More Wiki Usefulness

Txp Resources