iVia

Appendix B: Institutional Co-branding with iVia Themes

Warning: This page has not been updated to iVia version 5.

Many iVia web pages, including search results, are generated dynamically as the user interacts with them. These pages are created with iVia's "theme" system, which allows us to control the appearance of the iVia web pages.

Collaborating institutions can supply their own themes so that canned_search results are consistent with other web pages on their web sites. For example, search results using the wfu theme are displayed on the INFOMINE web server and are consistent with the Wake Forest University web pages.

Warning: Some information on this page may be out of date.

Installing themes

If you get a message that says "Error: No themes exist!" when trying to access the Theme Management page , or you get the default theme instead of the one you expect, then you will need to add themes to the database. You (or the machine administrator) can do so by running the following command:

Existing INFOMINE canned_search themes

The most common use of Themes is to format the output of the canned_search program (see Appendix A: Canned Search) in a manner appropriate to a particular institution or Web page. Although it is often useful to have a customized theme, INFOMINE provides a selection of pre-built canned_search themes which may be appropriate for your site.

The currently-available canned_search themes are listed below. If one of themes below is appropriate for your purposes, we suggest you use it and skip the rest of this chapter. If you require a more specialized theme.

How Themes work

Many iVia web pages, including search results, are generated dynamically as the user interacts with them. These pages are created with iVia's macro system, which works by reading template files, inserting data into the templates at the appropriate places, and sending the resulting HTML to the user's web browser. This makes it easy to control the appearance of the iVia web pages.

For a complete description of template files and the iVia macro language, see Appendix C: Template files and the iVia macro language.

How canned_search works

The most common use of the macro system is to display search results in a particular style. For example, the ucr_library theme displays search results in the same style as the UCR Library pages (e.g. search for Music resources).

The canned_search result pages are generated from a set of template files: top.html, data.html, bottom.html and zero_results.html. Each describes a different part of the generated page.

When the user performs a search and one or more documents are returned, canned_search outputs these results in three stages. First, it reads top.html, substitutes its macros and outputs it. Second, it reads data.html, then for each search result substitutes its macros and outputs it. Third, it reads bottom.html, substitutes its macros and outputs it. (If the user performs a search and no results are found, then canned_search reads zero_results.html, substitutes its macros, and outputs it.)

The simple canned_search theme was designed to be easy to understand. You can download the template files from the table above and have a look at them of you like. (Note that the template files are not complete HTML documents, but your web browser may think they are, so if you click on the download example links above then you may see some strangely rendered HTML. To see the templates properly, save these links to disk or click on them and then use "View Source" to view them).

The view_record and search programs

Canned_search is not the only iVia program that can be themed: the view_record program, which displays a single iVia record, and the search program, which displays the top-level category search pages and the advanced search page, can also be themed.

These programs use different template files, but in most other respects their display is the same as for canned_search. New themes for these programs can also be create with the theme_editor, but the explanation below will limit itself to the canned_search program.

Creating a new canned_search theme

If you want to create your own canned_search theme, you will need to make your own copies of the four canned_search template files, adapt them to your requirements, and upload them to the iVia server.

The first step is to contact an iVia administrator (on INFOMINE, contact Margaret Mooney at mmooney@ucrac1.ucr.edu) and request that a new theme be created and the appropriate permissions granted. You will also need access to a web server where iVia can reach your template files. You can then use the theme editor to upload your template files to the server.

The theme editor

We will explain the iVia Theme Editor by illustrating its use to create a new theme, called NZDL. This theme will output search results that resemble the New Zealand Digital Library Project's Greenstone software.

After arranging for access to build the theme, we log into the theme editor, shown below:

The top part of the screen is the most important; this is the interface for uploading template files onto the iVia server. It contains a list of of the files that form this theme: in this case, we have yet to upload any files, so their descriptions all read non: using default. The bottom form allows you to quickly test your theme.

The theme menu

The theme menu is the first item in the main form; it is used to control which theme we are currently examining. You can examine other themes with this menu. For example, if we select the simple theme, the screen changes as follows:

In the simple theme page the file descriptions have changed to show the size of the template files but the Upload and Delete buttons have disappeared because the user doesn't have access to alter this theme.

Although we cannot change the simple theme, we can view its template files by clicking on the View button.

Creating a template file

Before we can upload a template file, we have to create one. It's usually easiest to download one of the examples and change it to suit your purposes. Note that you don't have to create all four templates at once: if your theme doesn't have a template file that canned_search needs, it will use the corresponding template from the defaults theme instead. With this in mind, let's start by creating only a data.html file for our nzdl theme, as follows:

<!-- start nzdl/data.html -->
<tr>
  <td valign="top" align="center">
    <img src="/images/nzdl/doc.gif" width="16" height="16" />
  </td>
  <td valign="top" align="left">
    <b><a href="$VIEW_RECORD_URL">$TITLE</a></b>
    <br />
    (<a href="$CLICK_THROUGH_URL">$URL</a>)
  </td>
</tr>
<!-- end nzdl/data.html -->

This template file has several intersting features. First, it starts and ends with HTML comments identifying the template file (<!-- start nzdl/data.html -->). These wont show up on the screen, but can be very useful if you have to debug your files by using the "View Document Source" command in your web browser.

The functional part of the template file starts with a table row (<tr>) tag and ends with a close table row tag (</tr>). This is because in most canned search themes, (including defaults) the results are stored in a table: the table is started in in the top.html template, the table rows are generated from the data.html template, and the table is closed off in the bottom.html template. Although it is not strictly necessary to present search results in tables, it is almost always convenient to do so.

Four macros are used in this template. $TITLE and $URL are fairly straightforward: they resolve to the Title and URL metadata for the result respectively. The CLICK_THROUGH_URL is another form of the URL Metadata that has been altered to redirect anyone who clicks on it through iVia's click through counter. This lets us count how many times each URL is visited. We encourage you to use this form of the URL so that we can keep track of the most popular records in the live database. Note that, in this example, the $URL macro is used to display the URL to the user, but when they click on the link, they are sent to the $CLICK_THROUGH_URL instead. The $VIEW_RECORD_URL macro is a URL that can be used to link to a web page that displays the record. (Adders can see the number of times a URL has been visited or viewed from the "View Record" button in the iVia Database Manager.)

Finally, this template contains an image, which is loaded from /images/nzdl/doc.gif. If the query is being run on the infomine.ucr.edu server, the image URL will be expanded to http://infomine.ucr.edu/images/nzdl/doc.gif, a file which may not exist. Is that is the case, we would expect a broken image to be displayed.

Uploading template files

The first step is to move the edited files to a location where they can be retrieved over the Internet. I have a directory that I use for this purpose at http://tuatara.ucr.edu/~paynter/transfer so I put the data.html file into this directory.

To upload the file to iVia, I select the nzdl theme in the theme editor and enter the URL of the Upload directory in the Upload from field:

To upload the data.html template, I click on the Upload button on the data.html line. The theme editor attempts to replace the current data.html file with the file at http://tuatara.ucr.edu/~paynter/transfer/data.html. Afterwards, the screen looks like this:

We know the Upload succeeded because the description for data.html now reads 319 bytes, indicating that a file of that size was uploaded. There are two new buttons: View lets us look at the file we have just uploaded, and Delete removes it from the server.

Testing the theme

Now that we've started uploading our theme, it is interesting to test it using the search box at the bottom of the page:

Clicking on the Search button launches a search for the term in the box using the current theme. In the present case, we have provided a data.html template but no top.html or bottom.html template. Consequently, the output uses the top and bottom files from the defaults theme and our own data.html file, as shown below:

The empty boxes to the left of each result are caused by the image we added to our template. As we noted above, the image is not on the server, so shows up blank in the web browser.

Finishing and debugging

Once you've got your basic theme in place, you can debug your theme by editing your local file, uploading it, and running new test queries. To finish the nzdl theme, I repeated this process around a dozen times for each file. Here are the final versions of the file:

You can test this theme to see its final appearance.

Frequently asked questions about themes

What macros are used in canned_search?

Good question! The iVia macro language includes the function $CALL(PRINT_MACROS) that will display all the macros currently available. To see what macros are defined for a template, just add $CALL(PRINT_MACROS) to that template and run a new search. A list of the available macros will be displayed.

How do I tell canned_search to use my theme?

Once you have a theme, you will need to set up canned_search to use it. You will normally do this by making a search form somewhere on your own server that initiates a search on an off-site iVia installation. For example, the form below takes the user's query term as input and sends it to infomine.ucr.edu. To use your own theme with this search, you must add a "theme" parameter to the search, which instructs canned_search to use your theme, rather than the "defaults" theme.

For example, suppose you were to create a search box like this one, which uses the simple theme:

The HTML code that generates this form is as follows:

For a full explanation of how to integrate canned_search into your pages, see Appendix A: Canned Search.

Why is the screen not wrapping properly for some searches?

Why is my table very very wide for some searches?

iVia records may have very long URLs, and when these URLs are displayed, the web browser considers them a single word and cannot "word wrap" them properly. In order to get around this, you have to make the URLs that appear on the screen shorter.

Canned search has a "callback function" for just this purpose. To make sure a URL is never more than 100 letters long, don't write $URL, instead write $CALL(SubString,$URL). This will truncate URLs that are longer than 100 letters. You could also write $CALL(SubString,$URL,50) to truncate any URL longer than 50 letters.

You should only use the SubString function for displaying URLs, never when the URL is likely to be used (for example, never in the href attribute of a link).