TextBook

From Textbook

Revision as of 22:08, 9 March 2010

<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 of the id, name, and category attributes, it will grab a list of image IDs from the currently viewed article's article_image field. If it finds nothing there too, the tag will display nothing. See the context attribute for further information.

Attributes

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

id="integer"

A list of images to display as determined by the ids assigned at upload. The IDs can be found on the Images tab.

Default: unset.

name="image name"

A list of images to display, given by their image names as shown on the Images tab. If both name and id are specified, both are used to build the list.

Default: unset.

category="image category"

A list of images to display, given by their image category names as defined in the Categories tab. If used in conjunction with name and/or id, all images that match any of the attributes are chosen.

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.

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.

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.

Default: 0 (unlimited).

offset="integer"

The number of images to skip.

Default: 0.

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.

ext=".extension"

Filter the image list so it only includes images with this list of file extensions. Must include the period.

Default: unset.

author="author (login) ID"

Filter the image list so it only includes images uploaded by this list of author IDs (login names).

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.

thumbnail="boolean"

Set to 1 to filter the image list so it only includes images that have a thumbnail.

Default: 0.

context="string context"

List of Textpattern contexts to consider when automatically searching for images. Currently only one context is available: article, which will look in the article_image field. If you wish to turn off the automatic check for article_image, set this to context=""

Default: article.

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.

<txp:image_list context="" />

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 name="lion.jpg, zebra.jpg" id="2,3,6" />

images 2, 3, and 6 and the named images are displayed.

<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 category="mammals, birds" id="8, 42" />

all images in the named categories and images 8 & 42 are displayed.

<txp:image_list author="attenborough" />

all images by author (ID) attenborough 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 author="attenborough, morris" />

all images by the given author IDs are displayed.

<txp:image_list author="attenborough" realname="Desmond Morris" />

all images by the given authors and real names are displayed.

<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.

Example 2: description goes here

What it does...

...

Genealogy

Version 4.3.0

• tag introduced