• Guestbook layout using page template ( i )
• How do I use the guestbook template layout? ( i )
• Reserved characters in the Template layout ( i )
• I made some changes to page template. Now the page doesn't work. ( i )
• Guestbook templates - Cut and Paste ( i )
• Guestbook templates - Tips ( i )
• Available variables when using guestbook Template layout ( i )
• Creating the 'Sign the Guestbook' -page with Template layout ( i )

Guestbook layout using page template

Defining the guestbook layout using page templates requires a bit more effort than with the Form based layout, but it gives you full control over the appereance of the guestbook.

The problem with HTML is how the guestbook messages, so called dynamic content, can be added to the page. There are several different types of solutions to this problem, and Freebok uses one of the simpliest (yet powerful) method available.

Freebok uses a template engine called Velocity ( i ) for generating dynamic content. Velocity gives us the ability to add variables and simple commands to HTML pages. In practise you don't even have to know the meaning of the commands, but you can make the guestbook page layout with your favourite page editor, and cut and paste the required commands from the Cut and Paste ( i ) page. If you want to use the full potential of Velocity it's worthwhile to learn the commands it provides.

How do I use the guestbook template layout?

You can enable Template layout in your guestbook by selecting it as the guestbook layout type in the General Settings (m) section of the Guestbook Management page. When you have selected template as the guestbook layout type, the information in the layout form ( i ) is no longer used.

The first time you enable Template layout in your guestbook a default layout is used. Default Template layout looks roughly the same as the default layout for the Form layout type.

You can change the layout of the guestbook page and 'Sign the Guestbook' page by modifying the HTML code in the Guestbook (m) or Sign page (m) sections of the Guestbook Management screen. You can use the 'preview' button to see how the guestbook looks like without affecting the actual guestbook. The changes are saved and visible in the guestbook only after you have submitted them by using the 'Submit' button.

Reserved characters in the Template layout

Freebok uses a template engine called Velocity to render the output of the guestbook pages that use Template layout. Velocity has reserved some control characters for its own use.

• $ dollar sign
• # number sign

Generally Velocity does a very good job in deciding whether these special characters are meant to be variable references ($variable), directives (#directives), or if they should be directly displayed. In some cases Velocity cannot make the decision and gets confused. In these cases the offending character has to be escaped to let Velocity explicitely know what we want for it to do.

Escaping is done by prefixing the character with the backslash character (' \ ').

For example:
Welcome to channel #freebok
==>
Welcome to channel \#freebok

You'll need to do the escaping only if Velocity can't decide the proper action by itself in which case it will display an error message.

I made some changes to page template. Now the page doesn't work.

Because Freebok needs to use a script engine (Velocity) to render the template page, the guestbook code is not plain HTML. You need to be very careful when modifying the code as Velocity is very strict on the correct format of the code. Even one wrong character in the wrong place might render the whole page broken.

The easiest way to create your own Template layout is to base it on the default template (that you got when you started Freebok) and modifying it one change at a time. You can revert to default layout by emptying the edit box and submitting it. Test each change with the preview button. This way if problems should arise you know exactly where to look for fixes.

Guestbook templates - Cut and Paste

This page contains code snippets that you can use when building your template based guestbook layout. Here you will find the basic Velocity ( i ) code that you will need to use to make your guestbook page usable. Please refer to Available variables when using Template layout ( i ) for an explanation of the used variables and to find out how to further extend the guestbook pages.

If you decide to use the Template layout don't settle for the default black and white, two column layout. Undoubtedly you can do better than just change the guestbook texts, you know that you can do that with the Form layout as well. Template layout gives you complete control over the layout of your guestbook, so you can be as creative as you want.

The example code has been colored in order to improve readability. Velocity directives are in bold and variables are green.

• Guestbook page
• Sign the Guestbook page

Guestbook page

All the example code we present here assume that we are using table with two columns; the question field name is on the left column, and the field itself is on the right column. In practice these codes will be executed once for each message in the guestbook page. Further down this page you can find these snippets used in a full template page. There you'll see how the codes have been wrapped inside a #foreach statement.

Name, email and city

If the visitor gave her email address, we'll add it as 'mailto:' link to the name. If she filled the city field, we'll add it after the name.

#if ($message.email != "")
  #set ($message.name = "<a href='mailto:$message.email'>$message.name</a>")
#end
#if ($message.city != "")
  #set ($message.name = "$message.name, $message.city")
#end
<tr><td align="right" nowrap>Name : </td>
<td>$message.name</td></tr>

Homepage name and address

If the visitor gave her homepage address, we'll check if she also filled the homepage name field. If she gave also the name for her homepage, we'll combine the name and address to single string where the address is used as link. If the address was the only field, we'll use it as the name of the link also. If the visitor gave only the name of her homepage without the address, then we'll display only that.

#if ($message.hpURL != "")
  #if ($message.hpName != "")
    #set ($message.hpName = "<a href='$message.hpURL' target='_top'>$message.hpName</a>")
  #else
    #set ($message.hpName = "<a href='$message.hpURL' target='_top'>$message.hpURL</a>")
  #end
#end
#if ($message.hpName != "")
<tr><td align="right" nowrap>Homepage : </td>
<td>$message.hpName</td></tr>
#end

Text fields (text1, text2, text3)

#if ($message.text1 != "")
<tr><td align="right" nowrap>Age : </td>
<td>$message.text1</td></tr>
#end

Selection fields (selection1, selection2)

#if ($message.selection1 != "")
<tr><td align="right" nowrap>Found : </td>
<td>$message.selection1</td></tr>
#end

Message field

We assume that the message filed as marked as a required field, so in this case we don't need to check if the user has filled the field or not.

<tr><td valign="top" align="right" nowrap>Message : </td>
<td align="left">$message.message</td></tr>

Answer

#if ($message.answer != "")
<tr><td align="right" valign="top" nowrap>Answer : </td>
<td>$message.answer</td></tr>
#end

Date

Also the date field will always be present, as Freebok will fill it automatically.

<tr><td>&nbsp;</td>
<td>$message.date</td></tr>

Guestbook page

[We'll start the guestbook page the same way as a regular HTML
document. If you want the guestbook page to look like the rest of your
site you can use your existing documents as a base for the guestbook
page]

<html>
<head>
<title>Guestbook</title>
</head>

<body bgcolor="white" text="black">
<div align="center"><center>
<table border="0" cellpadding="0" cellspacing="0" width="468">
<tr><td colspan="3"><hr size="1"></td></tr>
<tr><td colspan="3">
<h3>Guestbook</h3>
<p>Welcome to my guestbook</p>
</td></tr>
<tr><td colspan="3"><hr size="1"></td></tr>

[Now that the basics have been defined for the page we can start using
Velocity. As you can see we use the same boring black and white, two
column layout as the previous examples. That's really not what you
want when you use Template layout, is it? So now it's time to be
creative.

To the top of the page we'll add link to your homepage and
information on how many messages there are in your guestbook, and
which ones we are currently viewing. Here we use the variables that
Velocity has made available to us.]

<tr><td><a href="$pageURL" target="_top">Homepage</a></td>
<td>Messages $msgStart - $msgEnd</td>
<td>Total of $msgTotal messages</td></tr>

[Then we'll add navigation links; to the next page in our guestbook,
Sign the Guestbook page, and to the previous page. We'll use the #if
directive to decide whether we need to create the link or if we
should just display the link text without the link. For example, we
will not make a link to the first page of the guestbook if we are
already on it.]

#if ($nextPage)
<tr><td width="33%">
<a href="$CALL_LOCATION/view.html?page=$nextPage">
Next $msgPerPage messages</a></td>
#else
<tr><td width="33%">Next $msgPerPage messages</td>
#end

<td width="34%"><a href="$writeAdd">Sign the Guestbook</a></td>

#if ($prevPage)
<td width="33%"><a href="$CALL_LOCATION/view.html?page=$prevPage">
Previous $msgPerPage messages</a></td></tr>
#else
<td width="33%">Previous $msgPerPage messages</td></tr>
#end
<tr><td colspan="3"><hr size="1"></td></tr>
</table>

[Here we'll start going through the messages on the guestbook
page. #foreach is a Velocity directive that is used to go through the
messages one by one.

Before we display the messages we modify them a bit to better suit our
needs. For example, we use the #if directive to check if the visitor
has given her email address, and if this is the case, we'll add the
address as a 'mailto:' link to the visitor's name. These are
essentially the same code snippets as in the beginning of this page.]

#foreach ($message in $messages)

#if ($message.email != "")
  #set ($message.name = "<a href='mailto:$message.email'>$message.name</a>")
#end
#if ($message.city != "")
  #set ($message.name = "$message.name, $message.city")
#end
#if ($message.hpURL != "")
  #if ($message.hpName != "")
    #set ($message.hpName = "<a href='$message.hpURL'>$message.hpName</a>")
  #else
    #set ($message.hpName = "<a href='$message.hpURL'>$message.hpURL</a>")
  #end
#end

[Now that we have modified the message fields to the way we want them
to be, we can display them. Once again we use the #if directive to
decide whether to display a field or not. If there is an empty value
in a field we will not display it (actually the comparison is:
#if ($field != "") - so we test whether the field is different than empty,
and if it is, we'll display it.

Note that we don't bother to test the fields $message.message and
$message.date as we assume that the message field is configured to be
a required field (you can configure the message field to be optional,
in which case it would be a good idea to include the check). The date
field will always be there because Freebok will fill it automatically
when the visitor submits the message.]

<table border="0" cellpadding="0" cellspacing="0" width="468">
<tr><td width="64" align="right" nowrap>Name : </td>
<td width="388">$message.name</td></tr>

#if ($message.hpName != "")
<tr><td width="64" align="right" nowrap>Homepage : </td>
<td width="388">$message.hpName</td></tr>
#end
#if ($message.selection1 != "")
<tr><td width="64" align="right" nowrap>Found : </td>
<td width="388">$message.selection1</td></tr>
#end
<tr><td width="64" valign="top" align="right" nowrap>Message : </td>
<td width="388" align="left">$message.message</td></tr>
<tr><td colspan="2">&nbsp;</td></tr>
<tr><td width="64">&nbsp;</td>
<td width="388">$message.date</td></tr>
#if ($message.answer != "")
<tr><td colspan="2">&nbsp;</td></tr>
<tr><td width="64" align="right" valign="top" nowrap>Answer : </td>
<td width="388">$message.answer</td></tr>
#end

[That was the last field that we'll display in our guestbook. Add or
remove fields to your liking. You can find out the fields that you can
use by examining the properties of the $messages variable. Remember
to make the same modifications to the Sign the Guestbook page as
well.

Next we'll make a row that will contain the horizontal line that will
separate the messages. After that we use the #end directive to end the
loop that we previously started with the #foreach directive]

<tr><td align="center" colspan="2">
<hr size="1" width="100%"></td>
</tr></table>

#end

[From the #end directive that we see above, Velocity will jump back to
the #foreach directive that we defined earlier. This loop is executed
once for each message in this guestbook page.

The loop ends after it has gone through all the messages. Now the
messages are in the guestbook page in the way that you defined inside
the loop. Depending on your settings there may be from 1 to 25
messages in one guestbook page. If your guestbook contains more
messages than one page can hold, the user can change the page by using
the Previous and Next page links in the top of the page. For user
convenience we'll add the navigation links to the end of the page as
well.]

<table border="0" cellpadding="0" cellspacing="0" width="468">
#if ($nextPage)
<tr><td width="33%">
<a href="$CALL_LOCATION/view.html?page=$nextPage">
Next $msgPerPage messages</a></td>
#else
<tr><td width="33%">Next $msgPerPage messages</td>
#end
<td width="34%"><a href="$writeAdd">Sign the Guestbook</a></td>
#if ($prevPage)
<td width="33%"><a href="$CALL_LOCATION/view.html?page=$prevPage">
Previous $msgPerPage messages</a></td></tr>
#else
<td width="33%">Previous $msgPerPage messages</td></tr>
#end
</table>

[All there is left to do is to end the HTML page properly.]

</center></div></body>
</html>

Sign the Guestbook

The fieldnames that you can use when defining the input fields in this page can be found from the page Creating the 'Sign the Guestbook' page with Template layout. There you'll also find the field properties and some additional tips.

Private message

<tr><td>&nbsp;</td>
<td><input type="checkbox" name="private" value="1">
&nbsp;Private message to the page owner</td></tr>

Text fields (name, email, city, hpName, hpURL, text1, text2, text3)

<tr><td align="right" nowrap>Name : </td>
<td><input name="name" maxlength="64"
type="text" size="40" value="$message.name"></td></tr>

Selection boxes (selection1, selection2)

<tr><td align="right" nowrap>Found : </td>
<td><select name="selection1" size="1">
<option selected value="">- Select -
<option>Search engine
<option>Just surfed
<option>Ad banner
</select></td></tr>

Message field

<tr><td align="right" nowrap>Message : </td>
<td><textarea name="message" rows="4" cols="36" wrap="virtual">
$message.message</textarea></td></tr>

Sign the Guestbook

[The Sign the Guestbook page is substantially simpler that the Read
page. You could create the whole page without using any Velocity code,
but it's better to use it to give default values to the question
fields. Additionally we have included two Velocity tricks to further
improve the page.

Again the layout of this page is far from pleasant. Heavy modification
is needed...]

<html>
<head>
<title>Sign the Guestbook</title>
</head>

[Trick no.1: autofocus() code is added to the body -tag of the
page. This has been explained more closely in the Template tips page.]

<body bgcolor="white" text="black"
#if ($focusField != "")
onLoad="window.document.gbMessage.${focusField}.focus();"
#end
>
<div align="center"><center>
<table border="0" cellpadding="0" cellspacing="0" width="468">

<form name="gbMessage" method="POST"
action="$CALL_LOCATION/sign.html">

[We'll define two required fields; name and the message.]

<input name="nameReq" value="1" type="hidden">
<input name="messageReq" value="1" type="hidden">
<tr><td><hr size="1"></td></tr>
<tr><td>
<h3>Sign the Guestbook</h3>

[Trick no.2: error message. Also this trick has been described more
closely in the Template tips page.]

#if ($error != "")
<p><b>$error</b>
#end
<table border="0" cellpadding="0" cellspacing="0" width="468">
<tr><td colspan="2"> </td></tr>

[Here we'll define a TEXT input field for each question that we want
to ask from the visitor. Additionally we'll use one selection field
and message field that is type TEXTAREA.

Note that the field names that we use here are exactly the same as the
ones we used in the Read the Guestbook page. We are using the Velocity
variables to give default values to the fields. The first time the
visitor comes to this page these variables will contain an empty value
(except the $message.hpURL field, which will contain value
'http://'). When the visitor submits the page and there occurs an
error (e.g. a required field was not filled), the variables will
contain the values that the visitor had entered.]

<tr><td width="25%" align="right" nowrap>Name : </td>
<td width="75%"><input name="name" maxlength="64"
type="text" size="40" value="$message.name"></td></tr>

<tr><td align="right">Email : </td>
<td><input name="email" maxlength="64"
type="text" size="40" value="$message.email"></td></tr>

<tr><td align="right">City : </td>
<td><input name="city" maxlength="64"
type="text" size="40" value="$message.city"></td></tr>

<tr><td width="25%" align="right" nowrap>Homepage : </td>
<td width="75%"><input name="hpName" maxlength="128"
type="text" size="40" value="$message.hpName"></td></tr>

<tr><td align="right">Homepage URL : </td>
<td><input name="hpURL" maxlength="128"
type="text" size="40" value="$message.hpURL"></td></tr>

<tr><td width="25%" align="right" nowrap>Found : </td>
<td width="75%">
<select name="selection1" size="1">
<option selected value="">- Select -
<option>Search engine
<option>Just surfed
<option>Ad banner
</select></td></tr>

<tr><td width="25%" align="right" nowrap>Message : </td>
<td width="75%"><textarea name="message" rows="4" cols="36" wrap="virtual">
$message.message</textarea></td></tr>

<tr><td colspan="2">&nbsp;</td></tr>
<tr>
<td align="right">&nbsp;</td>
<td><input type="submit" value=" Submit ">&nbsp;
<input type="reset" value=" Reset "></td></tr>
</table></td></tr>
</form>
</table>

</center></div></body>
</html>

Guestbook templates - Tips

This page contains some tips and tricks that you can use to further enhance your guestbook page. If you have invented some other great feature using the Template layout, please mail it to us, and we'll include your tip on this page.

• Alternating the background color of the messages
• Error messages on the Sign the Guestbook page
• Autofocus on the Sign the Guestbook page
• Multilingual guestbook

Alternating the background color of the messages

In order to improve readability, it's a good idea to separate the messages in the guestbook from eachother. One popular technique is to use horizontal lines or images between the messages. Another useful trick is to alternate the background color of the messages.

This feature is also available for those who are using the Form layout, so you don't need to switch to Template layout in order to use it.

There are many ways to implement the feature by using the Velocity template language, each of which has their own benefits. In this example we try to keep things simple. We take advantage of the automatic loop counter called $velocityCount that is made available by Velocity when using the #foreach directive. The counter is set to value 1 when to loop starts and it gets increased on each round of the loop.

We test if the value of the loop counter is divisible by 2 (by using the remainder '%' operator ( i ) and define different color for odd and even numbers. Now we have the color defined and we can assign the value to the bgcolor property of the HTML table element.

It's easy to expand this example. You could develop it further to use more colors or to use background images instead of colors. For simplicity the following example uses only two colors and a minimalistic #foreach loop. The actual code is marked with bold font.

#foreach ($message in $messages)

 #if ($velocityCount % 2 == 1)
  #set ($bgColor = "#C0C0C0")
 #else
  #set ($bgColor = "#A0A0A0")
 #end

 #if ($message.email != "")
  #set ($message.name = "<a href='mailto:$message.email'>$message.name</a>")
 #end

 <table bgcolor="$bgColor" border="0" cellpadding="0" cellspacing="0">
 <tr><td align="right">Name : </td>
 <td>$message.name</td></tr>

 <tr><td valign="top" align="right">Message : </td>
 <td align="left">$message.message</td></tr>
 </table>

#end

Error messages on the Sign the Guestbook page

When a user submits a message by using the Sign the Guestbook page, there may occur an error (e.g. there is an active time limit or the guest didn't fill a required field). When an error occurs the user is directed back to the Sign the Guestbook page and a message describing the problem is set to a variable called $error. You should display the variable when it's set, so that the visitor knows what she or he must do in order to get the message through. Here is one way to display the error message:

#if ($error != "")
<p><b>$error</b>
#end

Autofocus on the Sign the Guestbook page

If you have defined required fields ( i ) to your guestbook and the visitor fails to fill that field, Freebok will redisplay the Sign the Guestbook page with an error message. Additionally the variable $focusField will contain the name of the field ( i ) that was missing. You can use this variable to generate a JavaScript code that will automatically activate the missing input field when the page is redisplayed:

<body bgcolor="white" text="black"
#if ($focusField != "")
onLoad="window.document.gbMessage.${focusField}.focus();"
#end
>

The code checks whether there is value in the $focusField variable. If the variable is set, it is used to build a statement that will use .focus() function on the corresponding input field. Please note that the example code assumes that the input form has been named as 'gbMessage'. Note also the use of '{ }' characters which are use in order to separate the variable '$focusField' from the rest of the JavaScript code (so called Formal Reference Notation).

Multilingual guestbook

If your homepage is available in more than one language and you would like to use a single guestbook for all of them, you may want to make the guestbook multilingual too. This way the guestbook will be in the same language as the page that the visitor was browsing. Obviously the messages in the guestbook will be in the language that the visitors have used, so you may want to write some guidelines in the Sign the Guestbook page if you wish to enforce some particular practice regarding the language of the guestbook messages.

Multilingual guestbook can be implemented by using the free variables ( i ) $add1 or $add2. You can use the variable to define the language that will be used. The variable will be transferred from one guestbook page to another in the guestbook URL address. This means that you will also define the initial language in the guestbook URL.

For example, if the Freebok guestbook (book ID = 'freebok') had the language choises 'en' for English and 'fi' for Finnish, and the variable $add1 was used to carry the language information, the guestbook link would be as follows (please note that you need to make the appropriate ?add -changes to the Sign the Guestbook links as well):

English page:
http://www.freebok.net/books/freebok/view.html?add1=en

Finnish page:
http://www.freebok.net/books/freebok/view.html?add1=fi

Now that the language that the user wants to see is known, you can use that information in the HTML code of your guestbook. Once again there are many ways to implement a feature using the Velocity template language, and we'll use a simple solution in this example. Often the simplest solution is the best, albeit not always the coolest one.

We'll implement the multilingual guestbook by defining variables for all text in our guestbook. This is a good approach especially if you have several languages to support.

In the following example code we have translated only couple of words and phrases. Your language definitions will propably be quite a lot longer than this. It's good to notice that the default language in this example is English. English will be used if there is no ?add1 parameter defined, and also in the case where there is no language supported for the requested parameter (e.g. user requests the guestbook with parameter ?add1=sv in our example. This shouldn't happen too often if you have written your links correctly, but as the user can alter the parameter in the URL field, it is good to have a reasonable default value).

[add this code to the beginning of your template page]

#if ($add1 == "fi")
  #set ($title = "Freebok vieraskirja")
  #set ($main = "Pääsivu")
  #set ($next = "Seuraavat")
  #set ($msgs = "viestiä")
#else
  #set ($title = "Freebok guestbook")
  #set ($main = "Main page")
  #set ($next = "Next")
  #set ($msgs = "messages")
#end

#if ($add1 != '')
  #set ($param = "add1=$add1")
#else
  #set ($param = "")
#end

<html>
<head>
<title>$title</title>
. . .

In the example we have defined a variable $title to hold the text for the title of our guestbook. The #if directive checks the $add parameter and assigns either Finnish or English language to the variable depending on the parameter. All the language dependent words and phrases are replaced similarly.

Now that you have all the language resources defined as variables you use the variables in places where you would normally type the corresponding text, as demonstrated in the <title>$title</title> code.

There is still one thing to do. You will need to make sure that the language definition will be preserved from guestbook page to another. As already said, the language parameter is coded to the URL of the guestbook, so a good solution might be to define a $param variable that will hold the language URL parameter. You will then use this parameter in all(!) guestbook links inside your guestbook page. In the following example code please note the use of the $param variable in the end of the URL. Also, be careful to use the correct parameter separator: '?' with the first parameter and '&' for the rest.

[add to the beginning of the guestbook's template page]

#if ($add1 != '')
  #set ($param = "add1=$add1")
#else
  #set ($param = "")
#end

. . .

[$param added to all guestbook links:]

. . .
#if ($nextPage)
<tr><td width="33%">
<a href="$CALL_LOCATION/view.html?page=$nextPage&$param">
$next $msgPerPage $msgs</a></td>
#else
. . .

If you are not using a separate 'Thank you' page, the visitor will be redirected back to the guestbook page after she or he has signed the guestbook. In order not to lose the language definition in this case, you will need to include the $param definition to the action parameter of the input FORM in the 'Sign the Guestbook' page. You can do this as follows (also remember to include the code to define the $param variable in the 'Sign' page the same way we did in the 'Read' page in the previous example):

. . .

<form name="gbMessage" method="POST" action="$writeAdd?$param">

. . .

Available variables when using guestbook Template layout

This help section is meant for those who want to create the whole guestbook page by themselves. The Cut and Paste ( i ) page contains code snippets that you can use in your guestbook if you want to get a bit easier.

Guestbook page

All the variables that are available to you when you create your guestbook page are described below.

Creating the 'Sign the Guestbook' -page with Template layout

Create a form as follows:

<form method="POST" action="$writeAdd">

In form you can use the following INPUT -fields:

You can set the default values for the fields (excluding the selection fields) by referencing the field names. e.g.

<input name="name" maxlength="64" type="text" size="40" value="$message.name">

When the user first comes to the write page, all the values are empty. When the form is submitted and there occurs an error (a required field was missing, or some other error), the field values are set to whatever the user wrote to them, so he/she doesn't have to retype them.

Required fields

If you want that the visitor has to fill some question fields, add the field names to the form as hidden fields as follows: Field name+"Req", value="1".

E.g. The field 'name' is required:

<input name="nameReq" value="1" type="hidden">