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 and create links to images (in the form of aliases) through the table. See the #image->Documentation->Tools submenu for more information on the image management tools.

HtmlImage 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->Documentation->Image Styles for information on working with image styles.

NOTE: For Frontier 4.2.3, you need the older version of HtmlImage, available at http://www.spinwardstars.com/frontier/f4/.

---

Dependencies

In order to do its magic, htmlImage requires the regex extension, version 2.0b8 or later, available from http://www.scriptmeridian.org/projects/regex.

HtmlImage uses the fileWriters abstraction mechanism if it is available. If you're using Windows and want to render directly to a remote (FTP) site, you will need Alan German's fileWriter.ftp, which is available from http://www.erols.com/asg/user/html/fileWriters/ftp.html. Alan's fileWriter.ftp uses Frontier's built-in TCP capability on both the Mac and Windows, so if you use it on Mac you won't need an external FTP program on the Mac to allow render-to-remote.

---

Documentation

Documentation is available via the #Image->Documentation submenu.

---

Release Notes

• v. 3.0b9 - 16 July 1999
• Now works properly if installed in GDB instead of in root.suites table. However, it won't appear in the suite menu :-(
• Now works properly in mainResponder sites!
• Added utilities.IsInMainResponder(): returns TRUE if rendering in mainResponder context.
• DestFileName honors imageExtensions preference.
• And if rendering in mainResponder context:
• hi_imageBase is forced to "images" and hi_imageLoc is forced to "local". This gives the expected behavior in mainReponder sites. So don't bother defining these two values in a mainResponder site--they'll be ignored.
• PrepareImageFile doesn't save image file to disk.
• ImageFolder extends path to image data table element (path or binary).
• glossary.Update: Default current location by calling table.getCursorAddress instead of window.frontMost.
• v. 3.0b8 - 20 May 1999
• Modified Init() script to properly update user.htmlImage.virtual.linkto and user.htmlImage.virtual.attributes (did not in 3.0b7).
• TO UPDATE:
• If you haven't customized user.htmlImage.virtual, delete user.htmlImage.virtual.
• If you *have* customized user.htmlImage.virtual, delete user.htmlImage.virtual.linkto and user.htmlImage.virtual.attributes.
• Run the htmlImage.Init script.
• Should now work properly with GDBs.
• Added utilities.GetSiteTable: searches up from start address for #ftpsite, and returns address of containing table. Throws scriptError is #ftpsite is not found.
• Added utilities.IsInAnyWebsite: searches up from start address for #ftpsite; returns address of #ftpsite is found, or false if #ftpsite is not found.
• Changed glossary.GetGlossaryAdr to use utilities.GetSiteTable. Now works properly in GDBs.
• Changed glossary.Update to default currentLoc to table.getCursorAddress().
• v. 3.0b7 - 22 March 1999
• Will use old export/copy method if html.writeFile is not available.
• When using html.writeFile, if ftpSite^.method = "file" and the binary has not been loaded, call file.copy instead of html.writeFile.
• Should provide better performance for local builds.
• Eliminates the load-to-memory/write-to-file cycle required with html.writeFile.
• Added support for OnMouseOver & OnMouseOut attributes (processed by virtual.linkto.process script)
• TO UPDATE: Delete user.htmlImage.virtual.linkto and user.htmlImage.virtual.attributes, then run htmlImage.Init script.
• v. 3.0b6 - 8 March 1999
• In utilities.findImage, allow inImageKey to be an address.
• Updated imageRef glue script to provide the same interface as the script it replaces.
• Init script now asks whether to install the imageRef glue script, and warns that it will affect all websites.
• If user says no, it writes a note to the log describing how to use it for a single site.
• And finally--It now calls html.writeFile (to use filewriters) instead of writeWholeFile.
• v. 3.0b5 - 4 Sept 1998
• Added new directives (preferences) for table management
• hi_entryType, hi_autoLoadBinary, hi_autoUpdateBinary
• Finished reworking Image Table management tools.
• Add Image and Add Folder of Images use directives to determine what kind of entry to create.
• Submenu for each action is no longer needed.
• Update Selection and Check Aliases figure out whether they are working on entry or table.
• Finished reworking online documentation.
• Online documentation under Documentation submenu.
• Finished reworking menu.
• Muchly simplified menu layout.
• Now use Add File instead of Add File->[entry type] submenu.
• Now use Add Folder of Files instead of Add Folder of Files->[entry type] submenu.
• Initialization, creation of #images tables, and directive definition (new) moved to Setup submenu.
• v. 3.0b4 - 30 July 1998
• Added 'JPG ' and 'GIF ' to recognized file types (for Adding images on Windows).
• Upcase file type when checking whether to Add files.
• Fixed bug in PrepareImageFile that kept it from replacing image files even if they were outdated.
• Added optional startAdr and termAdr parameters to imgRef().
• Passed through to utilities.findImage() to allow search to start at location other than pageTbl^.adrobject.
• Made utilities.findImage() smarter about startAdr (inObjAdr) parameter.
• Now checks for existence.
• If doesn't exist, try to find it as sub-addr within pageTbl^.adrSiteRootTable.
• If still not found, throws scriptError()
• Made utilities.findImage() smarter about terminalAdr (inAdrTerm) parameter.
• Now verifies that startAdr is inside terminalAdr.
• If not, throws scriptError()
• v. 3.0b3 - 22 June 1998
• Replaced a call to toys.readWholeFile() with htmlImage.compat.readWholeFile() [oops!].
• Added filespecType to case statement in utilities.SiteFolder().
• v. 3.0b2 - 24 April 1998
• Fixed typo in htmlImage.compat.writeWholeFile.
• Was calling toys.writeWholeFile/file.writeWholeFile with inBinData repeated in binary-type parameter.
• v. 3.0b1 - 12 April 1998
• First Frontier 5-compatible release.
• No new functionality--just a port to F5.
• Created new compatibility scripts (in htmlImage.compat) so correct calls are made for F4 and F5.
• Haven't tested on F4, however--haven't figured out how to transfer it from F5 to F4.
• Changed directive/preference names to use hi_xxxx naming convention.
• Old names are no longer supported!
• Now uses standard html.getPrefs() mechanism to get directives/preferences.
• Calls html.getPrefs() to look for hi_xxxx directives/prefs.
• Also looks in website table (F4/F5), or in "prefs" or "#prefs" subtable of website table (F5 only).
• Directives can reside either in the site table (using #name notation) or inside #prefs table in site table.
• Name changes:
• autoGenAltText --> hi_autoAltText
• imageBase --> hi_imageBase
• imageLoc --> hi_imageLoc
• noSiteImageGlossary --> hi_genSiteGlossary -- NOTE: LOGIC IS REVERSED!
• To suppress site image glossary generation, set #hi_genSiteGlossary = false.
• To allow site image glossary generation, set #hi_genSiteGlossary = true or omit it (defaults to true).
• imgAttribsMustExpand --> hi_attribsMustExpand
• background --> hi_background
• Required because Frontier 5 hard-codes a call to html.data.standardMacros.bgImageRef when the #background directive appears.
• If you use the ResolveBackground filter script, the image specified by hi_background becomes your page background, and background is ignored.
• v. 2.1 - 14 Nov 1997
• Added support for nested subtables within the #images table.
• Subtable names begin with "$".
• Items from subtables are rendered into subfolders of the image folder.
• Image folder placement still controlled by #imageLoc and #imageBase. Subfolders then appear within the image folder.
• Image subfolders can appear within global, local, or hierarchical image folders.
• v. 2.08 - 21 Aug 1997
• BUG FIX: The Init() script called log.clear() from my customized log suite; this script is not in the Frontier distribution. FIXED.
• v. 2.07 - 19 Aug 1997
• CHANGES
• BUG FIX: Some glue scripts still referred to htmlImage.Ref(). Now call htmlImage.ImgRef(). FIXED.
• htmlImage.Init (and Initialize Suite menu item) is now more careful when it updates the forwarding scripts in user.html.macro.
• Does not delete macros that have same name as obsolete htmlImage macro.
• Prompts user whether to replace macro if macro does not belong to htmlImage.
• Records & displays log of initialization activity.
• v. 2.06 - 14 Aug 1997
• CHANGES
• Restored htmlImage.linkToImage() script (moved from obsolete subtable to main table, added forwarding script to user.html.macros).
• Easily links text to non-inlined image.
• v. 2.05 - 13 Aug 1997
• CHANGES
• BUG FIX: Sometimes created bogus image file path (contained 2 consecutive colon chars "::"). FIXED.
• Bug was introduced in v. 2.04.
• BUG FIX: htmlImage.glossary.Update() was creating spurious #imageGlossary entries at all levels of the site. FIXED.
• NEW PAGEFILTER SCRIPT: htmlImage.filter.ResolveBackground()
• To use:
• Add the following line to your finalFilter:
• htmlImage.filter.ResolveBackground()
• Define #background equal to an image identifier, rather than a full URL.
• Looks up html.data.page.background value in image hierarchy.
• Sets html.data.page.background to proper relative URL of image.
• #background now can be specified as an image identifier, rather than a full URL.
• If html.data.page.background value is not an image identifier, doesn't change it (allows use of full URL, as before).
• Suppress inherited background image using #background = "" (empty string).
• ResolveBackground deletes html.data.page.background so it isn't included in <body> tag.
• v. 2.04 - 27 Jul 1997
• CHANGES
• Added site image glossary to resolve image tags from parallel paths in the image hierarchy.
• Unimportant if using #imageLoc="global"; in this case, define #hi_suppressSiteGlossary to suppress glossary activity.
• Added "hier" option for #imageLoc directive.
• Creates single global image folder, with image directory hierarchy within the single folder.
• Image directory hierarchy mirrors site document hierarchy.
• Added new URL virtual attribute.
• Tells htmlImage to return only the URL, not a complete image tag.
• If the URL attribute begins with "abs" (e.g., "url=absolute"), returns full http URL; otherwise returns relative path.
• DOCS
• Added URLs to other add-on suites that htmlImage requires (regex, mediaInfo).
• v. 2.03 - 7 Jul 1997
• CHANGES
• htmlImage.filter.InsertClientSideMaps() now places client-side image maps just after <body> tag, instead of in before </head>.
• Rewrote htmlImage.filter.ProcessSubstMacros to use regex instead of string.replace (it's faster).
• htmlImage.filter.ProcessSubstMacros() now processes the target text in place. This requires a change of call if you are already using it.
• See section 12 (Filter Scripts) of the docs.
• DOCS
• Changes in sections 4 and 12.
• Note: To set default image style in image data table, the cell name is "style", not "styleBase". This was a documentation error.
• v. 2.02 - 3 Jul 1997
• CHANGES
• Bug fix in htmlImage.style.override()
• Was not recognizing "flag" (valueless) attributes such as ISMAP.
• Now correctly processes "flag" attributes. They become booleans with value=true in the html.data.page.imageStyleTable.
• Moved htmlImage.ProcessSubstMacros() to htmlImage.filter.ProcessSubstMacros().
• Added new final-filter script htmlImage.filter.InsertClientSideMaps().
• Menu: Fixed broken menu items.
• Menu: Added Convert Table menu items
• Convert aliases to image data tables
• Load binaries into image data tables
• Remove binaries from image data tables
• USEMAP: Added virtual-attribute processing to support client-side image maps
• In image data table:
• [image data table].map = image map
• [image data table].styleTable.usemap = true
• [image data table].map is copied to html.data.page.imageMaps.[image tag + "_map"]
• Use htmlImage.filter.InsertImageMaps() to add image maps to page automatically.
• In override parameter (1):
• [image data table].map = image map
• override parameter contains "usemap" or "usemap=true"
• [image data table].map is copied to html.data.page.imageMaps.[image tag + "_map"]
• Use htmlImage.filter.InsertImageMaps() to add image maps to page automatically.
• In override parameter (2):
• override parameter contains "usemap="#mapname""
• User must place image map in page.
• DOCS
• Added docs for using server-side (ISMAP+LINKTO) and client-side (USEMAP) image maps.
• Added docs for new menu items.
• v. 2.01 - 2 Jul 1997
• CHANGES
• Fixed "Read Me" and "Create #images Table" items in menu.
• DOCS
• Added section 14: Troubleshooting
• Make sure regex suite is up to date (1.1.2b5).
• v. 2.00b1 - 23 June 1997
• CHANGES
• MAJOR REWRITE!
• Major functionality, including ALTand HEIGHT/WIDTH defaulting, handled by filter processing.
• Styles can now be defaulted in either style table, or image data table (a new #image table entry type), or both.
• Full tool set (I think!) in menu for maintaining #images tables.
• htmlImage.image() is now obsolete; it is retained as glue, but I recommend switching to htmlImage.Ref() for efficiency.
• DOCS
• Completely rewritten for new release.
• v. 1.14 - 16 Jun 1997
• CHANGES
• Added support for mediaInfo-generated image info tables as entries in the #images table.
• New menu options for maintaining the #images table.
• #imageBase and #imageLoc may be defined in user.websites. This changes the default from ""/"global".
• Changed name of user.htmlImage.noShowAttributes to user.htmlImage.virtualAttributes.
• Definition: A virtual attribute is an attribute passed to the htmlImage routines that will not appear in the rendered IMG tag.
• Virtual attributes are intended as a way to pass additional information to the htmlImage routines using the same mechanism used for attributes.
• v. 1.13 - 13 Jun 1997
• CHANGES
• Added support for virtual attribute "style".
• Overrides style parameter to image().
• inType parameter to Image() is no longer needed. It is retained for backward compatibility.
• *** DELETE user.htmlImage.noShowAttributes AND RUN htmlImage.Init() to update ***
• Added htmlImage.Ref() script.
• Style and alt-text attributes folded into inOverride parameter.
• Simple glue script--calls htmlImage.image().
• Added support for autoGenAltText directive.
• autoGenAltText =
• "none": Do not automatically generate alt-text.
• "file": Generate alt-text = source file name (if any); equivalent to "none" for binary ODB entries.
• "tag": Generate alt-text = image tag (used to look up image) + " image".
• Defaults to "none".
• Added processSubstMacros() to process image substitution macros (EXPERIMENTAL!!!!)
• Finds and substitutes for:
• [[imagetag]]
• [[imagetag,imagestyle]]
• May interfere with more generalized substitution macro processing.
• Will probably change in the future.
• v. 1.12 - 12 Jun 1997
• CHANGES
• Added ability to select image placement in rendered site
• Global, global folder, local (each subfolder), or local subfolder.
• Placement depends on imageLoc and imageBase directives
• if imageLoc = "global" or imageLoc is not defined:
• If imageBase = "" or imageBase is undefined:
• placement is within site's root folder
• else
• placement is within image folder within site's root folder.
• if imageLoc = "local"
• If imageBase = "" or imageBase is undefined:
• placement is in the folder that corresponds to the image's location in the site hierarchy in the ODB
• else
• placement is in the folder that corresponds to the image's location in the site hierarchy in the ODB
• Default is global, to match previous behavior.
• v. 1.11 - 11 Jun 1997
• CHANGES
• Rewrote htmlImage.imgPrefs.override() (using regex) to provide more flexibility and capability.
• Attribute value can be bracketed by:
• Nothing at all (the only case previously supported):
• E.g., "border=0".
• Value after "=" is treated as literal string (as before).
• Value cannot contain whitespace (to contain whitespace, use quotes around value).
• Normal or curly double-quotes.
• E.g., "alt=\"What it is"" or "alt="What it is"".
• Value within quotes cannot contain closing delimiter. Value within quotes is treated as literal string.
• Recognition of two distinct sets of delimiters allows alternate delimiter to appear in literal string (e.g., "alt="John's \"hidden" tricks"").
• Double square brackets.
• E.g., "linkto=[[Where to go]]").
• Value within brackets will be expanded using glossary (if possible) or image URL (relative; uses standard #images search).
• Added htmlImage.imgPrefs.expandAttributes as helper to htmlImage.imgPrefs.override.
• Now supports additional "virtual attributes" in inOverride parameter:
• Added user.htmlImage.noShowAttributes list to suppress virtual attributes (so they never appear in generated tag).
• ** Mis-typed attributes *WILL* appear in generated tag! **
• Added support for "linkto" virtual attribute.
• Indicates that image is anchor for link to another URL.
• Value may be string literal (with or without quotes), or expansion specification, as described above.
• v. 1.10 - 10 Jun 1997
• CHANGES
• Changed initialization approach. Init() now looks in htmlImage.data.initItems for the items to copy to user.htmlImage.
• Now supports #imgPrefs table in website table, so each website or subsite can have its own distinctive preferences.
• ** SEARCH IS FULLY HIERARCHICAL!
• Searches up website hierarchy for "#imgPrefs" table containing specified preference entry.
• If not found, gets preference entry from user.htmlImage.imgPrefs.
• If *still* not found, calls scriptError().
• Split attribute text generation out from imgPrefs.getPrefs to create imgPrefs.attribsText.
• Supports a more flexible and extensible set of attributes.
• Case insensitive attribute names.
• Allows simple addition of new attributes to image tags, if they meet one of the following requirements:
• 1. "Specials": Attribute is flag (value is true or false), and is simply included or not (i.e., no "=value" in tag).
• 2. "Flags": Attribute may be include or not according to a simple logical comparison of its value.
• E.g., for width >= 0, the condition is ">=0".
• See specialAttributes, specialConditions, and flagAttributes in user.htmlImage.
• 3. General: Attribute is included only if it value is a non-empty string.
• New entries in user.htmlImage:
• user.htmlImage.specialAttributes:
• A list of attributes to be included or not included (if found in the prefs table) based on whether a simple condition on their value is met.
• Add to this list and to user.htmlImage.specialConditions for new "Special" attributes.
• Must have exactly the same number of items as specialConditions.
• Omitted if value is blank.
• user.htmlImage.specialConditions:
• A list of simple conditions corresponding to the attribute names in specialAttributes.
• Add to this list and to user.htmlImage.specialAttributes for new "Special" attributes.
• Must have exactly the same number of items as specialAttributes.
• user.htmlImage.flagAttributes:
• A list of attributes to be included *without value* or not included (if found in the prefs table) depending on whether their value is true or false.
• Add to this list for new "Flag" attributes.
• Omitted if value is blank.
• *** STILL DOES NOT AUTO-GENERATE ALT OR LOWSRC ATTRIBUTE!
• Updated docs to reflect changes.
• See especially:
• "Value Ranges and Suppressing Attributes" in section "2 Image Prefs".
• "utilities.FindHierarchical" in section "3 Major Functions".
• NOTE: #imagebase directive is *NOT* hierarchical. The most specific definition is used, just like other directives. (This was an error in previous docs.)
• v. 1.09 - 29 Apr 1997 by SCR
• CHANGES
• Added imagePath() script
• Returns the relative path from current page to image (not a tag, just the path).
• Minor docs changes
• v. 1.08 - 30 Mar 1997 by SCR
• CHANGES
• Added LinkToImage() macro script.
• Takes image short name and link text, returns hotlink html.
• v. 1.07 - 28 Mar 1997 by SCR
• DOCUMENTATION
• Revised to describe modified behavior.
• CHANGES
• Image() script
• Now adds image's actual height and width as tag attributes if neither attribute is specified by preference or override.
• Now always places quotation marks (") around tag attribute values. E.g., height="32" rather than height=32.
• v. 1.06 - 26 Mar 1997 by SCR
• DOCUMENTATION
• Added specific instructions for updating from previous versions. See "Installation" in "htmlImage.docs.1 Read Me".
• CHANGES
• Added UpdateImage() script
• Implementation for "Update" menu item (was do-nothing).
• Allows user to select image to replace current entry. Does not change entry name.
• If optional "withPrompt" parameter is false, only shows dialog if file is not found. Default = true.
• If selected item is a binary image (rather than a link), UpdateImage does nothing.
• Added UpdateImageTable() script and corresponding "Update #image Table" menu item.
• Calls UpdateImage(false) for each item in table.
• Init() script
• Does not require RegularExpression extension for initialization.
• Forwarding scripts are generated in advance by htmlImage.data.buildForwardingScripts. (It needs RX.)
• Init() copies forwarding scripts from htmlImage.data.forwardScripts to user.html.macros.
• Menu
• Update
• Now calls UpdateImage(). Previously did nothing.
• Update #image Table
• New item. Calls UpdateImageTable().
• v. 1.05 - 25 Mar 1997 by SCR
• BUG FIXES
• #image menu script for Edit Prefs
• Fix for 1.04 got lost in a crash (I think).
• CHANGES
• Init() script
• No longer adds an entry to system.misc.path. Instead, adds "forwarding" scripts to user.html.macros.
• Several people got on my case about adding to system.misc.path.
• However, I had to add a path for user.html.macros. I can't win, it seems.
• **NOW REQUIRES RegularExpression EXTENSION**
• v. 1.04 - 11 Mar 1997 SCR
• BUG FIXES
• _Thanks to Stefan Brantschen for the feedback._
• #image menu script for Edit Prefs
• was opening htmlImage.imgPrefs.prefs
• now opens user.htmlImage.imgPrefs as it should
• PrepareImageFile() script
• imgFolder now correctly set, so it should be correctly created if necessary
• Image() script
• Removed cross-dependency to unpublished scripts
• Changed image to use html.data.page.subdirectoryPath instead of html.data.page.pagePath.
• I keep my source text as external files, so I have a different build mechanism. It creates a pagePath entry in html.data.page.
• Init() script
• Now ensures an entry in system.misc.path.
• Looks for an existing entry before creating a new one.
• v. 1.03 - 26 Feb 1997 at 3:55:26 PM by SCR
• BUG FIXES
• Added ImportImageMult (omitted from earlier releases)
• _Thanks to Kenny Gatdula for letting me know._
• v. 1.02 - 25 Feb 1997 by SCR
• BUG FIXES
• Replaced utilities.RelativeUrl().
• Old version *usually* generated the correct relative URL.
• New version *always* does (as far as I can tell).
• Removed all references to htmlImage.Init() in code for efficiency.
• Users must execute Init() explicitly to install the user table.
• Added Installation section to the docs (section "1 readme").
• v. 1.01 - 24 Feb 1997
• Docs cleanup.
• v. 1.0 - 19 Feb 1997
• First public release.