About "SIIR"

that is, scalable inline image replacement

NOTE: This page is a mirror. The original page has been taken down by the author. The images here were rendered using the original scripts. See the xhtml+xml compliance test suite for some modifications and improvements to the scripts.

Welcome! It would appear that through either word of mouth or by perusing through my code you have stumbled upon this little mini-website-tutorial-dingy. Sorry, there's no grand prize for discovering the secret toy at the bottom of the box, but if you pay close attention, I'll give you some valuable information and a free program at that! Scalable Inline Image Replacement, more commonly known (to me, at least) as SIIR, is the dynamic image replacement method that I, Ryan Petrello, have personally developed and continually use on all of my client websites through AxisFive Media Solutions.

The SIIR program serves to basically change dynamic text on your website into pretty generated images with any font of your liking. The real magic of SIIR comes when you examine the XHTML source of this page. Those beautiful headings you see generated above are not pre-made images. They're merely <h1> and <h2> tags with text inside!

How It Works

in psuedo-code-english, i promise

In the likely case that you're a weird nerd like me and are interested in the inner workings of this program, here's the most basic description I can conjure up. In its most basic form, here's a generalized description of how SIIR works:

In a seperate JavaScript file named external.js, there is a variable that stores the XHTML tags that will be converted. This looks like this:

var elements=new Array("h1","h2");

Any elements within this JavaScript variable will be replaced with an image when the page is loaded.

In the same Javascript file, an array is used to store the settings for individual XHTML tags. The settings look a bit like this:

In the same Javascript file, there's another variable that stores the path to a website address of a PHP file called generate.php. This file is what essentially makes the image. The Javascript sends your defined settings (the code seen above) to the PHP program through an <img> tag. PHP then creates the image based on your approriate settings and returns the generated image. The JavaScript portion of this is a direct URL to your generate.php program:

var path="http://yourwebsite.com/siir/address/to/siir";

Other Tidbits

miscellaneous features, tidbits, etc...

SIIR is scalable, a very nifty feature. Two functions called "SIIR_add()" and "SIIR_subtract()" are included in the JavaScript file, external.js, for you to experiment with freely. For an example of their most basic use,

- or -

As one would imagine, bandwidth could become a potential problem here. Replacing all of the <h1> tags on a very large site, specifically one with dynamic content could be very server-intensive. Luckily, the PHP file included in the downloads section, generate.php, includes a pre-made caching program that saves and caches images that have previously been created. To enable this cache, simply add a folder named "/cache" and CHMOD it to 700.

As one would imagine, the number of files inside your "/cache" folder could grow exponentially if left alone. What if somebody views an older generated image that is never viewed again? Will this image sit idle on your server, using precious filespace, forever? Without some sort of way to clean this folder periodically, it could grow to tremendous sizes, especially on a larger commercial website! A function is included in the generate.php file that periodically removes cache clutter (that is, files that have not been accessed in a certain period of time).

For the accessibility freaks - before you pounce on me, relax. I've still got a few tricks up my sleeve. For those who have images turned off on their browsers, each generated <img> tag is equipped with an alt attribute; if you have images turned off, you'll simply see the original text. Similarly, if you have JavaScript turned off, the entire sequence will fail to commence, and the original text will be left to be styled by your CSS file(s).

Keep in mind that with this method, you can use almost any truetype font you have at your disposal. Simply upload the .tff (these can be found on your computer at C:/Windows/Fonts) to the same directory where your generate.php file resides. Then, in your the external.js JavaScript file, simply edit the following line so that it points to the font file of your choosing:

settings["h1"]["font_file"]="fontName.ttf";

Another problem that arises with this program is other people who wish to steal your bandwidth. If somebody were to set up an SIIR JavaScript file on their website and simply link to yourgenerate.php file, your server would do all the hard image-generating work. This is kin to somebody hotlinking your images, and may be prevented in the same way. In the folder in which you keep your generate.php file, simply upload an .htaccess file with the following code:

System Requirements

what you need for it to work

For SIIR to work correctly, you need a web server that has PHP4.2 or greater correctly compiled with the GD Library version 1.6 or greater. In the setup, make sure that you enable support for PNG and Freetype fonts, as these are the backbones of the SIIR program.

While SIIR works nicely with this setup, problems have arisen with users running PHP5. This is currently being investigated; if you're having PHP5 issues, expect a fix for this soon.

Download/Setup SIIR

take advantage of my sweat and blood!

Feel free to download the program and use it yourself. I would request that if you do use the program that you stick my name, or maybe a link to axisfive.netsomewhere in there or on your site, but if you're selfish and insecure I suppose you don't have to.

Once the files have been downloaded, there are a few simple steps to implementing them on your website:

Once you've got the files downloaded, unzip them from the archive and start browsing.

The first thing you will want to do is find the .htaccess file and open it. Inside you will find a few lines of text. Replace "yourwebsite.com" with your website's address and replace "http://yourwebsite.com/redirectTo.html" with the page you'd like to redirect to in the case that somebody tries to steal your bandwidth (your "hotlinking" message).

Next create a folder on your server where you'll store the SIIR program. Keeping it simple is best, so I usually try to stick with "/siir".

Inside of this folder, place the .htaccess, generate.php, and any .ttf font files you wish to use. Also create another folder here called "/cache".

Make absolute sure that you CHMOD the "/cache" folder to 700, or SIIR will not be able to cache your images. This is a very bad thing.

Open the external.js file and find the variable named "path". Change its value to point to your "/siir" folder on your server.

At the bottom of each page (right before you close the <body> tag) you're using SIIR on, make sure you place the following JavaScript coding to initialize the program:

<script type="text/javascript">
SIIR_init();
</script>

You're all set! Feel free to experiment and have fun with it. Good luck!

Common Errors/Problems

stuff to keep in mind

The following is a list of errors and small reminders along the way for those who plan on using this script.

Known ErrorWhy aren't images being added to my '/cache' folder?

While my documentation suggests that you CHMOD the '/cache' folder to "700", if you're continually having trouble with your cached images, try using "777" instead.

Known ErrorWhy is my XHTML showing up as plain text in my images?

All text within a tag desired to be changed will be changed. For example, the following XHTML code:

<h2><strong>Heavy Text</strong></h2>

...will result in the following image:

Heavy Text

Try to keep in mind that text-level elements like <strong>, <b>, and <i> will have no effect on the image generated by the SIIR program; they will simply be rendered as text in the image.

While there are a variety of things that could be causing this problem, here's a simple example that many people just don't think about. Keep in mind that in your external.js file, when you are choosing a .ttf font file for a certain tag, that font file must exist in the "/siir" folder. If the font that you're linking to does not exist, PHP will have no font file to work with and will simply terminate the script, leaving you with normal text. If you've got this code:

settings["h1"]["font_file"]="arialbd.ttf";

...the arialbd.tff file must exist in the "/siir" folder.

Known ErrorMy images are displaying as Red X's!

This is usually a good sign that your server does not have the necessary GD configuration or has not been built with support for Freetype (.ttf) fonts. To resolve this issue, talk with your server administrator.

Questions?

or comments, even

I'm too lazy at this point to make a spiffed-out contact form, so if you've got a specific question about SIIRthat is not addressed below, send a message to siir@axisfive.net. That's it. Enjoy.

comments (27)

Thanks for putting this comment form on this page. Didn't mean for my site to be the hotbed of discussion! This will open up the discussion of any problems/suggestions to many more people. Foir people just trying this out and who may have problems, there has been some discussion already on my site, including a 'fix' for a Firefox issue: http://www.masuga.com/?p=224

I'll be talking with my webhost, checking permissions, and anything else I can think of until I get this to work. If I discover anything, I'll be sure to post here. Thanks Ryan. - the other Ryan

Masuga, after checking over your coding, there's another possibility - in your "external.js", you're linking your "h1" and "h2" tags to the "arialbd.ttf" font. Are you sure this font file exists in your "/siir" folder? Just another possibility...

The fonts are in there, including the arialbd referenced in the external.js. I'm thinking (after talking with a co-worker versed in this stuff) that the PHP distribution must have Freetype support in GD (in other words be installed "with ttf"), which I know my current server doesn't have. I'll be talking with the server-meister (who sits about 20 steps away (I work at a web-design firm)) to see if he can enable that on the server. Hopefully it's as simple as that! I'll let you (and anyone interested enough to have read this far) know.

Yes, in the GD setup during PHP installation, there is a configure switch you must enable. I believe this switch is called "--enable-gd-native-ttf". More info is most likely available on the PHP.net website.

Foreign characters technically are supported in SIIR; you may just have an older version of a file. A few tweaks have been made recently to fix this problem. Try redownloading the files and replacing your external.js file with the new one.

Also, make very sure that your XHTML file is saved with UTF-8 encoding and that the appopriate character set is declared in your page's <head> tag. Another thing to keep in mind - if the font you are using does not have support for the language of your choice, it obviously won't be able to display a character in that language. Check out the following two images to see what I mean:

Testing: ę

Testing: ę

This character displays in the lower image because the font of choice is the much more widely used font "Arial". The upper image, however, is a font meant only to be used for English characters. I'm not quite sure what this says or even what language it is, but here's a working example of it:

Good point. By default any XHTML text you parse through the SIIR program will be displayed as read-only text. The PHP function, strip_tags(), will simply remove all of the tags, leaving text and no XHTML tags. A nice addition; thanks for the input.

Hi Ryan, a great piece of work that is going to save a lot of time and effort for a lot of developers I would imagine.

I was wondering if I could make a small suggestion. I do a lot of testing with screen readers and one issue is that although the source is still semantically correct the screenreader user only gets access to the generated output. This means all headings are lost and only images get read. I know the alt text is there but the structure does get lost. For example in jaws when you try to get a list of headings it will say "no headings found"

If the external.js file is changed slightly to wrap the outputted tags in the current element tag then screen readers like jaws read the page with the structure the author intended.

I changed line 157 to pasteHTML += '';

and this works great now for screen readers keeping the intended structure.

Just a thought for developers wanting the structure kept for all users.

Thanks for the useful suggestion! This is a valid and important observation for SIIR. After all, an image replacement technique wouldn't be nearly as potent if it did not completely cater to those without support for images. external.js has been updated in the SIIR downloadable file on this page with new code to fix this problem. Thanks again for your input.

The implications of this may be stretched beyond screen readers, however; using this new fix would also aid in making your websites easier to index by search engines such as Google. Rather than simply finding the replaced <img> tags, robots searching through your page's source code would be able to view the original unreplaced tags. This makes a drastic difference, as major search engines give more precedence to the contents of heading tags, and using them in the correct structural manner allows your pages to be more easily indexed.

I like a number of people had problems with this, but it is such a great idea i felt I must get it working.
I upgrade to the latest version of php5 and GD and it still wouldn't work although I had managed to get rid of the
red x boxes I still had no text. So I changed the path to the fonts to be the full path eg /home/sites/site1/web/siirtop/siir/arialbd.ttf
and it worked.
Brilliant work Ryan (and you now know it works on PHP5)

Thanks for the feedback, Andy! A few people have been having odd problems with their servers locating their font files. Perhaps using an absolute path could serve as a fix? Thanks again for the tip - I'll spread it around and see if it does any good for other people having SIIR problems.

Hi Ryan,
I've hit another strange one. On one server running php5 everything is fine, but on another using php4.3.10 (but exactly the same scripts) the spaces between words all come out as %20. Has anyone come across this problem before.

Any ideas on how this technique work in conjunction with gettext ? My client will invariably want his site internationalized and I find using gettext and locale files to be the most elegant way of doing it.

I'm not very familiar with the use of gettext, as I've never actually done a website which required foreign characters. I have, however, briefly skimmed over the specifications on PHP.net. The most simple answer I could give you would just be to open up the generate.php file and find the following lines:

Keep in mind that the variable for the outputted text in the generate.php script is "$this->text". Any changes you make to it will be displayed in the output of the image. Also make sure when using foreign character codes that you place the appropriate declaration inside of the head tag. Was this any help?

Hi !
I'm really excited about this siir, but there is only one thing now that i can't fix.
When i access the homepage the images are created in the cache catalogue but is not displayed in the homepage =(
Any ideas what I do wrong?

I was using this script here:
http://www.alistapart.com/articles/dynatext/
But was having several problems with it (wouldn't work with xhtml page served as application/xhtml+xml), and besides yours has more options/features and is more accessible anyway.

I downloaded the package, and worked to just set up the test page you included. It wouldn't work, and it was due to a javascript problem. This is using an unmodified external.js, so you have a problem in the file in your archive. The Firefox console spit this error out:

I played around with it, and turns out, just like Alistaparts replacer, yours fails when the XHTML page is actually delivered AS xhtml.

My site uses content negotiation to serve the browser what format they prefer. However, you can override this with query strings. (see the following two test pages).

http://pixeljunkies.com/test.php?forcehtml=true&trim=false

http://pixeljunkies.com/test.php?forcexhtml=true&trim=false

Your javascript is surely doing something that cant be done when the page is actually rendered stricly as xhtml. You can see, however, that the nifty corners javascript is working just fine.

Are there any known work arounds? Do you think you will be able to fix this?

Well, I just researched it some more, and I found this fix to Alistaparts script:
http://www.whaleofadive.com/misc/dtr/

Yet I can't find use of document.write in your script, so....?

Anyway, for now its back to Alistaparts script for me. I would much like to use yours, though. The shadow color, antialias, padding, and cache cleaning all sound great.

In addition, the Alistapart script also does one thing better then yours I think. If you render something such as "This is test text", it renders 4 different images, this causes the text to be able to wrap if it is in a container smaller then the text. Your script doesn't do this.

Fix these two things, the xhtml+xml and the line-breaking problem, and I think SIIR will be hands down the best Image Replacement Technique currently available.

Even though it doesnt appear your are supporting this anymore (a shame), just letting you know I have pin pointed SIIR's lack of "true xhtml" support to the use of innerhtml. Instead, you should use createElement() , createElementNS() and node.appendChild().

I am not too familiar with Javascript, so forgive what might be a simple question...

Anyone figured out how to limit the SIIR function to specific IDs or classes?

Credits

other people who helped

While the majority of this script was developed by myself, the following is a list of people who have made notable contributions, specifically in the category of pointing out my blatant errors.

Eric Duvic was very useful in clearing up heavy confusion involving the caching functions and in helping test these functions.

Rich Hodge was especially useful in pointing out some errors he was having involving CHMOD and text within <h1> tags (i.e. <h1><em>Text Here</em><h1> would display an image that read <em>Text Here</em> rather than emphasized text.)

Ryan Masuga was kind enough to point out the implications of a server without the correct GD library and appropriate Freetype font configuration.

Kieran Guckian offered a solution to make the SIIR script more structurally accessible to users viewing with screen readers.