A tour is a selection of existing pages on the CSWeb site, strung together to make a guided tour.
For example, a tour for prospective undergraduates may include pages from a selection of course pages and Course Handbook pages on the CSWeb site.
The pages should already exist on the CSWeb site, and a tour framework can be written containing the URLs of the pages to be part of the tour, alongside any annotations for those pages.
The tour framework file should be located at /web/cs/httpd/docs/tours/tour_frameworks, where all tour frameworks are located.
The syntax of the tour framework file is simple, and can be seen in
/web/cs/httpd/docs/tours/tour_frameworks/staff.tour. The first line of the file must be the title of the tour, as used in the tour start page
(the page before the tour starts, where each location in the tour is listed)
and as an H1 header in the annotation for each page
Following from that, the next line should contain the absolute URL
of the first page of the tour. This URL should not include the hostname
of the server. An example is /people/staff/index.@local_path
(note the use of @localpath).
Next comes the annotation. It should be enclosed in curly braces ({}) and may cross more than one line of the tour framework file (unlike the other data). It may also contain any HTML markup you require. Note that there must be an annotation, even if it is empty (i.e. {}).
The rest of the file should contain a URL / annotation pair for every other page in the tour.
Below is an example tour framework file that shows how the file may be laid out - we don't advise you layout your tour frameworks in this way!
The "members of staff who've made their webpage" tour
/people/staff/atp/index.@local_path
{This is Andy's
business card}
/people/staff/djb1/index.@local_path
{This is a longer annotation
that actually crosses several lines
in the
framework file}
/people/staff/rej/index.@local_path
{}
/people/staff/saf/index.@local_path
{}
Note that the file may contain blank lines between URLs and annotations, but nowhere else.
This is a more practical example:
The "members of staff who've made their webpage" tour
/people/staff/atp/index.@local_path
{
<P>This is Andy's <B>business card</B>.</P>
<P>It is generated from information held in a database, the
<CODE>staff_home_page.template</CODE> and a series of include files in
Andy's <EM>~/webpages</EM> directory.</P>
}
/people/staff/djb/index.@local_path
{This is the second page.<P><H3 ALIGN=RIGHT>This is the second annotation</H3>}
/people/staff/rej/index.@local_path
{
<CENTER><CODE WIDTH=10>
This is the third annotation. It is centred and pre-formatted.
</CODE></CENTER>
}
A CGI script overlays the appropriate annotation and navigation buttons on each page listed in the tour framework file.
The final step in creating a tour is to create a start page for your tour.
This page will provide the entry point to your tour by creating a hyperlink
the the tour CGI script.
btp is used to make this page, which will also list the titles of all the tour's destination pages, which will themselves be hyperlinks to the appropriate page in the tour.
A skeleton start page template is at /web/cs/httpd/docs/tours/start_page_skelton.template. You should take a copy and edit it to suit your
requirements. You should copy it to the place where you want the tour to start. Generally, this will involve the following changes:
#head line.
<DT><A HREF="/cgi-bin/tour.local?my_tour_framework.tour&/my/tour/start/page.local&0">E N T E R (at your peril)...</A>
and
<DT><A HREF="/cgi-bin/tour?my_tour_framework.tour&/my/tour/start/page.html&0">E N T E R (at your peril)...</A>
my_tour_framework.tour to the name of your tour framework file held in /web/cs/httpd/docs/tours/tour_frameworks.
/my/tour/start/page.html to the URL (minus hostname) of your tour start page.
Now read the manual page for btp before using btp to create the local and external versions of your tour start page.
Finally, make sure that the pages created by btp are world readable, and you should be able to try out your tour!
