---

1. The htmlImage Suite

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

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.

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:

What Is An Image Table?

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:

Image Table Entries

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

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.

Image placement in rendered site

The #imageBase Directive

The #imageLoc Directive

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

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.

If the alt text attribute is not otherwise defined:

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

See Site Image Glossary for more information.

imgAttribsMustExpand

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).

Attribute Override Priority

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

• 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

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 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

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

Examples:

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

URL

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

Examples:

../img/image1.gif

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

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.

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.

Read Me

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

Remove Binary

Check Aliases

Update

#images Table

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

Set #imageLoc

Add Style

Edit Styles

Initialize Suite

---

11. Glue Scripts

LinkToImage

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

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

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

image

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

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.

InsertClientSideMaps

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

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

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).

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

Simplest usage of core routine:

ImgRef("sitescriptedwithfrontier")

Setting ALT text

ImgRef("sitescriptedwithfrontier", "alt="Scripted with Frontier"")

ImgRef("sitescriptedwithfrontier", "alt="Scripted with Frontier"")

Overriding image default style:

Using generic routine:

ImgRef("thistle_icon", "style=icon")

ImgRef("hqx_picon", "style=picon")

Using style-specific routines:

icon("thistle_icon")

picon("hqx_picon")

figure("cardFig1")

bullet("diamond_blt")

Drop-Caps

dropcap("A")

dropcap("A", "script")

Adding LOWSRC attribute:

ImgRef("myBigImage", "lowsrc=[[myReducedImage]]")

Adding NAME attribute (for you JavaScript folks):

ImgRef("myBigImage", "name=george")

Linking image to another URL (hot link):

ImgRef("myreducedimage", "linkto="../media/myreducedimage.gif"")

ImgRef("myreducedimage", "", "linkto=[[mybigimage]]")

Why is an Image Glossary Needed?

An Example Site...

#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

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

Clearing the Site Image Glossary

The Image Rendering Process With the Site Image Glossary

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

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.

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

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