Uncle Joe's Cookhouse!

Table of Contents:

• What is a Genpage recipe?
• Including recipes
• Using recipes
• Creating your own recipe
• Documenting recipes.
• Current contributed recipes

What is a Genpage recipe?

The core script of genpage is kept deliberately small, with just the most commonly required functionality built in. However, there is a great deal of scope for expanding this functionality to provide for your specific situation or some particular use.

The means to accomplish this is through extension modules named 'recipes' (after the 'Perl Cookbook')

Recipes are very simply straightforward perl scripts that are executed from within Genpage (as specified by you) and typically define a function or series of functions obscure enough not to be included by default in the core Genpage script.

Including recipes

To include a recipe into genpage for application against your content, you simply have to issue the call <!-- _GP_ recipe("recipefile") --> somewhere in the content or template files.

The recipefile parameter is either the full path to the recipe (Genpage variables like $root$ apply) or if you have placed the recipe somewhere in your perl include tree (somewhere in @INC basically) you can just specify the filename. (e.g. place the file in /usr/local/lib/site_perl)

The most common method is to have a directory under your genpage web generation tree and reference the recipe there.
e.g. place the file in a directory called 'include' under the root of your web site generation tree and call the recipe as <!-- _GP_ recipe("$root/include/somerecipe.gp") -->

Using recipes

To use a recipe, you must first include it, as described above, and then simply reference the functions or variables or whatever that the recipe defines.
e.g. <!-- _GP_ recipe("$root/include/myrecipe.gp") --> <!-- _GP_ myfunction_as_defined_in_myrecipe("foo") -->

Creating your own recipe

There are just a few simple rules to follow when creating your own recipes, but they should be adhered to to ensure that your recipe will continue to work with all versions of Genpage.

• The recipe() function is similar to the perl 'require' command and as such, your recipe must return a value at the end. By convention this value is <-- Genpage recipe recipe-name included -->
• The recipe should include a descriptive comment detailing Author, Date of last modification, and a brief description of it's function at the top of the file.
• If the recipe or anything defined therein modifies internal Genpage variables, they should return those variables to a clean state before exit. (To ensure you don't break something further on in the genpage processing)
• For inclusion in the distribution of genpage, a recipe must include a content file as described in the "Documenting recipes" section below.

That's all. Nice and simple :)))

Documenting recipes.

Should you decide to share your recipe with the world, and want to include it in the genpage distribution, I'm more than happy to do it, so long as the recipe adheres to the rules above and is accompanied by documentation as follows.

The documentation is carried out using genpage itself to generate. You should create a content file with the following sections:

%template
recipe.html

%title%
recipename documentation

%name%
Name of the recipe file e.g. foo.gp

%abstract%
A brief abstract describing the function of the recipe.

%syntax%
Details on the syntax of the recipes commands.

%todo%
Information on outstanding work to do to the recipe.

%examples%
Examples on how to use the recipe.

%bugs%
Any outstanding or known bugs.

%history%
Version history of the recipe.

%maintainer%
The person currently responsible for maintaining the recipe.

%authors%
Original author(s) of the recipe.

%homepage%
The location of the recipe's homepage (if there is one)

%compat%
Versions of genpage that the recipe is known to work with.


Current contributed recipes

Currently available recipe documentation (in no particular order):

• download.gp
• imgsize.gp
• menu.gp
• toc.gp
• news.gp
• thumbnail.gp
• relPath.gp
• getModTime.gp
• displayHTML.gp
• getDateTime.gp (updated getModTime)