PDF version
Writing A Custom Skin for Pavlov
- Writing a Skin for Pavlov
- Step 1: Find The Skins Directory
- Step 2: Look at an Example
- Step 3: Set up A Default Theme
- Step 4: The Other Template Files
- Step 5: Use Advanced Velocity Features
- Step 6: Get More Information From Pavlov
- Step 7: Publish
- Known Bugs and Issues
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.
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
07
08 <HR>
09 <table width="100%" height="400" border="1">
10 <tbody>
11 <tr width="100%" height="200">
12
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>
19
20 #else
21 <td colspan="2" height="200" >
22 <div class="P"><big>$QUESTION_TEXT</big><</div>
23 </td>
24
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>
43</body>
44</html>
Let's make a few observations:
- This is a well formed HTML document (Java doesn't like bad HTML)
- It has some funny stuff with pound "#" signs (this is Velocity for "do something")
- It has some funny stuff with dollar "$" signs (this is Velocity for "value of something")
- $BOOK_NAME and $CHAPTER_NAME let you reference the name of the book and chapter the user is quizzing on.
- On lines 13 to 18, we display the question's image along with the question's text if the image exists
- On lines 20 to 25, we display the question's text if no image exists for the question
- On lines 33 to 35, we display answer A as well as providing a link that Pavlov uses to determine if it is the right answer or the wrong answer
- Note the $BASE_URL variable in line 5. This lets you use resources in the same directory as QuizPanel.vm.
- The rest of the code just closes the table and document.
- Since we know about how big this HTML page is going to be, we set the table height and width. This makes life a little easier on Java. If we do not know the size, the Java components can figure it out on their own.
- Feel free to use CSS Stylesheets, either inlined with the <STYLE> tag or loaded with a <LINK> tag. Remember to use $BASE_URL to help the system find linked files.
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.)
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 name=Binary fontName=Microsoft Sans Serif text2=153,153,153 text1=255,255,255 black=255,255,255 fontStyle=1 white=0,0,0 primary3=0,0,0 secondary3=31,31,31 primary2=0,0,0 secondary2=204,204,204 primary1=204,204,204 secondary1=0,0,0 fontSize=14
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
- Selecting a skin before starting a quiz causes some (minor) problems in how the QuizPanel is drawn.
- It's a really good idea to use HTML tables to enclose the content in Library.vm and QuizPanel.vm, and to set the width and height of these tables. 100% is a good setting for table width. Using exact numbers like width="400" height="400" is a good idea.
