Go to main content

Menu

Image

Contents

Syntax

<txp:image />

The image tag is a single tag that Textpattern will replace with the <img src="…"> HTML tag matching the image of the numeric id assigned by Textpattern when the image was uploaded via the Textpattern Images panel.

The tag outputs the alt, width, and height attributes by default. If you don’t need to set image dimensions (e.g. if you use width: 100% in your CSS), you can ‘turn off’ the effect of the width and height attributes by using width="0" height="0".

The tag is also context-sensitive: if an id or name attribute is not specified, it can be used inside an images tag or form to output an <img src="…"> HTML tag matching the current image.

Attributes

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

escape="html" v4.0.4+
Escape HTML entities such as <, > and & for the image’s alt and title attributes.
Values: See the tag escaping documentation for all possible values.
Default: html.
height="integer" v4.3.0+
Specify an image height which overrides the value stored in the database. Use height="0" to turn off the output of a width attribute in the <img> tag (thus the browser will scale the height if a width is used).
Default: height of image stored in the database.
html_id="id" v4.0.4+
The HTML id attribute applied to the wraptag, if set, otherwise to the <img> tag.
Default: unset.
id="integer"
Specifies the id, assigned at upload of the image, to display. Can be found on the Images panel. If both name and id are specified, name is used while id is ignored. If neither is specified, the tag must be used within an images tag or form.
loading="text" v4.8.3+
HTML loading attribute to be applied to image. Specifies how a browser should handle loading of the image.
Values: lazy (defers loading the image until it reaches a calculated distance from the viewport, as defined by the browser), eager (loads the image immediately, regardless of whether or not the image is currently within the visible viewport).
Default: unset.
name="image name"
Specifies which image to display by its image name as shown on the Images panel.
style="style rule"
Inline CSS style rule. It’s recommended that you assign CSS rules via the class attribute instead.
Default: unset.
thumbnail="boolean" v4.8.0+
Whether to display the full-size (0) or thumbnail-size (1) image.
Default: 0.
title="boolean|title text" v4.8.0+
Adds the given text as an HTML ‘title’ attribute to the image. If used as a valueless attribute, will use the caption as text.
width="integer" v4.3.0+
Specify an image width which overrides the value stored in the database. Use width="0" to turn off the output of a width attribute in the <img> tag (thus the browser will scale the width if a height is used).
Default: width of image stored in the database.

Common global attributes

These attributes are shared by all tags - and plugins, provided they do not override the functionality.

break="value"
Where value is an HTML element, specified without brackets (e.g. break="li") or some string to separate list items.
Default: br (see break cross-reference).
breakby="integer(s)"
Used to group list items when separating by break. Possible values are lists of integers, like 2 (groups of 2 items) or 1,2 (alternate groups of 1 and 2 items). Otherwise, the value is evaluated on each loop and `break` happens as soon as it changes. Note that `string` must be enclosed in *double* quotes.
Default: 1 (unset) (see breakby cross-reference).
breakform="form name"
A form to be used as `break`, generally jointly with `breakby` attribute. The special `<+>` pattern in this form will be replaced with the list "chunk" accumulated when break happens.
Default: unset (see breakform cross-reference).
class="class name"
HTML class to apply to the wrapper.
Values: Any valid string.
Default: unset.
default="value"
The value to display if the tag's output is blank.
Values: Any.
Default: unset.
escape="list, of, transforms"
The transforms to apply to the output. See tag escaping for details.
Values: html, js, json, url, float, integer, number, ordinal, spell, lower, upper, title, [r|l]trim, quote, tags, textile, _any tag_
Default: html.
evaluate="number list"
Alter the processing order of top-level tags inside a form/container. Tags are normally executed from top to bottom. If you wish to change this order, imagine Textpattern tags are numbered incrementally from 1 inside a container. To process tags 3 and 5 first, then 1, 2, and 4, specify evaluate="3, 5" in your container tag.
Values: Any comma-separated numbers corresponding with the numerical position of primary (top-level) tags inside the container.
Default: unset.
html_id="value"
HTML id to apply to the wrapper.
Values: Any valid string.
Default: unset.
label="value"
The label to display before the output.
Values: Any valid string.
Default: unset.
labeltag="tag"
The tag (without angle brackets) to wrap the label.
Values: Any valid HTML tag, e.g. h3 or div.
Default: unset.
not="boolean"
Switch parts.
Values: 0 (no) or 1 (yes).
Default: unset (0).
replace="string"
Replace the content stripped via the trim attribute.
Values: Any valid string.
Default: unset.
trim="string or regex"
Remove the matching patterns from the output.
Values: Any. Use /value/ to trigger regular expression matching, otherwise the value will be treated verbatim as a set of characters to trim.
Default: unset.
wrapform="form name"
The form to be used as wraptag. Handy if the wraptag pattern is too long, or is reused.
Values: Any defined form name.
Default: unset.
wraptag="tag or pattern"
The tag (without angle brackets) to wrap the output.
Values: HTML tag or a string containing <+> pattern that will be replaced by the output.
Default: unset.

Examples

Example 1: Display the given image

<txp:image id="42" />

Displays the image uploaded as ID #42.

Example 2: Apply a CSS class

<txp:image name="chickens.jpg" class="promoted" />

Displays the image named chickens.jpg and assigns a class="promoted" attribute/value to the <img> tag.

Had the wraptag attribute been used, the class="promoted" attribute/value would have been applied to that instead of directly to the image tag.

Example 3: Use within images tag

<txp:images>
    <txp:image />
</txp:images>

Displays full-size images for all images found by the images tag.

Genealogy

Version 4.8.3

loading attribute added.

Version 4.8.0

title attribute added.
thumbnail attribute may be used instead of the dedicated thumbnail tag.

Version 4.3.0

height and width attributes added.
Added context sensitivity within images tag.

Version 4.2.0

align attribute deprecated.

Version 4.0.7

Default value for escape attribute changed from ‘unset’ to html.

Version 4.0.4

escape, html_id and wraptag attributes added.

If you notice any kind of problem with this page's construction or content (outdated information, typos, broken links, or whatever), open an issue to have it sorted. Or have a go at it yourself. :)