htmlGallery Suite (F4)

ODB name:suites.htmlGallery
Version:1.2
Version Date:3 Dec 1997
Download: htmlgallery.hqx
Release notes.


Contents

1. Introduction
4. Directives

2. Copyright
5. Macros

3. Installation
 


The htmlGallery Suite

This suite provides tools for generating galleries of images within a website.

Dependencies

The htmlGallery requires my
htmlImage Suite and replacer Suite to function. Additional required suites are described in the documentation for these suites.


2. Copyright and Permissions

Created by Samuel Reynolds.
Copyright © 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 bug reports or suggestions for 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 htmlGallery suite, double-click on the suites.htmlGallery "pony" file. Open the suites.htmlGallery table in the ODB (or use the Quick Script window) and run suites.htmlGallery.Init(). This creates the user.htmlGallery table and its subitems. (If the table or any specific subitem already exists, it will not replace it.)


4. Directives

The #indexTemplate Directive

If defined, the contents of this directive will be used as the template for generated index text. If this directive is not defined, user.htmlGallery.templates.index will be used.

The #indexEntryTemplate Directive

If defined, the contents of this directive will be used as the template for each entry in the generated index text. If this directive is not defined, user.htmlGallery.templates.indexEntry will be used.

Directives Used By The Example (Default) Substitution Scripts

The following directives are used by the example/default processing. You may want to use these directives even if you modify or replace the substitution scripts.

The #displayPageAutoGen Directive

Type: Boolean
Default value: FALSE

If defined and equal to TRUE, the THUMB substitution script, which generates replacement text for the [THUMB] substitution tag in the index entry template, will generate page source for the target image at the location indicated by the #displayPageBase directive using the template defined by #displayPageTemplate (or by user.htmlGallery.templates.displayPage if #displayPageTemplate is not defined), and will return the URL of that page rather than the URL of the actual image file.

This allows you to display the images on the background and with the page appearance of your choice, simply by modifying the display page template.

The location of the rendered page sources is defined by #displayPageBase, and each generated page is given the same short name as the image being displayed.

Note: After building your indices using htmlGallery.Index(), you must build the autogenerated display page entries. They can be built in the same way as other pages built from the ODB.

The #displayPageBase Directive

Type: String
Default: "disp/"

Defines the URL of the autogenerated display pages relative to the location of the gallery image folder and the location of the autogenerated page sources in the ODB. The autogenerated page sources will be stored in a site subtable whose name is the same as the #displayPageBase directive (without the trailing '/' character) at the same level as the gallery image table.

Ignored if #displayPageAutoGen is false or is undefined.

The #displayPageTemplate Directive

Type: String, wpText, or outline
Default: user.htmlGallery.templates.displayPage

The template used to generate display page source text (not rendered html text!) in the ODB. This template may contain the same range of substitution tags as the default index entry template used by htmlGallery.Index().

Ignored if #displayPageAutoGen is false or is undefined.

The #thumbnailBorder Directive

Type: Integer
Default: 0 (zero)

This directive is used only by the THUMB substitution text generation script (user.htmlGallery.scripts.THUMB). It specifies the size (in pixels) of the border surrounding thumbnail images in the generated index.

The thumbnails act as buttons leading to the full-size images. Although I prefer no border (border=0) around pictures (hence the default), some people like a border. This allows a border to be easily added, removed, or adjusted.


5. Macros

Index

The Index() script builds a pictorial index of images from the first #images table found in the site hierarchy. It does not search hierarchically for images to include.

This #images table is referred to in this documentation as the "gallery #images table" or "gallery image table."

The Index() script uses two templates, one for the overall index and one for the index entries. Index() processes the index template directly, and calls replacer.Process() to process (fill in) the index entry template.

The Index Template

Index first looks for a template at html.data.page.indexTemplate. If it exists, it is used as the index template; if not, user.htmlGallery.templates.index is used. Therefore, user.htmlGallery.templates.index must be defined. This template is installed by the htmlGallery.Init() script if it does not already exist.

This mechanism allows each gallery table within a website to have a unique index template, if desired. Alternately, you can place a single #indexTemplate directive at an appropriate location within the site table hierarchy to be shared by multiple galleries.

It is recommended that if you define the #indexTemplate directive you also define the #indexEntryTemplate directive at the same location.

The index template may contain the following substitution tag:

[ENTRIES]
Replaced by the aggregate of all the generated index entries.

It may contain any other source or html text that you desire.

The Index Entry Template

Index first looks for a template at html.data.page.indexEntryTemplate. If it exists, it is used as the index template; if not, user.htmlGallery.templates.indexEntry is used. Therefore, user.htmlGallery.templates.indexEntry must be defined. This template is installed by the htmlGallery.Init() script if it does not already exist.

This mechanism allows each gallery table within a website to have a unique index entry template, if desired. Alternately, you can place a single #indexEntryTemplate directive at an appropriate location within the site table hierarchy to be shared by multiple galleries.

It is recommended that if you define the #indexEntryTemplate directive you also define the #indexTemplate directive at the same location.

The index entry template may contain any substitution tag you like, as long as it meets the requirements of the replacer suite. See the replacer Suite documentation for more information on substitution tags and replacement scripts.

If you use the default replacement scripts provided with the htmlGallery suite, the index entry template may contain the following substitution tag:

[COPYRIGHT]
Replaced by the notes.copyright field of the image record.

[MFG]
Replaced by the notes.mfg field of the image record.

[PAINTEDBY]
Replaced by the notes.paintedBy field of the image record.

[PARTNUMBER]
Replaced by the notes.partNumber field of the image record.

[SCALE]
Replaced by the notes.scale field of the image record.

[THUMB]
Replaced by a thumbnail image, if one is defined. If the image short name is "imgname", the THUMB replacement text generation script looks for an image named "imgnameThumb". If it finds the thumbnail image, it displays it; otherwise it displays the string "[IMAGE]". The thumbnail image or text is hot-linked to the full-sized image.

[TITLE]
Replaced by the notes.title field of the image record.

It may contain any other source or html text that you desire.

For an example of an image entry and templates using the default replacement scripts see htmlGallery.example.default.

Syntax

Index( inKey, inMatchAll )

Parameters

inKey
A string keyword or list of string keywords specifying which images to include in the index. Image table entries that have a entry named "inIndices" (a list) may be included in the generated index.

If inKey = "ALL" (or if a list, contains an item "ALL"), then all images in the gallery #images table will be included in the generated index, and the inMatchAll parameter will be ignored.

(b) the "inIndices" entry contains at least one of the string keywords in inKey will be included in the generated index text.

inMatchAll
Indicates whether to include only images that match all of the keywords in inKey.
If TRUE, only those images whose "inIndices" entry contains all of the keywords in inKey will be included in the generated index.
If FALSE, all images whose "inIndices" entry contains at least one of the keywords in inKey will be included in the generated index.
Default: FALSE

Examples

  • {htmlGallery.Index("fantasy")}
    Generates a list of all images from the gallery #images table that have an "inIndices" entry and where the "inIndices" list contains the keyword "fantasy".

  • {htmlGallery.Index({"grenadier","fantasy","25mm"})}
    Generates a list of all images from the gallery #images table that have an "inIndices" entry and where the "inIndices" list contains at least one of the specified keywords.

    The example keywords here are from my website, where this macro would generate an index to photographs of 25mm miniatures, fantasy miniatures, and miniatures manufactured by Grenadier. Items with more than one of these keywords would appear only once in the generated index.

  • {htmlGallery.Index({"grenadier","fantasy","25mm"}, TRUE)}
    Generates a list of all images from the gallery #images table that have an "inIndices" entry and where the "inIndices" list contains all of the specified keywords.

    The example keywords here are from my website, where this macro would generate an index to photographs of 25mm fantasy miniatures manufactured by Grenadier.


Release Notes

  • v. 1.2 - 3 Dec 1997
    • Modified to work with revised replacer Suite.
      • Removed htmlGallery.data.matchFields.
      • Renamed htmlGallery.data.tagForm to pattern.

    • Fixed bug in Index()
      • Was assigning return value of replacer.process() to entryText^.
        • Happened to work okay with suites.replacer v. 1.1, but breaks with suites.replacer v. 1.2.
        • Was unnecessary in any case, because replacer.process() makes substitutions in-place in target string.

  • v. 1.1 - 7 Oct 1997
    • Complete rework to use the replacer Suite.
    • The Gallery script is now thoroughly broken, and has been removed. It may return again at a later date.

  • v. 1.0 - 4 Sep 1997
    • First public release.

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.