/ 
roads-v2.3
/ ROADS::Render

NAME

ROADS::Render - A class to render HTML outlines + variable substitutions

SYNOPSIS

use ROADS::Render;
# Do a WHOIS++ search or three...
render($query, $view, @results);

DESCRIPTION

This class defines a mechanism for rendering WHOIS++ templates as HTML - or other formats, though HTML is the primary goal.

METHODS

render( query, view, @results );

query

The WHOIS++ query which generated these results

view

The view to use when rendering the results - many of the ROADS tools which generate HTML support multiple versions or 'views' of the same data using different HTML rendering rules.

results

This is a list of results in the format produced by the wppd code in the ROADS::WPPC class.

FILES

config/multilingual/*/scriptname/noconnect.html - HTML returned when connection to server couldn't be established.

config/multilingual/*/scriptname/nohits.html - HTML returned when there were no hits for a given query.

config/multilingual/*/scriptname-views - directory containing alternative views of rendering.

RENDERING VIEWS

Each view is actually a directory. Views typically consist of

HTML (or whatever...) to return for beginning of page.

tailer

HTML (or whatever...) to return for end of page.

full

Default rendering rules

USAGE

The following additional custom rendering outlines are available :-

format

where format is the name of the WHOIS++ response format. This lets you treat, for example, referrals to other servers differently from regular records. You could include a special logo for referrals, for instance.

serverhandle

where serverhandle is the server handle of one of the servers you expect to get results back from. This lets you give all results which come from this particular server their own custom HTML.

handle

where handle is the handle of a resource which you would to have rendered differenly from all the other resources. If you have a few 'stand out' resources this could be a good way of drawing attention to them.

format-serverhandle

where serverhandle and format are as before. This lets you treat (for example) referrals from this server differently to regular records.

format-template_type

where template_type is the template type of the record. This lets you render different types of records in different way - e.g. to display a picture icon beside an image.

format-template_type-serverhandle

This lets you customize down to the level of particular types of template from particular servers.

format-template_type-serverhandle-handle

Phew! This lets you customize down to the level of an individual template handle, from a particular server, of a particular type and response format :-)

You probably won't need to tangle with this stuff early on (if ever?) but we've tried to build plenty of flexibility in so that if you do want to use it you can get some quite dramatic results with a minimum of effort. Check out the technical guide for more information about customizing HTML rendering.

PSEUDO-HTML TAGS

FOREACH

This specifies a substitution pattern (see below) which is to be executed for each instance of the attribute specified in its right hand side. The format is

<FOREACH "[default value]"> [substitution pattern]

where the text marked [default value] is used if there are no instances of the attribute specified in the substitution pattern.

MYURL

Replaced with the URL of the WWW server, formed from \$ROADS::MyHostname and \$ROADS::MyPortNumber.

QUERY

Replaced with \$query, the WHOIS++ query.

ROADSSERVICENAME

Replaced with \$ROADS::ServiceName.

Attributes from the template being rendered may be referred to by placing an @ sign in front of the attribute name, e.g. @KEYWORDS refers to the Keywords attribute. If this does not occur within a FOREACH tag, only the first occurrence of the attribute's value will used.

The format of these references is

<@[attributename] "[default value]">

e.g.

<em>Keywords:</em><br> <@KEYWORDS "no keywords supplied">

Outline HTML files are found in config/search-views. Note that you can only effect substitution for a single attribute per line of your HTML outline file at the moment.

BUGS

The integration of hard coded HTML for the template editor and some aspects of the subject/what's new listings is sub-optimal - to say the least!

SEE ALSO

admin-cgi and cgi-bin programs, "addsl.pl" in bin, "addwn.pl" in bin, "cullsl.pl" in bin, "cullwn.pl" in bin.

COPYRIGHT

Copyright (c) 1988, Martin Hamilton <martinh@gnu.org> and Jon Knight <jon@net.lut.ac.uk>. All rights reserved.

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>