htmlImage Suite (F4)

ODB name: suites.htmlImage
Version: 2.1
Version Date: 14 November 1997
Download: htmlimage.hqx
Some Images: samimages.hqx
Contains some 12-pixel-high "picons",
32x32 "icons", 16x16 "bullets", and a highly un-optimized default set of drop caps to get you started with the image styles.
  Release notes


Contents

1. Introduction 9. Image Styles

2. Copyright 10. Menu Options

3. Installation 11. Glue Scripts

4. Image Table 12. Filter Scripts

5. Directives 13. Usage Examples

6. Preferences 14. Site Image Glossary

7. Attributes 15. Troubleshooting

8. Virtual Attributes 16. Conversion Scripts


1. The htmlImage Suite

This suite provides a set of tools for managing the #images table of a website in the ODB. It will import images into the table or create links to images (in the form of aliases) through the table. See "Menu Options" for more information on the image management tools.

It also provides a set of image style scripts to simplify the inclusion of various images for various purposes, while providing a consistent appearance. See "Image Styles" for information on working with image styles.

Dependencies

In order to do its magic, htmlImage requires the following suites:


2. Copyright and Permissions

Created by Samuel Reynolds.
Copyright © 1996, 1997 by Samuel Reynolds. All rights reserved.

Permission is hereby granted to use the scripts in this suite for private or commercial use at no charge, and to distribute them with this documentation in their original form. You may modify the scripts for such purposes, but may not distribute the modified versions of the scripts.

If you have suggestions or changes you think should be included for distribution with future versions of this software, please contact the author at <reynol@primenet.com>.


3. Installation

To install the htmlImage suite, double-click on the suites.htmlImage "pony" file. From the Suites menu, select htmlImage. Then from the #Image menu, select Initialize Suite. This creates the user.htmlImage table and its subitems. (If the table or any specific subitems already exists, it will not replace it.)

The commands in the #images menu will affect user.htmlImage. All editing of image Styles is done in user.htmlImage.style, not in suites.htmlImage.data.style.

Note:

Versions of htmlImage after 1.05 install "forwarding" scripts in user.html.macros that call the corresponding scripts in htmlImage so you don't have to type
htmlImage. before each macro in your site source files. This eliminates the need for the path "@suites.htmlImage" in system.misc.paths. I'm told that Frontier, when it encounters macros in your site source files, will look for them in user.html.macros automatically. This does not happen on my machine. If it also doesn't happen on yours, add the path "@user.html.macros" to system.misc.paths. Since Frontier is supposed to search this path anyway, it shouldn't cause problems.

Upgrading From an Earlier Version:

1. If you have defined new image styles or customized predefined styles in user.htmlImage.style, export user.htmlImage.style to disk.

2. Delete user.htmlImage, then select Initialize Suite from the #Image menu.

3. If you exported user.htmlImage.style in step 1, double-click on the file in the finder to re-import it.

Upgrading From v. 1.05 or Earlier:

After following the above steps, open system.misc.paths and remove the path "suites.htmlImage" if it exists.


4. Image Tables

What Is An Image Table?

The htmlImage suite depends on the presence of image tables within the hierarchical tables of a site in the ODB. These tables are assumed to be named "#images".

The htmlImage routines (notably htmlImage.ImgRef(), the primary access point for the suite) are called with an image tag, which is the name of an image entry in an #images table. The suite searches for a table named "#images" containing an entry whose name is the tag.

The image search proceeds upward from the table containing the page currently being rendered (the parent of html.data.page.adrobject) all the way up to html.data.page.adrSiteRootTable. If the image is not found, it is also sought in user.websites.["#images"], if that table exists. The image may also be sought in a site image glossary (see Site Image Glossary more information). If the image is still not found, htmlImage throws a scriptError().

A hierarchical site may contain multiple #images tables, one at each level of the site (i.e., within the site subtables). Or, like a single-level site, it may contain only one #images table, at the top level of the site.

The #imageLoc and #imageBase directives determine the placement of images from the #images table(s) in the rendered site. See the section on Directives for more information.

Note:

Preceding the name of an item in the site table with "#" results in it being copied to html.data.page as a directive. (In the case of a table, the ODB address of the table is placed in html.data.page.) It also suppresses any attempt to build the item into a page or sub-site. This second behavior is the reason for naming the image table "#images". The entry in html.data.page (html.data.page.images) is ignored completely.

Image Table Entries

An image entry is an item in an #images table. It is referred to by its name, which is used as an identifying tag in calls to htmlImage.ImgRef(). An image table may contain one or more of the following types of entry:
alias
The alias of an external image file. The file will be copied to the rendered website when a referencing tag is generated.

binary
The binary data for an image, loaded from an external file. The name of the external file is not recorded anywhere. The data will be written to an external file in the rendered website when a referencing tag is generated.

image data table
The table contains all the fields defined by the mediaInfo suite (which is used to create the table). See mediaInfo.documentation for information on these fields. Only a few of these fields are used by htmlImage:
  • name -- short name of the external image file.
  • path -- string or filespec identifying external image file.
  • physicalHeight and physicalWidth -- image size in pixels.

The image data table also contains additional fields not provided by mediaInfo:
  • modified -- last modification data for the file.
  • style -- (OPTIONAL) base style for rendering the image tag. If omitted, base style is "default".
  • styleTable -- (OPTIONAL) table of tag attribute values to override base style.
  • map -- (OPTIONAL) (client-side) image map specification text.

Image Subtables

Subtables may be placed inside an #images table. The name of each image subtable must begin with the "$" character. Subfolders may be nested inside other subfolders.

Image entries within these subtables will be rendered into subfolders nested inside the rendered image folder. The logic for placement of image folders remains as described in the section on Directives. The image subtables and their rendered subfolders allow you to enforce a level of organization within the image folder.


5. Directives

Image placement in rendered site

The #imageBase Directive

Defines name of image folder in rendered site. If left undefined or defined equal to "" (the empty string), images are placed directly in site folder at level specified by #imageLoc.

The #imageLoc Directive

May be set to "", "global", "local", or "hier". If undefined, default is "global".

If set to "global" or "" (the empty string), or undefined, all images are placed in the rendered site's root folder. The #imageBase directive determines whether the images are placed directly in the respective site folder or in a subfolder of that folder.

If set to "local", each image is placed in site folder or subfolder corresponding to the location (in the web site table hierarchy) of the #images table containing the image entry. The #imageBase directive determines whether the images are placed directly in the respective site folder or in a subfolder of that folder.

If set to "hier", the site folder hierarchy is duplicated within a global image folder, and each image is placed in the subfolder of the global image folder corresponding to the #images table's location in the web site table hierarchy. If the #imageBase directive is not defined equal to a non-empty string, it defaults to "image/".

Summary of Image Placement Directive Options:

imageLoc = "global"
imagebase = "img/"
imageLoc = "global"
imagebase undefined
   
imageLoc = "local"
imagebase = "img/"
imageLoc = "local"
imagebase undefined
   
imageLoc = "hier"
imagebase = "img/"

The #autoGenAltText Directive

Specifies whether and how to automatically generate text for the ALT attribute. May be set to "", "none", "file", or "tag". If undefined, default is "none".

Has no effect if a value for the alt text attribute is provided in the data table image entry, the appropriate named image style, or the override parameter.

Specifying an alt text attribute of "" (the empty string) at any of these levels will suppress the alt text attribute (it will not appear in the rendered tag).

If the alt text attribute is not otherwise defined:

If #autoGenAltText = "" or "none", the alt text attribute is not automatically generated; it is omitted if not otherwise provided.

If #autoGenAltText = "file", the alt text attribute is set to the short filename of the image source file. If the image record is a binary record, this case is equivalent to "none".

If #autoGenAltText = "tag", the alt text attribute is set to the tag used to look up the image in the #images table plus the string " image".

The #noSiteImageGlossary Directive

Suppresses the generation of a site image glossary. To allow generation and use of a site image glossary, omit this directive.

See Site Image Glossary for more information.


6. Preferences

imgAttribsMustExpand

This preference is defined in user.html.prefs. HtmlImage.Init() sets it to true if it is not already defined.

If true, when htmlImage is unable to find an expansion for an expansion parameter to an attribute (see "Attributes"), it posts a scriptError(), which results in the well-known macro-error block in the rendered html file. If false, when htmlImage is unable to find an expansion for an expansion parameter to an attribute, it leaves the attribute value set to the tag string (including brackets).


7. Attributes

Attribute Override Priority

The override sequence for all attributes is (uppermost overrides):
  1. override parameter
  2. #images.[image_name].styleTable.[attribute_name]
  3. user.htmlImage.style.[style_name].[attribute_name]
  4. programmatic default value generation, if applicable. (Currently only applies to ALT, HEIGHT, and WIDTH attributes.)

Attribute Override Syntax

Attributes in the override parameter are of the form name=value, where value is a string optionally surrounded by
  • straight or curly double-quotes,
  • nothing, or
  • double square brackets.

Values within straight or curly double-quotes are treated as string literals. They may contain whitespace. No conversion or lookup us done on string contents. The use of straight or curly double-quotes allows htmlImage to properly recognize values containing spaces (such as alt text), as well as allowing the alternate enclosure to be included if necessary (i.e., an item in curly quotes may contain straight quotes, and vice versa).

Values without quotes or brackets (e.g., "border=0") are treated as string literals. They may not contain whitespace. No conversion or lookup us done on string contents.

Values surrounded by double square brackets (e.g., "linkto=[[where to go]]") are treated as glossary or image lookup key tag. The tag (with the brackets removed) is looked up first in the glossary; if a glossary entry is found, it is substituted as the attribute value. If the tag is not found in the glossary, it is looked up in the image hierarchy. If the tag is found in the image hierarchy, the image's relative URL is generated and substituted as the attribute value.

If an expansion tag is not found in either the glossary or the image hierarchy, and imgAttribsMustExpand (a new preference in user.html.prefs) is true, htmlImage posts a scriptError. If imgAttribsMustExpand is false, it leaves the attribute value equal to the expansion tag (including brackets). Note that html.getPref() returns TRUE if it doesn't find a requested preference entry in user.html.prefs.

User.html.prefs.imgAttribsMustExpand is set to TRUE at installation, unless it already exists (i.e., from an earlier installation of htmlImage).

The lookup notation ([[...]]) is particularly useful for the LINKTO attribute.

ALT Text

The ALT attribute will be set automatically if the #autoGenAltText directive has been set to either "file" or "tag" and no value is provided for the attribute through the image data table entry, the style definition, or the override parameter. If the attribute has been defined in any of these three places, even if it is defined as "" (the empty string), the attribute's value will not be set.

For autogeneration of the alt text to work, there must be *no* entry named "alt" in either the style definition table or the styleTable subtable of the image data entry table. If such an entry exists, it becomes the default entry, according to the override sequence described above.

The default definition of the button style (user.htmlImage.style.button), for example, defines alt="" (the empty string) to suppress autogeneration of alt text.

If alt text is defined at some point in the override sequence, it may be suppressed by including "alt=\""" in the override parameter.

If alt text autogeneration is suppressed by a value of "" (the empty string) at some point in the override sequence, it cannot be restored by a parameter later in the override sequence.

HEIGHT and WIDTH

The HEIGHT and WIDTH attributes are treated together, so that proportional scaling is properly performed when only one is specified.

The HEIGHT and WIDTH attributes will be set automatically if no value is provided for the either attribute through the image data table entry, the style definition, or the override parameter. If either attribute has been defined in any of these three places, even if it is defined as "" (the empty string), the attributes' values will not be set automatically.

For autogeneration of the height and width to work, there must be *no* entry named "height" or "width" anywhere in the override sequence (as described above).

The default definition of the default style (user.htmlImage.style.default), for example, does not define either height or width attributes, thus allowing them to default to the actual dimensions of the image.

If height or width is defined at some point in the override sequence, you cannot force auto-generation of the height and width attributes.

LINKTO

If the LINKTO virtual attribute is defined, and its value is not "" (the empty string), the rendered image tag will be wrapped in an anchor (<a>) tag to make it a hot link to the destination specified by the LINKTO attribute.

LINKTO is also used for specifying server-side image maps (see below).

Examples:

htmlImage.ImgRef( "myImage" ) generates the tag
<img src="myImage.gif">

htmlImage.ImgRef( "myImage", "linkto=[[myDest]]" ) generates the tag
<a href="http://mysite/somefile.html"><img src="myImage.gif"></a>

URL

If the URL virtual attribute is defined, htmlImage.ImgRef() will return only the URL of the specified image, rather than the entire rendered image tag. If the URL attribute is given a value beginning with "abs" (e.g., "url=absolute"), the returned URL is a fully qualified http URL (e.g., "http://www.yoursite.com/img/image1.gif"); otherwise, it is relative to the page currently being rendered (e.g., "../img/image1.gif").

The glue routine htmlImage.Url() adds this attribute for you.

Examples:

htmlImage.ImgRef("image1","url") or
htmlImage.Url("image1") returns the string
../img/image1.gif

htmlImage.ImgRef("image1","url=abs") or
htmlImage.Url("image1","abs") returns the string

http://www.yoursite.com/img/image1.gif

Image Maps

Server-Side Image Maps With ISMAP and LINKTO

To use a server-side image map, include the ISMAP (flag, or no-valued) and LINKTO attributes in the override parameter. The value of LINKTO may be either a literal string or an expansion tag, as described above.

To use a server-side image map by default, define ismap=true and set the linkto parameter in the image data table's imageTable subtable. You can still suppress the use of the image map by including "usemap=false" in the override parameter.

Client-Side Image Maps With USEMAP (first version)

The USEMAP attribute can appear in one of two ways. The first is as a valued parameter, where the value is the name of the map to use. Used this way, it looks much as it will in the rendered image tag. The value may be either a literal string or an expansion tag.

Client-Side Image Maps With USEMAP (second version)

The second form of the USEMAP attribute is as a flag (a non-valued parameter). The flag form will be recognized only if the corresponding image entry is an image info table, and the image info table contains an item named "map". In this case, the image info table's map cell will be copied to the table html.data.page.imageMaps, which will be created as necessary.

In your finalFilter, add the line htmlImage.filter.InsertClientSideMaps( @html.data.page.renderedText ). This script will insert the image map text from all items in html.data.page.imageMaps just after the opening body tag (<body>).

Notes:
The map text stored in the image data table should not contain the opening and closing tags (<map...> and </map>).

To automatically use the image map whenever the image is used, make sure the map entry appears in the image data table, and set usemap to true in the image data table's imageTable subtable (create it if necessary). You can still suppress the use of the image map by including "usemap=false" in the override parameter.

Combining Client-Side and Server-Side Image Maps

The attributes for client- and server-side image maps may be combined. This allows the browser to choose which method to use, and improves compatibility with older browsers. (In general, if a browser supports client-side image maps, it will use the client-side map.)


8. Virtual Attributes

The htmlImage suite recognizes several "virtual attributes" that never appear in the rendered image tag. Virtual attributes are passed to the htmlImage routines in the same way as normal image tag attributes such as width and border. However, they are used to pass values to the htmlImage scripts, and are omitted from the rendered image tag.

Most virtual attributes are processed by "filter" routines that are run before, during, and after the image tag is rendered. These filter routines are stored in subtables of user.htmlImage.virtual. Each subtable contains two entries:

    processWhen specifies when the filter script should be run:
    "pre":
    Run the filter script after parsing the htmlImage input parameters into html.data.page.
    Used for attributes such as "style" that must be resolved prior to working with attributes.

    "mid":
    Run the filter script after all processing except final rendering of the image tag.
    Used for attributes such as "alt" that have default behavior if not otherwise defined.

    "post":
    Run the filter script after final rendering of the image tag.
    Used for attributes such as "linkto", "prefix", and "suffix" that add additional information before and/or after the rendered image tag.

    process is the actual filter script.

user.htmlImage.virtual.["! Read Me"] summarizes the environment available to each type of filter defined in user.htmlImage.virtual.

In addition to the filter routines, user.htmlImage.virtual.attributes lists the attributes that are to be omitted from the rendered image tag.

Filters can be defined in user.htmlImage.virtual for attributes that are included in the rendered image tag. In this case, simply do not add the attribute to user.htmlImage.virtual.attributes. The "alt" attribute is handled this way; a filter is defined with processWhen="mid" to provide a default value for the "alt" attribute if necessary.

Additional virtual attributes can be defined. Use the existing filters, the foregoing description, and user.htmlImage.virtual.["! Read Me"] as guides.


9. Image Styles

The htmlImage suite provides a mechanism for defining image styles. An image style is a named set of attributes and their values that results in a desired image tag being generated with minimal effort on the part of the user.

An image style is defined by a subtable of user.htmlImage.style. The subtable contains string entries whose name is the name of an image tag attribute (or a "virtual attribute") and whose value is the default value of that attribute for any image that is rendered using the named style.

The style name is the subtable name.


10. Menu Options

Read Me

Pretty obvious, I think.

Add Image

Link (Alias)

Adds a file alias image entry to the current #images table.

Binary (Import)

Adds a binary image entry to the current #images table.

Table

Adds a data table image entry to the current #images table.

Add Folder of Images

Links (Alias)

Adds file alias image entries to the current #images table for all recognized image types in a selected folder.

Binary (Import)

Adds binary image entries to the current #images table for all recognized image types in a selected folder.

Table

Adds data table image entries to the current #images table for all recognized image types in a selected folder.

Replace With

Link (Alias)

Replaces the currently-selected image entry in an image table with a file alias image entry.

Binary (Import)

Replaces the currently-selected image entry in an image table with a binary image entry.

Table

Replaces the currently-selected image entry in an image table with a data table image entry.

Load Binary

Loads the binary data for the currently-selected data table image entry into the data table. Does nothing if the currently-selected image entry is not a data table entry.

Remove Binary

Removes the binary data for the currently-selected data table image entry from the data table. Does nothing if the currently-selected image entry is not a data table entry.

Check Aliases

Tests to make sure that all aliases/filespecs in the current #image table are valid. Both file alias image entries and the path cell of data table entries are checked.

Update

Update the currently-selected data table image entry to match the assocated external file. Does nothing for binary and file alias entries.

#images Table

These menu options apply to an entire #images table. The #images table must be open, and must be the topmost window.

Createü¿à

Create an #images table in the current table.

Update Entriesü¡à

Update each item in the currently-selected #images table.

Convert Aliases-->Tablesüø[sgl dagger]

Converts all alias entries in the #images table to image data tables. Ignores other image entry types.

Load Binariesü¬[florin]

Loads the binary image into every image data table in the the #images table. Ignores other image entry types.

Remove Binariesüø®

Removes the binary image from every image data table in the the #images table. Ignores other image entry types.

Site Image Glossary

Clearü¿[apple]

Clears all entries from the site image glossary. Creates the glossary (#imageGlossary) if it does not already exist.

Updateü¡

Scan the entire site hierarchy in the ODB and create an entry in the site image glossary for every image in every #images table in the site. Logs any glossary name collisions. Creates the glossary (#imageGlossary) if it does not already exist. (Entries are also created on-the-fly as images are referenced, but) without glossary name collision logging.)

Set #imageBase

Create or change the #imageBase directive in the current table.

Set #imageLoc

Create or change the #imageLoc directive in the current table.

Add Style

Create a new named image style.

Edit Styles

Open the user.htmlImage.style table for editing.

Initialize Suite

Initializes user.htmlImage for use by the htmlImage suite (executes htmlImage.Init()).


11. Glue Scripts

Forwarding scripts for most of these glue scripts are installed in user.html.macros by htmlImage.Init().

LinkToImage

Installed automatically in user.html.macros.

Links a text anchor to an image. (I.e., click on the hot-linked text to view the image.) Does not insert an inline image.

Syntax: linkToImage( <image name>, <link text> )

Url

Installed automatically in user.html.macros.

Provides a simpler syntax to get just the (local) URL of an image. Instead of the macro {htmlImage.ImgRef( imageName, "URL" )}, you can use {Url( imageName )}.

imageRef

Installed automatically in user.html.macros.

Duplicates the functionality of html.data.standardMacros.imageRef().

image

Installed automatically in user.html.macros.

Duplicates the functionality of the old htmlImage.image(); actually delegates all work to htmlImage.ImgRef().

You should remove all references to htmlImage.image() as you edit your source files, but you needn't edit them just for that purpose.

A set of conversion scripts is provided at htmlImage.conversions.ImageToImgRef.

Ref

Not installed automatically in user.html.macros. To install, copy script from htmlImage.glue.Ref and paste it into user.html.macros.

Duplicates the functionality of the old htmlImage.Ref(); actually delegates all work to htmlImage.ImgRef(). The only difference between ImgRef() and Ref() is the name; Ref() was too non-specific, and sometimes caused script-name collisions.

You should remove all references to htmlImage.Ref() as you edit your source files, but you needn't edit them just for that purpose.

A set of conversion scripts is provided at htmlImage.conversions.ImageToImgRef.


12. PageFilter/FinalFilter Scripts

Add even more functionality by calling these scripts from your pagefilter script.

InsertClientSideMaps

Full name: htmlImage.filter.InsertClientSideMaps
Call from finalfilter script Example: htmlImage.filter.InsertClientSideMaps( @html.data.page.renderedtext )

The virtual-attribute processing for the USEMAP tag copies image map text from the image data table entry to html.data.page.imageMaps.

Call InsertImageMaps() from your finalfilter() script to automatically insert the image maps into the rendered page text, just after the <body> tag.

ProcessSubstMacros

Full name: htmlImage.filter.ProcessSubstMacros
Call from pagefilter script Example:
htmlImage.filter.ProcessSubstMacros( @html.data.page.bodytext )

Warning: Experimental script! Please let me know if you use it, and whether you like it, hate it, or have an idea to improve it.

Processes image substitution macros of the forms

[[imagetag]] Equivalent to {htmlImage.Ref("imagetag")}.

[[imagetag,imagestyle]] Equivalent to {htmlImage.Ref("imagetag","style=imagestyle")}.

Of course, since you can give an image entry any name (tag) you want, this would allow you to type something like [[A photo of Niagra Falls]] in your source file, if you wanted.

May interfere with more generalized substitution macro processing. May change in the future.

ResolveBackground

Full name: htmlImage.filter.ResolveBackground
Call from pagefilter script Example:
htmlImage.filter.ResolveBackground()

Set #background to the name of the image you want to use as the background.

Looks up html.data.page.background value in image hierarchy and sets html.data.page.background to proper relative URL of image.

Allows #background to be specified as an image identifier, rather than a full URL.

Allows suppression of inherited background image using #background = "" (empty string). In this case, ResolveBackground() deletes html.data.page.background so it isn't included in <body> tag.

If html.data.page.background value is not an image identifier, doesn't change it (allows use of full URL, as before).


13. Usage Examples

Note: As of version 2.05 of htmlImage, htmlImage.image() and htmlImage.Ref() are deprecated.

They continue to be available as a glue routine for backward compatibility, but introduce additional overhead.

Simplest usage of core routine:

ImgRef("sitescriptedwithfrontier")
"<img src="../media/sitescriptedwithfrontier.gif" border="0" height="38" width="150">"

Setting ALT text

ImgRef("sitescriptedwithfrontier", "alt="Scripted with Frontier"")
ImgRef("sitescriptedwithfrontier", "alt="Scripted with Frontier"")
"<img src="../media/sitescriptedwithfrontier.gif" border="0" alt="Scripted with Frontier" height="38" width="150">"

Overriding image default style:

Using generic routine:

ImgRef("thistle_icon", "style=icon")
"<img src="../media/thistle_icon.gif" border="0" height="32" width="32" align="middle">"

ImgRef("hqx_picon", "style=picon")
"<img src="../media/hqx_picon.gif" border="0" height="12" align="top">"

Using style-specific routines:

icon("thistle_icon")
"<img src="../media/thistle_icon.gif" border="0" height="32" width="32" align="middle">"

picon("hqx_picon")
"<img src="../media/hqx_picon.gif" border="0" height="12" align="top">"

figure("cardFig1")
"<p><img src="../media/cardFig1.gif" border="0" align="center" prefix="<p>" suffix="<br clear=all>" height="192" width="168"><br clear=all>"

bullet("diamond_blt")
"<img src="../media/diamond_blt.gif" border="0" height="16" width="16" vspace="1" align="bottom">"

Drop-Caps

dropcap("A")
"<img src="../media/drop_a.gif" align="left" alt="A" height="32" width="32">"

dropcap("A", "script")
"<img src="../media/script_a.gif" align="left" alt="A" height="32" width="32">"

Adding LOWSRC attribute:

ImgRef("myBigImage", "lowsrc=[[myReducedImage]]")
"<img src="../media/myBigImage.gif" border="0" lowsrc="../media/myReducedImage.gif" height="50" width="69">"

Adding NAME attribute (for you JavaScript folks):

ImgRef("myBigImage", "name=george")
"<img src="../media/myBigImage.gif" border="0" name="george" height="50" width="69">"

Linking image to another URL (hot link):

ImgRef("myreducedimage", "linkto="../media/myreducedimage.gif"")
ImgRef("myreducedimage", "", "linkto=[[mybigimage]]")
"<a href="../media/mybigimage.gif"><img src="../media/myreducedimage.gif" border="0" height="50" width="69"></a>"

ImgRef("sitescriptedwithfrontier", "linkto="http://www.scripting.com/frontier"")
ImgRef("sitescriptedwithfrontier", "linkto=[[frontier URL]]")
"<a href="http://www.scripting.com/frontier"><img src="../media/sitescriptedwithfrontier.gif" border="0" height="38" width="150"></a>"

ImgRef("sitescriptedwithfrontier", "linkto=[[frontier URL]] alt="Scripted with Frontier"")
"<a href="http://www.scripting.com/frontier"><img src="../media/sitescriptedwithfrontier.gif" border="0" alt="Scripted with Frontier" height="38" width="150"></a>"

Using client-side image map

ImgRef("navbar","usemap="#navbar_map"") ImgRef("navbar") -- Assumes map is defined and enabled in image data table. See the Attributes section "<img src="http://../media/navbar.gif" usemap="navbar_map">

Using server-side image map

ImgRef("navbar","ismap="http://path_to_my_map/navbar_map.map"") ImgRef("navbar") -- Assumes ISMAP is defined and set to TRUE in image data table. See the Attributes section "<a href="http://path_to_my_map/navbar_map.map"><img src="http://../media/navbar.gif"></a>

Getting just the URL of an image

ImgRef("image1","url") or Url("image1") returns the string ../img/image1.gif

ImgRef("image1","url=abs") or Url("image1","abs") returns the string http://www.yoursite.com/img/image1.gif


14. Site Image Glossary

The site image glossary is a site-specific glossary used by htmlImage to look up images anywhere in the site hierarchy.

Why is an Image Glossary Needed?

If you keep all your images in a single #images table at the root of your site, you don't need a site image glossary. (Or, more accurately, you already have one, and shouldn't waste the CPU and user time maintaining one.) If you keep images at various levels in your site hierarchy, though, a site image glossary will allow you to refer to images in one portion of your site that are actually stored in a different portion of the site.

An Example Site...

yoursite [table]
#imageBase = "img" << Could be any name you want.
#imageLoc = "local"
#images [table]
default
site file 1
students [table]
#images [table]
user_joe [image entry] (user_joe.gif)
user_sue [image entry] (user_sue.jpg)

joe
sue

associates [table]
#images [table]
boss_fred [image entry] (boss_fred.gif)
worker_bee [image entry] (worker_bee.jpg)

fred
bee

In this example site table, without a site image glossary, a macro {htmlImage.imgRef("user_joe")} from yoursite.associates.fred cannot be resolved, and is replaced in the rendered file by a macro error block.

WIth a site image glossary, on the other hand, this reference can be properly resolved.

Automatic Generation of Image Glossary Entries

By default, the site image glossary is automatically generated as images are referenced, and used to look up images outside the immediate hierarchy in which an image reference appears. To suppress automatic generation and use of the site image glossary, define the #noSiteImageGlossary directive in your site table.

Entries are automatically added to the site image glossary only when images are located in the site image hierarchy as a result of an htmlImage macro call in a rendered page.

Manual Population of the Image Glossary

To compile a complete site image glossary quickly and easily, select Site Image Glossary->Update from the #images menu. The site image glossary will be created or cleared, as necessary, and entries will be made in the glossary for all image entries in all #images tables in the site hierarchy.

Clearing the Site Image Glossary

Select Site Image Glossary->Clear from the #images menu to clear the site image glossary.

The Image Rendering Process With the Site Image Glossary

Directive #noSiteImageGlossary not defined.

First, the site image hierarchy is searched for the image identifier. If the identifier is found in the image hierarchy, it is added to the site image glossary, and the image tag is rendered and returned.

If the image identifier is not found in the image hierarchy, the site image glossary is searched for the identifier. If the identifier is found in the glossary, htmlImage verifies that the image still exists at the location specified by the glossary. If it does, the image tag is rendered and returned; if it doesn't, a scriptError is posted.

The Image Rendering Process Without the Site Image Glossary

Directive #noSiteImageGlossary defined.

The site image hierarchy is searched for the image identifier. If the identifier is found in the image hierarchy, it is the image tag is rendered and returned.

If the image identifier is not found in the image hierarchy, a scriptError is posted.


15. Troubleshooting

Frontier crashes when I call htmlImage.ImgRef() with an override parameter

If you have not updated the regex suite since installing Frontier 4.2.3, you should do so. Michael Janneck, who uncovered this one, reports that the problem vanished after he installed version 1.1.2b5 of the
regex suite; that's also the version I had installed when I tested htmlImage v. 2.0x.


16. Conversion Scripts

I have provided a set of conversion scripts, in the table htmlImage.conversions.

See the "_READ ME!" entry in the individual conversion table for instructions.


Release Notes

Copyright © 1998, 1999 by Samuel Reynolds. All rights reserved. Last modified 1999/02/16.
Built with Frontier v.6.0 on Macintosh OS 8.1 on 1999/05/23.