ODB name:suites.randomizer
Version:1.2.1
Version Date:1998/08/11
Compatibility: F4.2.3 - F5.0.1 - F5.0.2b - F5.1+ - F6.0
Download: MacOS: Frontier 5 (24 kb)
Windows: Frontier 5 (16 kb)
MacOS: Frontier 4.2.3 (20 kb)
Release notes

About Randomizer

This suite provides a utility for randomly selecting an item from a table and rendering it (presumably as text -- especially html -- although other formats are possible).

NOTE: The BlipBlapBleep *script* works fine with both Frontier 4 and Frontier 5, but the BlipBlapBleep *CGI* has not been updated for Frontier 5, and so currently works only with Frontier 4.

Compatibility

This suite works in Frontier 4.2.3 on MacOS, and in Frontier 5.0.1 and later on both MacOS and Windows.

Copyright and Permissions

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 suite, please contact the author at <reynol@primenet.com>;

Installing Randomizer

To install randomizer, simply double-click on the "pony" file, and click on the Okay button when Frontier asks where to install the suite. No initialization is required.

If you are replacing an earlier version of Randomizer, delete user.randomizer. If you have added your own data tables and/or renderers to user.randomizer, only delete user.randomizer.default, as it is no longer used.

To remove Randomizer, delete suites.randomizer.

Using Randomizer

The access point for randomizer is randomizer.select():

Syntax:
randomizer.select( dataTableAdr, renderScriptAdr )

Parameters:
dataTableAdr
[REQUIRED] The address of the data table from which an item should be selected at random.

The data table contains a number of items from which randomizer.select() can select. These items can be of any data type, but all items of a given data set will typically be of the same data type.

renderScriptAdr
[OPTIONAL] The address of the script to be called to render item selected from data table.

If not specified, renderScriptAdr defaults to a script named render in the table that contains the data table (i.e., @parentOf(dataTableAdr^)^.render). If this default render script is not found, a scriptError is thrown.

Randomizer.select() selects one item the specified data table and renders it with the specified render script, if provided, or with the default render script.

Because the data table and render script are provided to randomizer.select() by the caller, they may reside anywhere in the ODB.

To reiterate: If you use the full syntax (passing the addresses of both the data table and the render script):

    o The data table may be located anywhere in the ODB. o The data table may have any name. o The render script may be located anywhere in the ODB. o The render script may have any name.

If you omit the renderScriptAdr parameter, you must provide a render script named "render" in the table that contains the data table:

[some table]
[data table]
render()
[some table] may be any table, anywhere in the ODB. [data table] may have any name, since its address is passed to randomizer.select(). The render script must be named render.

The Render Script

The render script must be of the following form:

render( odbAdr )
odbAdr is the address of an item in the ODB.

The render script should "render" the item at odbAdr^.

What Do You Mean by "Render"?
What "render" means will depend on the application. For example, in the BlipBlapBleep example (randomizer.examples.BlipBlapBleep), the data table contains strings, and the render script simply returns the string value stored at odbAdr^.

In other applications, the render script might do additional processing, and might return text, or another ODB address, or the contents of a file, or anything that can be passed as a return value in Frontier.

This approach may seem a bit confusing at first because it refers to nearly everything indirectly (through addresses). As a result, this description cannot describe the render script as "returning a string" (although for the most common uses, it probably will).

For example, a CGI for use with SSI (server-side includes) might use a table containing logical names of images in a website, and call randomizer.select() to choose a random image to be included in a page each time that page is sent to a browser. The render script would call the HtmlImage Suite to get a full image tag. Banner images could be handled similarly.

Randomizing Heterogenous Data

To randomize heterogenous data, I can think of three simple approaches off-hand:

    o You can use multiple data tables, with one table randomized and the others located relative to the passed table address by the render script.

    o You can use multiple data tables, with separate render scripts for the various tables.

    o You can use a render script that distinguishes between the data types of the entries in the data table, and either processes them separately or calls other render routines to process them.

Examples

Multiple Renderers

Location: suites.randomizer.examples.multipleRenderers

This example demonstrates the use of multiple renderers from a single script. The renderers may be either sub-scripts within a script, or other scripts within the ODB.

Aphorism Generator

Location: suites.randomizer.examples.BlipBlapBleep

This aphorism generator is called BlipBlapBleep. It gets its name from the structure of aphorisms: blip is the blap of bleep. It actually calls randomizer.select() three times, once for each of the three main words or phrases. To use it, execute the script randomizer.examples.BlipBlapBleep.Install(). This will copy the aphorism data set to user.randomizer. The generator script is suites.randomizer.examples.BlipBlapBleep.BlipBlapBleep().

To de-install the BlipBlapBleep example, execute the script randomizer.examples.BlipBlapBleep.Remove(). This script removes user.randomizer.BlipBlapBleep, and optionally removes user.randomizer. It also removes webServerScripts.BlipBlapBleep if it has been installed.

To use this example as a CGI, execute the script examples.BlipBlapBleep.InstallCGI(). This script will initialize user.randomizer, user.randomizer.default, and user.randomizer.BlipBlapBleep, and will install the CGI script webServerScripts.BlipBlapBleep (copied from randomizer.examples.BlipBlapBleep.CGI). Do not move or remove randomizer.examples.BlipBlapBleep if using the CGI; it calls randomizer.examples.BlipBlapBleep.BlipBlapBleep().

To de-install the BlipBlapBleep CGI, execute the script suites.randomizer.examples.BlipBlapBleep.RemoveCGI(). This script does not remove user.randomizer.BlipBlapBleep.

The CGI determines (from data provided by the server) whether it is being called directly or is being inserted in another page through a server-side include mechanism. If called directly, it will build a full html page, using a template, that includes the generated aphorism. If included in another page, it will return only the aphorism. You can, of course, modify the template (or the CGI itself, for that matter).

The BlipBlapBleep data set actually has three separate data tables, called word1, word2, and word3. All three tables contain strings, and are rendered by the same render script. In this case, all the render script does is return the string at the address it is given. The html template (for use by the CGI) and a script for adding new words to the tables are also stored in the data set table. The full data set for BlipBlapBleep looks like:

    BlipBlapBleep
        AddWords        [script]
        htmlTemplate    [wptext]
        render          [script]
        word1           [table]
        word2           [table]
        word3           [table]

The words or phrases in the three data tables are taken from traditional or humorous aphorisms. However, since the aphorisms are randomly generated, some very strange juxtapositions can occur.

You can add additional words to the data tables by executing user.randomizer.BlipBlapBleep.AddWords(). (You could also, of course, add them manually.)


Release Notes

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