NAME

admin-cgi/mktemp.pl - WWW based template editor

SYNOPSIS

  admin-cgi/mktemp.pl [-C charset] [-L language]
    [-m views_dir] [-o outline_dir] [-s source_dir]
    [-t index_dir] [-u url] [-v subject_view]
    [-w whats_new_view]

DESCRIPTION

The mktemp.pl program is a Common Gateway Interface (CGI) compliant program run from an HTTP daemon. It allows a user sitting at a forms capable World Wide Web (WWW) browser to generate an Internet Anonymous FTP Archive (IAFA) template and then either have a text version of the template returned to the browser, have a text version emailed to a database administrator, actually enter the template into a database, or have the template saved in a holding area pending later processing.

In the case that the template is entered directly into the ROADS database it will be immediately available for searching via the search.pl program. The user will also be given the option of adding it to a subject listing and whats new file.

To allow the indexing and addition to the subject lists and whats new files to take place, the mktemp.pl program must have access to the deindex.pl, mkinv.pl, addsl.pl, addwn.pl scripts in the ROADS bin directory.

USAGE

You can either create resource description templates by hand using your favourite text editor (e.g. GNU Emacs), or via the World-Wide Web based template editor distributed with the ROADS software. Note that in order to use this feature your browser must support HTML forms.

If your server's Internet domain name was bork.swedish-chef.org, your World-Wide Web server was running on port 80 (the default) and you installed ROADS using the default paths, the template editor would be found at:

  http://bork.swedish-chef.org/ROADS/admin-cgi/mktemp.pl

Most of the ROADS tools which manipulate templates will let you specify the directory in which the templates are held. The template editor is a notable exception, and we will probably remedy this in a later version of the software.

We suggest that you use the IAFA template schema shipped with the ROADS software as a starting point. If you find that you need to change the templates, e.g. to add a new attribute or describe a new type of resource, we suggest that you discuss the changes you have in mind with other ROADS users on the open-roads@net.lut.ac.uk mailing list. By doing this we may be able to avoid ending up with different attributes (or templates!) which describe the same things.

If you use the WWW interface to create your templates, you will be given the option of specifying your own handle for each template you create, or letting the editor come up with a handle on your behalf. The handle is the name of the template as used internally by the ROADS software - it corresponds to the field in each template which begins with:

  Handle:

If you let the software generate a handle for you automatically, this will be based on the time the template was created. As a result, the handle can be quite long, and has no semantics associated with it. For example:

  814010256-14355

The automatically generated handles are almost certain to be unique, which is very important. If you choose to use your own handles rather than the ones produced by the software, you should be careful to check that there is only one template with a given handle. It's generally a good idea to make the value of the Handle attribute the same as the filename which the template is saved as.

Within the WWW template editor, you may be asked what view of the template you wish to see. This is discussed in detail below. In the first instance at least you are likely to only have one view of each template - all the fields it contains and their values (if any), in which case you will not be queried as to your preferred view. If you often find yourself editing large templates, it will probably be desirable to construct views containing just those attributes which you supply values for on a regular basis.

Many templates allow you to specify multiple instances of particular attributes which are clustered together, e.g. the information about the author of a document may be repeated if the document has multiple authors. In addition to clusters of attributes, some individual attributes may be repeated more than once - these are referred to as variants. If you have elected to create a template which contains clusters or variants, you will be asked to choose how many of these should be present. Hopefully this will be self-evident - e.g. a document with two authors should have two Author clusters.

If you make a mistake, such as not asking for two author clusters, you can easily rectify this later on by editing the template.

The template to be created is rendered as a page of HTML with a type-in box for each attribute in the template - or in the view of it which you have chosen. For the default templates distributed with the ROADS software, each attribute's name will be a hyperlink to on-line help. You may find that the type-in boxes are the wrong size, or want to constrain the possible choices for a particular attribute to a controlled vocabulary - if so, read the sections below on customising the editor.

Having entered values in the type-in boxes for all the attributes you would like to appear in the template, you should choose whether the template should simply be formed and returned as a Web document, sent via email to the ROADS server administrator, or entered into the ROADS server's database. You can also opt to have it entered into a list of resource descriptors broken down by subject category, and/or a What's New list of recent additions to the server. See below for more information on these.

The HTML documents which constitute each of these lists may be customized by the ROADS server administrator. Consequently, you will be asked which customised view you would like to use in constructing or reconstructing the lists. This is discussed in detail below.

If you do decide to create your templates by hand, note that each template must include the Template-Type and Handle attributes, and that the type of the template should correspond to one of the outline templates - see below. Note that in order to use many of the ROADS tools with your templates, it will be neccessary for the attributes in the template to match the template outline definitions discussed below.

You can edit an existing template either by hand, or via a World-Wide Web form. If you know the template's handle already, you can edit it directly using the WWW based template editor - just type the template's handle into the text entry box at the bottom of the starting page.

If you don't know the template's handle already, there is a variant of the ROADS search tool which is intended for administrative use. Following the example above, the URL for this would be:

  http://bork.swedish-chef.org/ROADS/admin-cgi/admin.pl

admin.pl is documented separately in its own manual page.

Alternatively, if you just want to see the template rendered into HTML, or make a hyperlink to it from somewhere else, the tempbyhand.pl tool may be used to do this.

SCHEMA DEFINITIONS

The ROADS software attaches virtually no semantics to the contents of the templates - doing so would require it to know (for instance) that a Description box should be larger than a title box, since it usually contains more text, and so on. We have tried to avoid this wherever possible, instead leaving these decisions up to the ROADS server administrator.

The mechanism we have chosen to use for this is what we call an outline file. Outline files specify important information about each type of template the software knows about, and an outline file must be present for any new types of template, i.e. any templates which were introduced locally and not provided with the ROADS software distribution.

Outline files for the following template types are distributed with the ROADS software. Hopefully the titles are self-descriptive:

DESCRIPTOR: for cataloguing information such as UDC, MeSH or LC SH. Not used in its own right, but included in templates of other types
DOCUMENT: e.g. a book or technical report
FAQ: a Frequently Asked Questions document
IMAGE: e.g. a GIF or JPEG image
MAILARCHIVE: the location of a mailing list archive
ORGANIZATION: information about an organization
PROJECT: information about a project
SERVICE: information about an on-line service
SOFTWARE: information about a software package, e.g. ROADS
SOUND: e.g. an AIFF or WAV object
TRAINMAT: information about training materials
USENET: information about a Usenet News conference
USER: information about a person
VIDEO: e.g. an MPEG or QuickTime object

These can be found in the config/outlines subdirectory of whatever directory you unpacked the ROADS software distribution in.

An individual outline file contains, for the template it describes:

What attributes, or clusters of attributes, it contains. All the attributes in another type of template may be imported by putting its name in brackets after a disambiguating attribute, e.g.
```
  Author-(USER*):
```
says to import the attributes in the USER template, and prefix them with Author-. The star sign (*) indicates that the cluster may appear more than once. Each instance of the incorporated cluster should be tagged with a -v and a sequence number, e.g.
```
  Author-Name-v1: Martin Hamilton
  Author-Name-v2: Jon Knight
```
The reasoning behind this is discussed further in the IAFA template specification.
What variant attributes it contains. These are attributes which may occur more than once, but are not part of another cluster, e.g.
```
  ISBN-v*::::o:
```
This indicates that the ISBN attribute may appear a number of times. Each instance of it should be tagged with a sequence number, e.g.
```
  Language-v1: English
  Language-v2: Swedish
```
How big the editor's type-in boxes should be for each attribute. If not specified for a particular attribute, the default is for each type-in box to be a single line, 25 characters long. For example,
```
  Description:25:5:
```
indicates that a type-in box 25 characters wide and 5 lines deep should be used for the Description attribute.
A set of default values for the attribute. If these are present, they will be presented to the user in the form of a list of choices, and the user will not be able to enter arbitrary text for the value of this attribute. This can be used to enforce a rudimentary controlled vocabulary, e.g.
```
  Format-v*:::Plain text|PostScript|HTML|DVI:o:
```
Indicates that the editor should render the value of the variant attribute Format- in the form of a list:

Plain text

PostScript

HTML

DVI
Whether or not the attribute is mandatory. Mandatory attributes must be supplied, or the editor will refuse to create the template! For example,
```
  Alternative-Title::::o:
```
indicates that the Alternative-Title attribute is optional, and may be omitted from the template. it will be assumed that the attribute is optional if no m (for mandatory) appears in the outline.

The DOCUMENT template distributed with the ROADS software has some sample settings for these outline options, to illustrate the sort of thing which may be accomplished.

AUTHORITY FILES

A more powerful mechanism for using authority lists is additionally available. This lets you conveniently include long lists of alternative values for an attribute in a particular type of template, which would be painful to do in the template outline.

To create an authority list for a particular attribute of a particular template type, e.g. the Keywords attribute of the DOCUMENT template, simply place the words in the authority list in the file config/authority/document/Keywords. Note that we supply this example with the sample configuration that comes with the ROADS software - you may need to create additional directories under config/authority for other types of template.

The authority file is formatted on a line by line basis, with each line a separate authority term or terms, e.g.

  Glastonbury
  Phoenix
  Reading

ACCESS CONTROL LISTS

If you use HTTP user authentication to control access to your administrative programs, which we strongly recommend, the authenticated user name is available to the ROADS tools for access control purposes. This makes it possible for us to determine whether a particular user should be allowed to modify a particular template.

Access control on an individual template may be enabled by checking the box labelled ``Add me to the user authentication list for this template'' (in the default English message set for the template editor) whilst editing the template. We also provide an additional tool templateadmin.pl for editing the access control list for a given template.

TEMPLATE VIEWS

It is important to note that the template editor can be configured to display only those attributes of the templates which you are interested in seeing. This can be a very useful feature when the template you are editing has a large number of attributes.

In fact, you can specify multiple views of a template. This is intended to make life easier for people who look after templates, by letting them have ``quick views'' which just display those attributes which are used most often, and ``detailed views'' which display most or all of the attributes in a template.

ROADS is shipped with a Common Elements view for each template type, to demonstrate how this feature works in practice. When editing an existing template or creating a new one, you will be prompted as to whether you want the Common Elements view, or would prefer to see all the fields in the template. The full view of the template is always available, and any information which is in the full view will continue to appear in the template after you have edited it using another view such as Common Elements.

The views which are available for a particular type of template can be found in the directory config/mktemp-views, in the place where you unpacked the ROADS software. There will be a file for each type of template which has multiple views defined. Any template which does not have multiple views defined will only be available as a full view. In a future version of the software we will probably provide a facility to create and maintain editor views via a WWW form, but in the meantime you will need to use a text editor.

To create a view of the SERVICE template called Highlights, one would first copy its outline from the the directory config/outlines, e.g.

  % cp config/outlines/service config/mktemp-views

Having done this, for each line in the copy of the outline file in the config/mktemp-views directory, you should replace everything after the colon (:) with the names of the views in which you would like it to appear, e.g.

Before:

  Requirements:

After:

  Requirements:Highlights:

You can specify multiple views, separated by colons, if you would like an attribute to appear in multiple views. By default it will always appear in the ALL view, which is generated automatically by the ROADS software itself.

ALTERNATE BACKENDS

We have tried to keep the template editor design sufficiently open that it can be used as a front end to other databases. This has been done by giving it the capability to run an external program instead of the normal database update process.

The mktemp.pl manual page describes the template editor's back end interface in detail, but it is important to note that your replacement back end code must be able to process the IAFA template format, as generated by the template editor. This is because IAFA is used as an interchange format between the template editor and any external code you may develop as a template editor back end.

OPTIONS

-C charset: The character set to use.
-L language: The language to use.
-m views_dir: The directory to look in for alternative template editor views of the data being edited.
-o outline_dir: The directory to look in for template outlines, i.e. schema definitions.
-s source_dir: The directory to look in for templates themselves.
-t index_dir: The directory to look in for the ROADS index.
-u url: The URL of the template editor program itself.
-v subject_view: The directory to look in for alternative subject listing views for the addsl.pl program.
-w whats_new_view: The directory to look in for alternative "What's New" listing views for the addwn.pl program.

CGI VARIABLES

asksize

Set to "done" once the user has been asked if they want to change the number of clusters and variants displayed in the main template editing form. Setting this variable before calling the template editor will cause this stage to be skipped.

charset

The character set to use.

clusterclustername

The number of clusters of type clustername included in the template.

done

Boolean variable set when the template editing is complete.

IAFAfieldname

A field from the template - e.g. the Handle field would be represented as IAFAHandle.

language

The language to use.

mode

The editing mode for the template editor - normally either create (when creating a new template from scratch) or edit (when editing an existing template).

originalhandle

When editing an existing template, the handle of the template.

op

The operation to carry out when the template editing form is submitted. Normally this is set to one of :-

  email - email template to ROADS database administrator
  enter - enter template into ROADS database and update any
    subject/what's new listings
  offline - store template for later indexing
  text - return text of template on screen

slinsert

Boolean variable indicating whether or not to include this template in a subject listing.

templatetype

The template type being edited, e.g. DOCUMENT.

variantsize

The number of variant records in the template being edited.

view

The template editor view to use - this governs which template attributes are shown to the end user by the template editor on its main screen. If this variable is set when the template editor is called, the WWW form requesting the user to select a view will be skipped.

wninsert

Boolean variable indicating whether or not to include this template in a "What's New" view.

FILES

config/mktemp.cfg - template editor config, see mktemp-config-editor.pl.

config/mktemp-views - template editor views directory.

config/multilingual/*/mktemp/authlookupform.html - end of authority file lookup form.

config/multilingual/*/mktemp/authlookuphead.html - beginning of authority file lookup form.

config/multilingual/*/mktemp/editformtail.html - end of main editing form.

config/multilingual/*/mktemp/editformhead.html - beginning of main editing form.

config/multilingual/*/mktemp/cannotdeindex.html - HTML returned when existing template being edited couldn't be deindexed.

config/multilingual/*/mktemp/cannotindex.html - HTML returned when template cannot be indexed.

config/multilingual/*/mktemp/cannotreplace.html - HTML returned when an existing template cannot be replaced with a new version.

config/multilingual/*/mktemp/clusterhead.html - beginning of the add cluster/variant form displayed when editing an existing template.

config/multilingual/*/mktemp/clusteronlybottom.html - end of the add cluster/variant form returned when the template has no variants.

config/multilingual/*/mktemp/clustervariantsize.html - end of the add cluster/variant form returned when the template has both clusters and variants.

config/multilingual/*/mktemp/failedcreation.html - HTML returned when the temporary copy of an existing template being edited could not be created.

config/multilingual/*/mktemp/handleexists.html - HTML returned when an attempt has been made to create a new template with the same handle as an existing one.

config/multilingual/*/mktemp/introform.html - initial HTML form returned when starting up mktemp.pl for the first time without specifying any of its CGI parameters.

config/multilingual/*/mktemp/lookupclusterform.html - end of form returned when doing a cluster search.

config/multilingual/*/mktemp/lookupclusterhead.html - beginning of form returned when doing a cluster search.

config/multilingual/*/mktemp/mailererror.html - HTML returned when mktemp.pl could not email the template to the ROADS database admin contact.

config/multilingual/*/mktemp/missingmandatory.html - HTML returned when mandatory fields are missing from the submitted template.

config/multilingual/*/mktemp/nonexistant.html - HTML returned when the user tried to edit a template which didn't exist in the ROADS database.

config/multilingual/*/mktemp/notemplateoutline.html - HTML returned when the template type being edited has no outline (schema).

config/multilingual/*/mktemp/notemplates.html - HTML returned when mktemp.pl couldn't find its list of the template types supported on the installation.

config/multilingual/*/mktemp/offlineaddedok.html - HTML returned when an offline template creation was successful.

config/multilingual/*/mktemp/offlineeditedok.html - HTML returned when an offline template update was successful.

config/multilingual/*/mktemp/selectview.html - form used to select from available template editor views.

config/multilingual/*/mktemp/variantsizeonly.html - form returned when editing an existing template which has variants but no clusters.

config/outlines - outline (schema) definitions for the supported template types.

guts/alltemps - list of template handle to filename mappings.

source - directory where the templates may be found.

FILE FORMATS

EDITING VIEWS

A template editor view consists of a file named after the template, e.g. user for the USER template. The first line of this file must consist of the string "Template-Type: " followed by the template type itself. The other lines of this file list attributes and the views which are available of them, separated by colons, e.g.

  Template-Type: USER
  Handle:
  Name:Quick Edit:Martin
  Work-Phone:
  Work-Fax:
  Work-Postal:
  Job-Title:Quick Edit:Martin
  Department:Martin
  Email:Quick Edit:Martin
  Home-Phone:
  Home-Postal:
  Home-Fax:

This configuration defines two views - Quick Edit and Martin of the the USER template, in addition to the built-in default view ALL, which shows all fields. Note that the Department attribute only appears in the Martin view.

If the attribute is a cluster (such as a USER or ORGANIZATION cluster embedded in a DOCUMENT template) there are two options for specifying views. The first is to use an attribute name of the form:

  AttributeName-(ClusterName*):

where AttributeName is the base part of the cluster attribute name and ClusterName is the template type of the cluster. For example:

  Author-(USER*):

In this case the views for all the elements in the cluster are inherited from the view of the cluster's template type. This allows you to set up standard views for clusters that can appear in all templates and also means that only the cluster's template type's views need to be changed to affect the views of all template types that include that cluster.

The second way of defining views for elements of a cluster is to do so on an attribute by attribute basis. To do this specify just the attribute name (without the trailing "-v*") in the view file for the template type that the cluster appears in. For example consider the Author-(USER*) cluster in the DOCUMENT template type. To specify that Name attribute of the USER cluster should appear in the "Quick Edit" view, use the line:

  Author-Name:Quick Edit:

in the DOCUMENT template type's view. This permits different templates to include different views of the same clusters.

OUTLINE FILES

Each outline file consists of a first line of the form

  Template-Type: DOCUMENT

which describes the template type being represented in the outline. There then follows a list of the allowable attributes, one per line, in the following format:

  Attribute-Name:x-size:y-size:default:status:

The Attribute-Name is the name of the field in the template and also specifies the field type (either plain, variant or clustered). For plain fields, this is just the field name. For a variant field, the field name has -v* appended to it. For a cluster, it has (CLUSTER_TYPE*) appended, where CLUSTER_TYPE is the template type of the embedded cluster. The x-size and y-size are optional and if present specify the size of the text editing area used for that attribute in the HTML editing form. The default size is 40 characters long by one character high.

The defaults field is text automatically placed loaded into the editing form. If the defaults does not contain any vertical bar ("|") characters, it is loaded into the text edit box of new templates by the mktemp.pl script. The vertical bar characters can be used to separate a number of options which will be presented as drop down selections in the editor form. This latter form allows a small controlled vocabulary to be used in some fields in the template.

The status field tells the mktemp.pl program whether or not it is mandatory that the field contains some text once the filled in template is submitted. If the character m appears in this field, it is considered to be mandatory and any templates submitted without such fields completed will generate an error.

DATABASES

The ROADS software can split templates in the same installation up into "virtual" databases, using their Destination attribute. You may wish to use the defaults feature in the template editor outlines to restrict the available choices for later processing.

The mktemp.pl program can make use of backend database technologies other than the simple file system based index supplied in the ROADS distribution. It does this by making use of two external database Application Programming Interfaces (APIs). The first of these is used to add a template to an external database and the other deletes a template from an external database. The API for both of these operations are basically the same; two environment variables are used to pass the handle of the template and the location of the source IAFA template to an external program. These environment variables are called HANDLE and IAFAFILE respectively. The external programs for adding and deleting templates from a third party external database should return zero on a successful completion and a non-zero value if they failed for some reason.

The names of the two external programs are held in the Perl variables \$ROADS::ExtDBAdd and \$ROADS::ExtDBDel. The values for these can be placed in the ROADS.pm file in the lib directory of the ROADS installation.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

It was developed by the Department of Computer Studies at Loughborough University of Technology, as part of the ROADS project. ROADS is funded under the UK Electronic Libraries Programme (eLib), the European Commission Telematics for Research Programme, and the TERENA development programme.

AUTHOR

Jon Knight <jon@net.lut.ac.uk>, Martin Hamilton <martinh@gnu.org>

To install ROADS::WPPC, copy and paste the appropriate command in to your terminal.

cpanm

cpanm ROADS::WPPC

CPAN shell

perl -MCPAN -e shell
install ROADS::WPPC

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)