the Pavlov site

PDFPDF version

Writing A Custom Skin for Pavlov

Writing a Skin for Pavlov

One of the big improvements in Pavlov 1.1 is the leveraging of the Apache Jakarta Project's Velocity Template Engine to create templated Pluglets and Skins. This document describes how to write a custom Skin for Pavlov.

Step 1: Find The Skins Directory

Let's assume you already have Pavlov 1.1B1 or later installed. Find the directory it was installed in. Now, there will be a subdirectory called resources and its subdirectory of resources/skins. In the 1.1B1 release, there are several subdirectories of skins, like "cipher" and "euphoria." Every subdirectory of skins is scanned at startup for subdirectories that have velocity template files named Library.vm, Logon.vm, QuizPanel.vm, and Welcome.vm. Pavlov also looks for a file called Theme.theme which specifies the fonts and colors to use for the skin.

Don't spend any time working on the Logon and Welcome templates. They need to be there, but aren't really used. They won't need to be there in a near-future release.

Let's take a look at one of these examples.

Step 2: Look at an Example

We open up the file QuizPanel.vm in the cipher directory and see something like this:

01 <html>
02 <head>
03  <title>pavlov quiz: $BOOK_NAME: $CHAPTER_NAME</title>
04 </head>
05 <body text="#ffffff" bgcolor="#000000" link="#ffffff" vlink="#ffffff" 
   alink="#ffffff" background="${BASE_URL}cipher.JPG">
06 pavlov quiz: $BOOK_NAME: $CHAPTER_NAME
08 <HR>
09  <table width="100%" height="400" border="1">
10    <tbody>
11      <tr width="100%" height="200">
13 #if( $QUESTION_IMAGE!="")
14       <td valign="Top" height="200" colspan="1">
15        <div class="P"><big>$QUESTION_TEXT</big></div>
16        </td>
17        <td><img src="$QUESTION_IMAGE" align="Left">
18        </td>
20 #else       
21        <td colspan="2" height="200" >
22        <div class="P"><big>$QUESTION_TEXT</big><</div>
23        </td>
25 #end      
26        </tr>
27      <tr>
28        <td colspan="2">
29        <table width="100%" border="0" height="200">
30          <tbody>
31            <tr>
32              <td height="100%"><!-- start a -->
33              <div class="P"><big><a href="${BASE_URL}$A_BUTTON"><b>
34       A.</b></a>
35  $A_ANSWER </big></div>
36              <hr>
... stuff deleted...
37             </td>
38            </tr>
39          </tbody>
40        </table>
41      </tbody>
42   </table>

Let's make a few observations:

Java doesn't like some META tags (charset specifiers seem to be the primary offenders), and it hates bad HTML. If you have problems debugging a VelocityPluglet, try to remove META tags and simplify the HTML.

Step 3: Set up A Default Theme

When you've got your HTML how you want it, you've probably made some decisions on what sort of fonts and colors you want the skin to use. You can ensure that the rest of the Pavlov application uses these fonts and colors by providing a file Theme.theme in your skin directory. You can create this file by hand or using the "Theme Editor" available in Pavlov. (If you use the theme editor, you'll have to save your theme, then copy if from resources/themes/YourTheme.theme to resources/skins/yourskin/Theme.theme.)

You can skip the next paragraph if you're planning to use the ThemeEditor to create your themes.

As an introduction to themes, let's take a look at the Binary.theme file. The colors are comprised of triplets of numbers from 0-255 describing the amount of red, green, and blue in the color. Attributes like fontSize, name, and fontName are pretty self-explanatory. The best way to understand what parts of the GUI correspond to the various colors is to use the Theme Editor in Pavlov.

#Tue May 11 20:41:04 EDT 2004
fontName=Microsoft Sans Serif

Step 4: The Other Template Files

The files Logon.vm and Welcome.vm shouldn't be part of the skin system, but they have to be there for now. You shouldn't spend any effort customizing these templates. The Library.vm file controls how the books and chapters containing questions are displayed to the user. You should customize Library.vm to agree with your QuizPanel.vm template.

Step 5: Use Advanced Velocity Features

The best source for information on advanced Velocity features is at Apache Jakarta Project's Velocity Site. There are some neat tricks on display there.

Step 6: Get More Information From Pavlov

Pavlov passes a great deal of information to your template. The default skin in skins/default displays all the information Pavlov passes. If you want to display more or less information, feel free.

Step 7: Publish

When you get a skin that you like, send it to the Pavlov project. We'll need copyright information and have to filter out obscenities, but other than that, we'll be happy to make your skin available. That way, others can not only use your skin, but learn from it as well!

Known Bugs and Issues