Theme HOWTO

YaWPS themes consist of up to two files which make up a theme. The CSS-file of course defines the style of each theme. And the theme.pl contains the template as well as some layout functions (of course you can also put the CSS definitions into the header function of your theme if you don't like to have an external CSS file).
All the templates in YaWPS reside in the directory themes off of your YaWPS root directory.

Create a directory inside the themes-directory and label it as you want. You need to have the complete HTML-code of your desired layout finished and all tags in style.css defined (please refer to the style.css in YaWPS standard theme. You need most of the tags from there in your new CSS or the design will look broken). You have to "split" the HTML-File in two parts: a header and a footer. The header would end right before the point, where all the content of your page should start (mostly the part in the middle of the page ;)). You have to put this content in the sub routine theme_top in your theme.pl file. The footer consists of the bottom part of your HTML-File (to be saved into theme_bottom). You have then to define the layout functions box_header, box_footer and menu_item. You can include these routines in your theme_top- and/or theme_bottom-function to show every block of your menus in the layout-style.

Function name	Purpose	Example
menu_item()	Returns HTML for a link used in a box in the side panels.	my $item = menu_item("url", "title");
box_header()	Returns HTML used at the top of a box in the side panels.	print box_header("title");
box_footer()	Returns HTML used at the bottom of a box in the side panels.	print box_footer();
get_formatted_date()	Here you can define how the current date should be displayed.	my $date = get_formatted_date();

You can call some function exported from yawps.pm to populate your left/right menus.

Function name	Purpose	Syntax
main_menu()	This will print the Main menu box, including the links to installed modules.	print main_menu("url", "title");
user_panel()	Prints a box with possible user actions depending on user permissions.	my $user_panel = user_panel();
user_status()	Shows the status box, login information, online members/guests and a link to the IM inbox.	my $user_status = user_status();
current_poll()	This will display the current poll.	my $current_poll = current_poll();
latest_forum_posts()	Displays the last five forum post titles.	my $latest_forum_posts = latest_forum_posts();
show_blocks()	This will show additional blocks, which are editable by the administrator. You have to substitute location either with header or footer.	my $blocks = show_blocks("location") || '';
show_quote()	This will display a random quote from the quotes database.	my $quote = show_quote();
check_ims()	This will add a Javascript function to the YaWPS HTML output, which presents a popup window, if the user has a new message in his inbox waiting.	my $im_alert = check_ims() || '';

Here is a list of definitions needed by the YaWPS core (it doesn't matter if you put them in a CSS file or if you include them directly in the theme's HTML head). You can add your own definitions if you need them in your theme.

Class name	Function	Example value
cat	The background of a cell in a block	color: #737b9c; font-family: arial, helvetica, geneva
texttitle	Headline in news, etc.	color: #660033; font-family: arial, helvetica, geneva
tbl_header	Header for tables in middle	background-color: #000000; color: #000000; font-family: arial, helvetica, geneva
tbl_row_light	Rows with even numbers in a table	background-color: #FFFFFF; color: #000000; font-family: arial, helvetica, geneva
tbl_row_dark	Rows with odd numbers in a table	background-color: #EEEEEE; color: #000000; font-family: arial, helvetica, geneva
bg, bg2, bg3, bg4, bg5	Various backgrounds in content tables	background-color: #000000

You have of course access to all global YaWPS variables and constants defined in yawpsrc.pl. The most important variables are:

Variable name	Variable function
$cfg{pagetitle}	The page title
$cfg{pageurl}	The URL to your YaWPS
$cfg{codepage}	The character encoding
$cfg{imagesurl}	The URL to the images directory
$cfg{themesurl}	The URL to the themes directory

You can of course use all the local language definitions for headlines, buttons and information boxes.

Let's assume you have the following HTML code for your layout template "Test".
1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2: <html>
3:
4: <head>
5: <meta http-equiv="expires" content="0">
6: <meta http-equiv="Content-Type" content="text/html; charset=$cfg{codepage}">
7: <meta name="Generator" content="YaWPS $VERSION">
8: <title>$cfg{pagetitle}</title>
9: </head>
10:
11: <body>
12: <table border="0" cellpadding="0" cellspacing="0" width="100%">
13: <tr>
14: <td colspan="2"><img src="$cfg{themesurl}/Test/logo.png"></td>
15: </tr>
16: <tr>
17: <td>### LEFT MENU HERE ###</td>
18: <td>### CONTENT HERE ###</td>
19: </tr>
20: </table>
21: </body>
22:
23: </html>
In line 6 we use the $cfg{codepage} variable to define the page character encoding, in line 7 we show the YaWPS version we use (this is for information purpose only) and line 8 will display the page title. In line 14 we display the page logo, by using the $cfg{themesurl} vatiable, followed by the theme directory we are going to use for this template.
For this template we use a two column layout. The left menu will be placed in the first cell and the content will be placed in the second cell of the table.

Of course we are going to brake our HTML template in two parts, header and footer. We have to do this in line 18, right behind the cell opening tag.
Now we put the HTML snippet from line 1 to 18 and put it into the function theme_top(). For this demo theme we want to put the main menu and the user panel into the left menu, so we have to include the following variables on top of the theme_top() function.
my $main_menu = main_menu();
my $user_panel = user_panel();
After the variables are initialized, we only have to put them where the output should be displayed. To do so we include the following right after the cell opening tag in line 17 (the start of our left menu):
print $main_menu;
print $user_panel;

Now on to the theme footer. We have to put the HTML snippet from line 18 (right before the cell closing tag) to line 23 into the function theme_bottom(). Since we don't want to have much YaWPS output there we're almost done. The only function we inlude here is the check_ims in line 41. We put the variable $im_alert into line 48 at the end of the HTML template (looks better in browser there).

We need to define the layout of a box, since YaWPS uses it to print the boxes for the main menu and the user panel. We do this as descibed above (see theme functions).

After this we can save the template as theme.pl in our "Test" directory. The complete theme.pl would look like this:

1: sub theme_top
2: {
3: # Import variables.
4: my $main_menu = main_menu();
5: my $user_panel = user_panel();
6:
7: print <<"HTML";
8: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
9: <html>
10:
11: <head>
12: <meta http-equiv="expires" content="0">
13: <meta http-equiv="Content-Type" content="text/html; charset=$cfg{codepage}">
14: <meta name="Generator" content="YaWPS $VERSION">
15: <title>$cfg{pagetitle}</title>
16: </head>
17:
18: <body>
19: <table border="0" cellpadding="0" cellspacing="0" width="100%">
20: <tr>
21: <td colspan="2"><img src="$cfg{themesurl}/Test/logo.png"></td>
22: </tr>
23: <tr>
24: <td>
25: HTML
26:
27: # Display the main menu.
28: print $main_menu;
29:
30: # Display the user panel.
31: print $user_panel;
32:
33: print <<"HTML";
34: </td>
35: <td>
36: HTML
37: }
38:
39: sub theme_bottom
40: {
41: my $im_alert = check_ims() || '';
42:
43: print <<"HTML";
44: </td>
45: </tr>
46: </table>
47: </body>
48: $im_alert
49: </html>
50: HTML
51: }
52:
53: sub menu_item
54: {
55: my ($page, $title) = @_;
56:
57: my $menu_item = <<"HTML";
58: <tr>
59: <td>- <a href="$page">$title</a></td>
60: </tr>
61: HTML
62:
63: return $menu_item;
64: }
65:
66: sub box_header
67: {
68: my $title = @_;
69:
70: my $box_header = <<"HTML";
71: <table width="150">
72: <tr>
73: <td width="100%"> $title</td>
74: </tr>
75: HTML
76:
77: return $box_header;
78: }
79:
80: sub box_footer
81: {
82: my $box_footer = <<"HTML";
83: </td>
84: </tr>
85: </table>
86: HTML
87:
88: return $box_footer;
89: }
90:
91: 1; # return true!

The finished "Test" folder should now contain the following files:

-rw-r-r- 1 user web 0 Nov 23 11:22 index.html
-rw-r-r- 1 user web 994 Nov 23 13:03 logo.png
-rw-r-r- 1 user web 1320 Nov 23 17:54 theme.pl

Now put the entire "Test" folder into your themes directory and you are done!