RubyFrontier Documentation

Images and IMG Tags

On this page, I talk about how to do images in your Web pages. Images involve macros, and I haven’t formally discussed macros yet, but you don’t actually need to understand the details of macros in order to do images, and users are naturally anxious to start using images right away; hence this independent discussion.

Image Basics

To generate references to images within the site, you do two things, as follows:

  1. First, you have to have an image file. Place it in an #images folder in your source folder, in a location such that it will be found when the page table is built. (Personally, I usually just keep all images in a single top-level #images folder.)

  2. Second, in the page body or template, use the imageref() call in a macro. For example, you might say this:

     <%= imageref("myimage") %>

    If the image file’s simple name (without the extension) is myimage (for instance, it might be myimage.png), it will be located (in the #images folder) and copied out into the Web site folder. The macro call then returns an <img> tag whose src attribute is a relative URL from the page being built to the image file. The <img> tag will also have a height, width, and alt attribute.

Every #images folder containing an image file that is actually referred to by an imageref() call results in a folder in the Web site at the same relative location, called images, and the image file is copied into this folder. Thus you can have many images folders throughout your site, though the simplest and most common situation is probably to have a single #images folder at the top level of your source folder, where all pages can see it, and thus a single images folder in the rendered site.

Optional IMG Tag Attributes

An optional second parameter in the imageref() call is a hash of names and values that you can use to set additional attributes of the <img> tag that will be generated. You may supply as many as you like of the following:

So, for example, an imageref() call that includes some of these optional values might look like this:

    <%= imageref("myimage", {:border => "1", :alt => "A great image"}) %>

Images Without imageref()

All of the above presumes that you’re calling imageref() to generate an <img> tag. But there are circumstances where you want to refer to an image within your site, without using an <img> tag. For example, you might do this from a JavaScript or CSS file.

In this case, you’re going to need to use some other strategy to get the image copied from the source folder into the Web site folder. There are two main strategies:

To help with this, starting in RubyFrontier, JavaScript and CSS files are now macro-processed by the standard macros that deal with them. This not full macro-processing; it’s really just a call to ERB in the current context. But the current context is the PageMaker object, so calling getImageData() without the .html prefix will work. Moreover, in the case of a stylesheet or JavaScript file that’s going to be linked to (not embedded), adrPageTable[:sheetLoc] will be the path to that file, so this can be used to work out the relative URL to the image.

For example, here’s how a CSS stylesheet file might refer to a background image:

    <% def writeAndGetRelativeURI(im)
    end %>
    body {
      background-image: url(<%= writeAndGetRelativeURI("body_bg") %>);
      background-repeat: repeat;

The method writeAndGetRelativeURI() does just what it says: it causes the named image to be written into the Web site, and works out its URL relative to the stylesheet itself within the Web site. That relative URL is substituted within the CSS, in the url(...) construct, and thus the relative URL works — it is correct, and the image is present. Meanwhile, the def stuff at the top of the stylesheet is removed (note the lack of an equal-sign in the macro call; this means that nothing is substituted into the stylesheet at this point), and so the stylesheet is legal.

Nevertheless, in some cases (where, for example, there are a lot of images), you might like to take a simpler batch approach and copy out explicitly all the images in the #images folder every time any page is rendered, by calling a macro (let’s call it spit()) in the template:

    def spit
      h = @adrPageTable["images"]
      h.keys.each do |img|

This is not particularly inefficient, because html.getImageData() only performs an actual copy if an actual copy needs to be performed; if the image has already been copied into place in the Web site, and has the same modification date as the original, no copying takes place. The spit macro ignores the data returned by html.getImageData, and your call to spit() would also ignore its results, like this:

    <% spit() %>

(Note the lack of an equal-sign in the macro call; this means that no results are entered into the Web page being rendered at this point.) It is possible to use html.getImageData in more sophisticated ways, where you actually do care about the results it returns; for an example, look at the caption() macro used to generate the image-plus-caption pairs in this documentation.

Next: Outline Renderers

This documentation prepared by Matt Neuburg, phd = matt at tidbits dot com (, using RubyFrontier.
Download RubyFrontier from GitHub.