Documentation Guestbook Script

Thank you for your interest in our Guestbook Script. We recommend to read this documentation carefully.

Introduction

The script has been configured in a way that makes it ready to use. After uploading all script files to your web server by FTP and running the database table installation routine you can work with the script. When you intend to edit the script you should do that step by step. After each change you should run the script to monitor the effects. Doing so enables you to know what change causes an error.

The HTML templates of the script have been generated by the specifications of XHTML 1.0. HTML tags like <br> or <input> contain an ending slash (<br /> or <input type="text" name="feld" />).

How the script works

The script works like a classic guestbook script. Visitors of your website can read an entry list - last entry first. The visitor can sign the guestbook by using a form.

The administrator can edit and delete guestbook entries. The admin can login via login.php by using the database access data (username and password). After logging in each entry will be expanded by additional information such as IP address and browser and the delete and edit links as well.

Top

Set up and configuration

The file "config.php" is the configuration file of the script. To edit the settings open the file in a text editor (i.e.: Wordpad under MS Windows). The following variables can be edited:

$language     You can set here the language. Enter the abbreviation that is used in the language file name that is stored in the directory "languages" ("en" in languages.en.inc.php and "de" in languages.de.inc.php).

$results_per_page     This variable contains the number of guestbook entries per page. In case the number of entries is higher than the number of results per page the script displays links to navigate between the guestbook pages. You can leave this variable empty and display all entries on one single page.

$direct_page_links     In case the guestbook has a high number of entries the link list to the guestbook pages can get quite long. Therefore, you can define the number of links you want to be displayed. I.e. if you have 20 guestbook pages you will get the following direct link list:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

You could set a limit of 9 links. All numbers after 9 would be replaced by dots (can be changed within the HTML template).

1 2 3 4 5 6 7 8 9 ...

The link display would be changed by page 6:

... 2 3 4 5 6 7 8 9 10 ...

Tip: You can test this behavior by doing some test entries. Set the numbers of entries per page to 1.

$show_error_messages     The default value of this variable is set to "yes" by default so during the configuration process you will get error messages and hints that help you to install the script. Once the script configuration have been finished you can set those system messages off because it is not necessary to give extern visitors a view inside the system.

$path['templates']     This file contains the path to the directory where the HTML template are stored.

$file[]     All $file[] variables contain template file names. Those template files are described in the chapter "HTML Templates".

The following variable $database contains the MySQL access data. You will get those access data when you create a database or ask your web space provider. Description of the $database variables:

$database['host']     Name of the database server, i.e.: localhost.

$database['name']     Name of the database.

$database['user']     Username of the database.

$database['pass']     Database password.

$database['prefix']     To tell apart the guestbook script tables from the existing ones you can add a prefix to the database table names.

$add_text     You can add further values, text, variables or other content to this variable. That content can be displayed in the HTML templates by using markers/placeholders within curly brackets { and }.

If you want to add your own values to the variable $add_text please follow the pattern from the example entries.

$add_text = array(

                    'txt_additional' => 'Additional',
                    'txt_more'       => 'More'

                  );
          

The first part of each entry is the name of the placeholder. In case you want to use the value of 'txt_addition' in your template enter the name of the entry with curly brackets - {txt_addition}. The name must not contain white spaces or special characters. Only allowed is the _ .

   

Top

Upload script files to web server

Create the following folders on your web server (with the most FTP clients you are able to copy the hole script with all folders in one go):

/guestbook/
/guestbook/inc/
/guestbook/languages/
/guestbook/templates/

Copy all files to their corresponding folder. Image files (.gif, .jpg, .png) have to be uploaded in binary mode. Every other files have to be uploaded in ASCII mode (text mode).

Top

Installation

After uploading the script files to the web server open file "index.php" in your browser. Since the database tables have not been installed yet an installation page will be called automatically. However, you need to enter the MySQL access data in the file "config.php" in the first place. You will get those access data when you create a database or ask your web space provider. Description of the $database variables:

$database['host']     Name of the database server, i.e.: localhost.

$database['name']     Name of the database.

$database['user']     Username of the database.

$database['pass']     Database password.

$database['prefix']     To tell apart the guestbook script tables from the existing ones you can add a prefix to the database table names.

When you have entered all data and uploaded all updated files you can install the database tables. When you first run the Guestbook Script you will get an installation page. Click on the green submit button. After a successful installation the script should run.

Top

Form field configuration

The file "form_config.php" contains the form field configuration. Each form field will be defined in the following pattern:

$new_form_fields[] = array(
                            'name'       => 'name',
                            'label'      => 'Name',
                            'type'       => 'text',
                            'required'   => 'yes',
                            'value'      => ''
                           );
    

Every form field definition contains certain elements:

name     Enter here the form field name. The name is used by the script and must not consist of white spaces or special characters.

label     Enter here the text you want to display to the visitor. You can place the label by the form field within the HTML template.

type     Type defines what kind of form field you want. You can use:

textarea     Multi line text field.



text     Single line text field.



password     Password field - all entered values are displayed as ***.



radio     Radio button.   

checkbox     Checkbox.   

select     Select menu.   

required     If you set that option to "yes" you make the script requiring an input by the visitor. No guestbook entry will be made until all required fields are filled in. You can leave this option empty ('required' => '').

value     With this option you can define a default value for the form field. This value appears automatically when the visitor opens the form. You can leave this option empty ('value' => '').

If you want to use select menus or radio buttons with different options you can add those options separated by comma to the value element:

'value' => 'Red, Green, Yellow, Blue'

will be:

selected     If you want to use select menus or radio buttons and want to pre-select a value you can use the element "selected". If you want to select the value Green from the example above you need to set 'selected' => 'Green'.

   

Further options

Beside the original script options you can add your own options. Those options will be added to the form field automatically. Possible options would be: maxlength, size, cols, rows, selected, checked. You can also add CSS content like: class, style.

Example:

$new_form_fields[] = array(
                            'name'       => 'comment',
                            'label'      => 'Kommentar',
                            'type'       => 'textarea',
                            'required'   => 'yes',
                            'value'      => '',
                            'cols'       => '20',
                            'rows'       => '10',
                            'style'      => 'padding:5px;'
                         );
    

This form field definition produces a multi line text field ('type' => 'textarea') with the intern name "comment" ('name' => 'comment'). On the HTML page appears the label "Comment" ('label' => 'Comment'). This field is required to fill in ('required' => 'yes'). The visitor have to enter a value to write a guestbook entry. No default value is defined ('value' => ''). The text field has a width of 20 columns ('cols' => '20') and a height of 10 rows ('rows' => '10'). Additionally the field gets a margin of 5 pixel - defined by CSS ('style' => 'padding:5px;').

Example form

To see how the form field configuration works you can take a look at the file "form_config_example.php" where every possible form field has been defined. The corresponding HTML template is "form_detail_example.tpl.html". Open the file "sign_example.php" to see how the form looks in your browser.

Place the form fields within the HTML template

Please open the template "form_detail.tpl.html" in your text editor to see how the form fields are placed.

The form field definition produces automatically two placeholders: {label:...} and {field:...}. The dots can be replaced by the name of the form field, i.e.: {label:name} and {field:name} or {label:comment} and {field:comment}.

The placeholder {label:...} contains the name of the form field that you want to show to the visitor. The placeholder {field:...} contains the HTML code of the form field, i.e.: <input type="text" name="name" value=" " size="30" style="width:350px;" />

The form field names also appear as placeholders ({name} or {comment}) in the template "entry_detail.tpl.html" within the LOOP block . They will be replaced by the values that are stored in the database.

Top

HTML template customization

The directory "templates/.../" contains the files for the layout. You can use HTML and CSS to customize the layout as you wish. The already existing subfolders "derfault" and "simple" are examples how to customize the guestbook.

In case you are using a WYSIWYG editor like Dreamweaver, Frontpage or NetObjects please make sure the software does not make any changes by itself.

The template files contain markers with curly brackets { and } like: {txt_next_page}. These markers will be replaced by its counterparts from the language file "languages/language.en.inc.php". You are free to edit that file and change the words and phrases. You are also free to replace the markers within the template files by real words or put those markers to other positions within the template file. And you are also able to enhance the language file by using the given pattern.

Amongst those word markers exist the so called loops. Similar to HTML tags the two parts (<LOOP ></LOOP>) must not be separated. If you want to alter the position within the template you need to move the hole block.

There are also IF blocks. These are to display or remove parts of the HTML code under certain conditions. The IF blocks can be handled in the same way as the loop blocks.

The different HTML templates

main_layout.tpl.html

This file can contain the layout elements that apply for all pages. All guestbook pages are then using automatically the same layout. You can leave this file empty and define an individual layout for each guestbook page.

The file contains the special placeholder {main_content}. This placeholder will be replaced by the script with the content of the detail templates. This placeholder must not be removed or altered - even if the file shall not contain any layout content.

The main template contains also the placeholder {txt_title} within the title tag (<title>...</title>). That placeholder has been defined in the file "config.php" in the variable $add_text. The used variable $script_title can be defined within the several PHP files (index.php, delete.php, edit.php, login.php, sign.php). Just enter the page title you want.

entries.tpl.html

This file contains the layout of the guestbook entry page. It contains the following elements:

<IF NAME="logged_in">

If the administrator has been logged in, the log out link will be displayed.

{txt_entries} {txt_page} {currentpage} {txt_page_of} {allpages}

These placeholders contain information about number of guestbook pages and the number of the current page.

<IF NAME="previous_result_page">

This IF block contains navigation links.

<IF NAME="page_link_start">
<IF NAME="page_link_end">

If you have limited the number of direct links to the guestbook pages the content of these IF block will be displayed at the beginning or/and the end of the link list.

<LOOP NAME="page_direct">

Within this LOOP block the direct links to the guestbook pages will be displayed. You will get a link list that consists of numbers (1 2 3 4 5 6 7 8 9 ...).

<IF NAME="next_result_page">

This IF block contains navigation links.

{entry_detail}

The detail layout of the guestbook entries are stored in the file "entry_detail.tpl.html".

entry_detail.tpl.html

<LOOP NAME="guestbook_entries">

Within this LOOP block appear the names of the form fields as placeholders (i.e.: {name} or {comment}). These placeholders will be replaced by database values.

sign.tpl.html
edit.tpl.html

<LOOP NAME="message">

This LOOP block displays notes and error messages, i.e. when a required field has not been filled in by the user.

{form_detail}

This placeholder will be replaced by the content of the form detail template "form_detail.tpl.html".

form_detail.tpl.html

The form field definition produces automatically two placeholders: {label:...} and {field:...}. The dots can be replaced by the name of the form field, i.e.: {label:name} and {field:name} or {label:comment} and {field:comment}.

The placeholder {label:...} contains the name of the form field that you want to show to the visitor. The placeholder {field:...} contains the HTML code of the form field, i.e.: <input type="text" name="name" value=" " size="30" style="width:350px;" />

Top

Support

You will find answers to your questions and solutions for your problems with the script in our support forum.

Top

License Information

You can download the script without registration und use it for free. If you want to use the script without the reference to STADTAUS.com, you can purchase the script online (19 US$/19 Euro).

  1. You may re-distribute the script license to a third party.
  2. You can make your own pricing.
  3. A script license applies to a single domain.

Contact: http://www.stadtaus.com/en/

More scripts on STADTAUS.com:

  1. Image Gallery Script
  2. Formmail Script
  3. Tell-A-Friend Script
  4. Schedule Appointments Online
  5. Google Tool
  6. Download Script

Please also visit our project MetaCollection, a guide for webmasters and developers who are in search of CGI, Perl, or PHP script archives.

http://www.metacollection.com/

Top