zem_image_replace, or zem_ir, replaces text with a PNG image rendered using a TrueType font, and uses CSS to place the image on the page in such a way that the text is still accessible to text-only browsers. It’s similar, in some respects, to SIFR, except that zem_ir uses PNG and CSS where SIFR uses Flash and Javascript.

Because it integrates with Textpattern, zem_ir can be safely used to automatically turn any text into an image – not just a static heading, but article titles, dates, even excerpts and entire articles (not that we’d recommend that). All images are cached to save bandwidth and minimize server load. In most cases the title images created by zem_ir are very small, often less than 1kb each.

The image is generated by code based on Stewart Rosenberger’s Dynamic Text Replacement script. zem_ir supports several different CSS replacement methods, based on the most widely tested techniques. Alternative methods can be implemented using the class attribute.

Typical use might be something like this:

<txp:zem_ir font="myfont.ttf" wraptag="h2"><txp:page_title /></txp:zem_ir>

Which would automatically generate a PNG image containing the page title rendered in the specified font, and display it with code similar to this:

<h2 style="margin: 0 0 0 -5000px; background: url('/images/zir/b0f4c80ec436ee047716afc02b79cc92.png') no-repeat top right; height: 24px; text-align: left;">my page title</h2>

nb – this example assumes your image directory is writable, and the font file is stored in your home directory (not public_html).

A more complex example, using the new zem_ir_set tag to pre-define attributes:

<txp:zem_ir_set font="myfont.ttf" fontsize=32 backgroundcolor="#fff" color="#ccc" wraptag="h1" />
<txp:zem_ir_set group="subhead" font="myfont.ttf" fontsize=16 wraptag="h2" />

	
<txp:zem_ir><txp:page_title /></txp:zem_ir>
<txp:zem_ir group="subhead"><txp:site_slogan /></txp:zem_ir>
<txp:zem_ir><txp:title /></txp:zem_ir>

The first <txp:zem_ir_set> tag defines the default parameters used by <txp:zem_ir>. The second one defines a second set of defaults, identified by group="subhead". The page title and article title are displayed using the default settings (fontsize=32, etc); the site slogan is displayed using the group="subhead" settings (fontsize=16, etc). (Default parameters, where no group is specified, are not inherited by other groups, so the site slogan will not use the color and backgroundcolor settings specified in the first <txp:zem_ir_set /> tag).

Tags

<txp:zem_ir_set /> – specify the default parameters used by <txp:zem_ir> tags. The group attribute may be used to create multiple independent groups of parameters. <txp:zem_ir>...</txp:zem_ir> – create a PNG image containing the enclosed content, and use CSS to display it. The content may include any Textpattern tags, such as <txp:title />. Any parameters specified by zem_ir_set with the same group setting will be applied. Additional parameters may also be specified as attributes to the zem_ir tag.

For compatibility with older versions, <txp:zem_image_replace> is an alias for <txp:zem_ir>.

Attributes

Both tags support the following attributes:

group

Specify the group name. zem_ir will use any parameters specified by a zem_ir_set tag with the same group name. If no group is specified, both tags use a group named ‘default’.

info

Use info=1 to produce debugging output instead of creating an image. Default is 0.

fontdir

Absolute filesystem path to the directory where font files are found. Default is the directory containing the document root, typically your home directory (e.g. /home/myname/).

font

Pathname of the ttf font file, relative to the fontdir. May include subfolders.

fontsize

Font size in pixels. Default is 24.

color

Font color, in #rrggbb or #rgb format. Default is ”#000000”.

backgroundcolor

Background color, in #rrggbb or #rgb format. Default is ”#ffffff”.

angle

Text rotation angle in degrees, counter-clockwise from horizontal. Default is 0.

trans

1 for a transparent image, 0 for a solid image. Default is 1.

aa

1 to use anti-aliasing if available; 0 to disable. Default is 1.

ft

1 to use Freetype 2 if it’s available; 0 to disable. Default is 0.

depth

Image depth in bits, 8 or 24. Default is 8.

cachedir

Folder used to store generated images, relative to the document root. Default is ”[prefix]/images/zir”. The final subdirectory will be created if it does not exist. This folder must be writable (chmod 0777).

wraptag

Tag used for image replacement. Default is h1

width

height

CSS element width and height. Set this if you need the wraptag element to be a different size to the image. Defaults to the image size.

wrap

Word-wrap text to a specific width limit, in pixels. Default is 0, no wrapping. The pixel width refers to the dimensions of the text before rotation and padding is applied.

position

Image position. Default is “top left”. Doesn’t work well with all image replacement methods.

limit

Maximum number of characters to pass to the image replacement script. Default is 0, no limit.

class

If set, the generated code will only provide the background attribute in the inline style. Use this if you want to shift the CSS to your stylesheet, or use a different replacement technique (e.g. FIR).

padding

Padding around the text within the image, in pixels. Use this to compensate for bounding box errors with some fonts. Provide a single number for equal padding on all sides, or “1 2 3 4” to specify the top, right, bottom and left separately. Default is “0”.

transform

Transform the text used to create the image. One of “uppercase”, “lowercase”, “capitalize”.

method

Image replacement method. One of “phark”, “radu”, “dwyer”, “lir”, “img”. Default is “phark”.

tr

Convert unwanted characters to spaces before creating the image. Useful for fonts that don’t provide a complete character set. For example, tr="_/" will convert underscores and slashes to spaces. Default is no conversion.

tt

Alternate replacement character to use with tr. Default is " ", a space.

text

Specify the text to display. May be used instead of an enclosing tag as a shorthand for creating images with static text. For example, <txp:zem_ir text="hello world" /> is equivalent to <txp:zem_ir>hello world</txp:zem_ir>.

Some notes on the different CSS replacement methods:

phark

“Phark Revised”, the most reliable method in most circumstances. Tests well in IE, Mozilla, Opera and Konqueror, and allows left, right or center positioning.

radu

Radu Darvas’ negative margin method. Tests well in IE, Mozilla, Opera and Konqueror, but only when right aligned.

dwyer

Leon Dwyer’s enhanced FIR method. Tests well in IE, Mozilla, Opera and Konqueror. Uses an extra <span> tag.

lir

Leahy/Langridge overflow method. Tests well in IE, Mozilla and Opera, but fails in Konqueror and Safari.

img

Doesn’t use CSS replacement at all, but simply produces an <img> tag with a link to the generated PNG image. Text content will be included in the alt attribute.

zem_ir is Copyright 2004-2005 Threshold State.
Distributed under the terms of the GNU General Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.