Help for gbookplus Plugin

Content

1. Setup

1.1 Where I get the Guestbookplus?

The Guestbookplus plugin is available at cmsimpel.nl. The actual version is 2010 (august).

1.2 What must be done before you install?

Best to do is install cmsimple XH. You know where to find that.

1.3 How to install the Guestbookplus?

Download the zip-file from cmsimpel.nl and unzip it into the folder .\cmsimple\plugins. Take care to check the "use folder names" option while unzipping. After unzip you should have the following structure:

 +-plugins
 | +-gbookplus
 | +-config
 | +-content
 | +-css
 | +-help
 | +-images
 | +-languages

After this you can start CMSimple and login into the Admin area. Now you should see the Plugin in the list of all plugins. If you don't see it, something is wrong (check the folder structure).

1.4 How to call the Guestbookplus?

1.4.1 Installation and Build in to your Website

First you should create a own main page with <H1>, or subpages with <H2> or <H3>, as a container for the Guestbookplus..Plug the Guestbookplus in your CMSimple-page by adding the line

#CMSimple $output.= GBlist();#

#CMSimple $output.= GBlist(cFilename);#

into your text, directely following to the heading. You can copy the text line directly from the description here. But please take care to control the HTML-code directly and delete, if necessary, the < FONT >-tags. The result should exactly look like shown above. If it looks like the following line

<font size="2">#</font>CMSimple $output.= GBlist();<font size="2">#</font>

you should delete all <font> tag, because these tags are causing errors.

Specifying the filename cFilename is optionally. The specified filename should not contain any language shortcut or an file extension, both will be added automatically. If you specify as cFilename the string 'MyGuestbookplus', there will be a file with the name 'MyGuestbookplus_en.txt' used, if you use English as language. The splitting of the Guestbookplus into a own part for each language can be switched off by setting the option common_Guestbookplus to True. In this case only one Guestbookplus will be used for all languages.

If you specify no filename, the gbookplus plugin will use the default string 'Guestbookplus' as first part of the filename.

Attention:
Don't forget to disable the default Guestbookplus of CMSimple in the settings. Otherwise spam will fill anyway the Guestbookplus datafile (but without being visible).

1.4.2 Calling outside of Menu Structure

If you want to integrate the gbookplus Guestbookplus in the same matter as the default Guestbookplus of CMSimple, this means not visible in the menu structure, but instead of that visible as separate link in the navigation area, you have to the following steps:

First you have to create an own page for the Guestbookplus as described under 1.4.1. For hiding the Guestbookplus in the normal menu/navigation structure, the addition command hide is necessary. So the following lines must be inside of the Guestbookplus page:

#CMSimple hide #
#CMSimple $output.= GBlist(); #

As next step, you have to insert the link to the new Guestbookplus into the template file. You have to exchange the following code

<?php echo Guestbookpluslink(); ?>

with

<a href="index.php?Contact:Guestbookplus">Guestbookplus</a>

The path specified after "index.php?" is the menu structure you have choosen for storing / organizing the Guestbookplus in your website. In this example the main menu is called Contact and the submenu, where the Guestbookplus page is called has the name Guestbookplus. After this steps the default Guestbookplus from CMSimple will be no longer shown and instead the gbookplus Guestbookplus will be called.

1.4.3 Calling in Member Area (Memberpages)

If the gbookplus Guestbookplus should be available in a member area, where only logged in members are having access, the following steps have to be proceeded:

First an own page, as described under 1.4.1, has to be created for the Guestbookplus. For hiding the Guestbookplus page in the normal menu structure (it should be visible only for members) the additional command hide is necessary:

#CMSimple hide #

As next line the commands for the memberpage and gbookplus plugins must be entered. Both command must be specified in one #CMSimple ... # command:

#CMSimple $output.=memberspage("Access denied","0"); $output .= GBlist(); #

This means, first the access will be checked and if successful, the Guestbookplus will be shown.

1.5 Can I use multiple Languages?

gbookplus supports the use of multiple languages. There are no specific commands necessary. gbookplus detects automatically which language is currently used and choose the dependent Guestbookplus file.

At the moment the plugin comes with the following languages:

Danish, many thanks to Per Kongebro
Dutch, many thanks to Gerd Xhonneux
English
Finnish, many thanks to Ahti Kurki
French, many thanks to Gerd Xhonneux
German
Hungarian, many thanks to Zsolt Kádas
Italian, many thanks to Sandro Cavalieri Foschini
Norwegian, many thanks to Tobias Michel
Portuguese, many thanks to JoaoVr
Slovak, many thanks to Martin Sereday

If your language is not listed above, you can create your language as well. Just copy an exiting language file (e.g. en.php), rename this file according to the used language and translate the texts inside.

At this point I like to say "Thank you very much" to all the people, which have sent their translations to me!

Please feel free to send new languages files to me. I will include them in the very next setup, the author will be mentioned!

1.6 Configuration

The gbookplus plugin is individually adaptable to the desired functionality and layout by several settings.

The following settings are available:

date format:
time format:
captcha:
image captcha:
ucase captcha:
ask for email:
ask for website:
ask for title:
mandatory title:
mandatory email:
remove html:
items per page:
num of pages:
info mail:
thank mail:
thank sendfrom:
new entries:
spam words:	old, please don not use any longer
show creator:
show narrowlink:
show email:
show website:
show ip addr:
store ip addr:
use smileys:
blocked words:
blocked IPs:
blocked domains:
blocked countries:
common Guestbookplus:
quarantine time:

date format: Use this field for defining how the date of the message should be displayed on the screen. The values of the field are the same as the date() function of PHP allows.

time format: Use this field for defining how the time of the message should be displayed on the screen.The values of the field are the same as the date() function of PHP allows. The date() function of PHP is used as well for date values as well for time values.

captcha: The captcha code is a string combinations of five characters and number, which must be entered by the user, if this setting is set to true. Does this value not match with the original captcha code, the new Guestbookplus entry will not be stored. This setting avoids most of all spam entries. Possible values for this field are True or False.

image captcha: This option is for defining if the captcha code should be displayed as image or as normal text. Due to spamming attacks using an image is highly recommended. Possible values for this field are True or False.

ucase captcha: This option is for defining wether the captcha code should contain upper or lower case characters. Sometimes (e.g. with some fonts) the lower case display is better readable. Possible values for this field are True or False.

ask for email: This field defines if the user will be asked for his e-mail address or not. Possible values for this field are True or False.

ask for website: This option is for setting up if the user should be prompted for his website / homepage or not. Possible values for this field are True or False.

ask for title: This option defines if the user will asked for a title of his message or not. Possible values for this field are True or False.

mandatory title: This option defines if the user must enter a value into the field Title or not. This option can be set to True only when the option ask for title is set to True too. Possible values for this field are True or False.

remove html: This field defines if maybe contained HTML code should be removed or not. Possible values for this field are True or False. Normally it is strongly recommended to set this option to True for removing HTML code. This avoids bad links to websites which are containing viruses, trojans and other ugly stuff.

items per page: With this option the administrator can define how many items per page should be displayed. Are there more entries in the Guestbookplus, the plugin will split the content onto so many pages as necessary.

num of pages: This setting specifies how many page links will be shown left and right close to the actual page number in the navigation bar at the bottom of the Guestbookplus.

info mail: This field specifies to whom an info e-mail, that there is a new entry in your Guestbookplus, should be sent. In this field you can specify more than one e-mail address. All e-mail addresses must be separated by a comma.

thank mail: This option defines if the visitor which has created a new message in the Guestbookplus will get an automatically send mail to thank him. Possible values for this field are True or False. The text of the thank mail is available in the section Language and can be modified as you prefer.

thank sendfrom: This field contains the e-mail address which will be shown as sender.

new entries: This option allows to switch on and off the functionality of creating new Guestbookplus entries. Possible values for this field are True or False. This option can be used eg. when your Guestbookplus is under maintenance or your have some other problems. Normally this option should be set to True.

spam words: Since version 0.8 this option is no longer used. Use instead the option blocked words.

show creator: At the bottom of the Guestbookplus will be a link to the author shown. If this text should not be shown this field must be set to False. Switching off this display is only possible after contacting the author. Possible values for this field are True or False.

show narrowlink: This option allows to switch on or off the links to previous "< Back" and next "Next >" page. Possible values are True or False.

show email: This options specifies if the e-mail address of the Guestbookplus visitor will be shown or not. Possible values for this field are True or False. This option has no influence if the e-mail address will be stored or asked from the user (see also ask_for_email) or not. It's only for switching on/off the display.

show website: This option allows to define if the address of the homepage will be shown or not. Possible values for this field are True or False. This option has no influence if the homepage address will be asked from the user (see also ask_for_website) or not. It's just for switching the display on/off.

show ip addr: This option specifies if the ip address of the visitor will be shown or not. Possible values for this field are True or False. This option has no influence if the ip address will be stored (see store_ip_addr) or not. This setting is just for switching the display on/off.

store ip addr:This option allows to define if the ip address of the visitor will be retrieved and stored or not. Possible values for this field are True or False.

use smileys:This options enables or disables the support for using smileys. If this option is switched on on the upper right corner of the message field a toolbar with the available smileys will be displayed. If the user clicks on one of the smileys the depending code will be copied into the message field. Possible values for this field are True or False.
Hints:
The smileys will be displayed in the message field in the common used notation like :-) oder 8-), but internally they will be stored as a describing code. This means the smiley :-) will be internally :smile: or the smiley 8o will be internally stored as :eek:. This has the advantage to support also smileys which are containing control characters which would be otherwise unsupported.
The detection and online conversion of smileys is everytime active. This means: If the smiley :-) was once a time used and stored internally as :smile:, the visitor of the Guestbookplus will see independent of this setting everytime the graphical smiley.

List of supported smileys:

Icon	User input	Internal coding
	:-) :)	:smile:
	:-))	:happy:
	:-D :D	:biggrin:
	;-)	:wink:
	8-)	:cool
	:P	:tongue:
	:rolleyes:	:rolleyes:
	8o	:eek:
	?(	:confused:
	:-( :(	:frown:
	;-(	:crying:
	X(	:mad:
	:->	:evil:

blocked words: This field contains a list of all words, which will be used to identify the Guestbookplus entry as spam. Contains a message words, which are classified as spam, this message will be not stored and a hint will be displayed instead.
This option is used on creating new entry in the Guestbookplus as well as on importing an old Guestbookplus. Regular expressions are allowed.

blocked IPs:This option allows to block visitor by their IP address. If the IP address matches the specified range, the new message will not be stored and a hint will be displayed instead. The specification can be a single IP address line 127.0.0.1 (=localhost) or a IP range like 192.168.0.1-192.168.0.255.

blocked domains: With this option it is possible to domains or part of domains which should be used for denying the access. If the search string matches, the entry will not be stored and a hint will be displayed instead. Multiple search stings are allowed and must be separated by the character |. Regular expressions are allowed.

blocked countries: With this option you can block visitors from a country by specifying its top level domain. There are multiple entries possible, separated by the character |. Regular expressions are allowed.

Hint:
For using this option, the package IPFILES must be installed. For installing the package the file ipfiles.zip must be unzipped in the directory include. This package must be downloaded separately.

common Guestbookplus: This option allows to specify that for all languages only one common Guestbookplus has to be used. Possible values for this field are True and False.

quarantine time: With this option it ios possible to define, if a new entry should be displayed immediately or after a specified time is gone. The value for the quarantine time is calculated in hours. Until the quarantine time is expired, the text $plugin_tx['gbookplus']['txt_quarantine_notice'] will be displayed. During this time the webmaster has the oportunity to check the entry. When the time is expired, the Guestbookplus entry will be displayed. The value 0 switches off this function.

1.7 Adapting the Layout

The layout, eg. the used colors and fonts of the Guestbookplus, will be basically defined by the settings stored in the file stylesheet.css in the folder css. In this file all colors, fonts and font sizes for the Guestbookplus are defined there. There are four different color definitions already predefined: Blue, yellow, gray and green. These definitions can be used easily just by renaming the files, eg. rename the file stylesheet.green.css into stylesheet.css to use the green color definition.

According to these color definitions the gbookplus installation contains also matching smileys. The smileys with the different colors are stored under the folder images in the subfolders blue, green and yellow gespeichert. To use one of these smiley sets just copy the content in the folder images. If you are using eg.the stylesheet yellow, so have to copy the smileys from the folder yellow one level higher in the folder images, for using yellow smileys.

The stylesheet file can be modified of course. The entries have the following meaning:

Class	Description
td.gbtitle	Formatting of title bar
td.gblightline	Formatting of a light = even line (lines 2, 4, 6, 8, ...)
td.gbdarkline	Formatting of a dark = odd line (lines 1, 3, 5, 7, ...)
span.gbdatetime	Formatting of date and time
div.gbname	Formatting of visitor name
span.gbmessage	Formatting of message text
input.gbcaptcha	Formatting of captcha text field
input.gbtextbox	Formatting of text fields
input.gbmsgbox	Formatting of message box

1.8 How to import an existing Guestbookplus?

Since version 0.6 of gbookplus plugins there is the function available at the section "gbookplus Data". This function allows to import a default Guestbookplus of CMSimple into the gbookplus Guestbookplus. With this function you will not loose messages, stored in your old Guestbookplus, when switching to gbookplus plugin.

For importing a CMSimple Guestbookplus, please click the button . The following pages offers several options. These options can have heavy influence to the success and quality of the following import. The Guestbookplus of CMSimple is storing all messages directely as HTML text. Therefore it is quite complicate to detect, where eg. the message text or where and how the author or the date is stored

The following options are available:

Save-Options: The default setting is Append to gbookplus file . When you choose this option all items of the old Guestbookplus will be append automatically to the new Guestbookplus on importing the Guestbookplus. Contains your new gbookplus Guestbookplus only some test entries, which should be deleted anyway, you can choose the option Overwrite existing gbookplus file . If you choose this option all entries of the gbookplus Guestbookplus will be overwritten with the Guestbookplus entries of the CMSimple Guestbookplus..

Conversion Options: The option Use server name as username replace the name of the user with the name of the server. This can by helpful eg. when the recognition of the username doesn't work in any cases. or the name of the user should not be shown.

The option Use Spam filter enables the filtering of all new imported entries for spam. All texts defined in the field 'Spam Words' will be compared with the Guestbookplus message which will be imported. If a text matches with a message, this message will be skipped and not imported.

Use the option Scan Format for defining which date and time format was used for storing these values. These settings cannot be read automatically. Therefore you have to specify them manually.
Possible values are e.g.:
%s, %d. %d. - if the date format is like March, 13. 2006
%d.%d.%d - if the date format is like 24.03.2006

The option Parameter order defines, the order of the values for day, month, year, hours, minutes und seconds. The number 1 is for the day, 2 for the month, 3 for the year, 4 for the hours, 5 for the minutes and 6 for the seconds.

The option Value for Posted allows to change the predefined value of the field 'Posted'. This is necessary e.g. if you're using CMSimple Plus which adds in the source code the additional string ' am ' to the field 'Posted'. In this case you have to add the string ' am ' at the end of the option 'Value for Posted'.

Other Options: The Debug Mode shows addtional output during the import. This can be helpful on errors or not exactly recognized data.

Info: The fields Used Date Format and Used gbookplus language file are shown just for information and cannot be changed.

When you have set up all settings and you're sure to import the CMSimple Guestbookplus, press the button .
If not press to return to normal editor of the gbookplus Guestbookplus file.

Importing the original Guestbookplus may take some time. Please wait until a summary of the import is shown. As last step of the import you have to press the button to finish the import. The new content of Guestbookplus will be shown in the textbox and can be edit, if necessary.

1.9 What is the Purpose of the Function Reorg?

Since version 0.7 there is the function available in the administration. This function allows to reoganize the Guestbookplus file. There will be two things corrected by the function:

If the character /// will occure multiple times, it will be removed
Simple smileys, like eg. :-) will be converted to the correct internal kind eg. :smile:

The function Reorg will correct everytime only the Guestbookplus file of the actual language. If you're in the english branch of your website, only the english Guestbookplus file will be corrected. For reoganizing eg. the german Guestbookplus file, please logout, switch to the german branch, go to into the administration - gbookplus - and start the function reorg once again.

It is highly recommended to backup the Guestbookplus file before running the reorg function!

2. FAQ

FAQ = Frequently Asked Questions (and the answers)

2.1 Frequently Askes Questions

How to install the Guestbookplus?
How to import the default Guestbookplus of CMSimple?
How to create a new Language?
How to protect against SPAM?
How to avoid < SCRIPT > or < HTML > in the entries?
How to change the colors of the Guestbookplus?
How to change the fonts of the Guestbookplus?
How to display the date and time information?
How to use mail notification?
Why do I need to switch off the Guestbookplus?

2.2 Questions & Answers

Q: How to install the Guestbookplus?

A: A Look in this helpfile or search teh forums fo cmsimple.

top

Q: How to import the default Guestbookplus of CMSimple?

A: The default Guestbookplus of CMSimple stores all entries directely as HTML in the Guestbookplus file. This causes that logical structures are nearly not existing, eg. to detect where is the name stored or where does the message start and where it ends
Since version 0.6 the gbookplus plugin has a new function to import existing Guestbookpluss from CMSimple. To start this function, please go to the administration section and start there the import routine. For a detailled description how to import and which settings are necessary, please take a look to the documentation of the installatione.

top

Q: How to create a new Language?

A: If you want to offer your website in multiple laguanges, surely the Guestbookplus and its entries should support the different languages as well. The plugin gbookplus offers you this functionality. It creates for each language its own Guestbookplus file. Each Guestbookplus file ends with a two character code, representing the containing language. For example the english Guestbookplus has the filename Guestbookplus_en.txt, the german one the filename Guestbookplus_de.txt and so on.
A general description, how to use multiple languages with CMSimple you will find in the CMSimple manual.

top

Q: How to protect against SPAM?

A: Guestbookpluss are often the target of spammer. Mostly so called bots - automatically working programs - are used to create the spam entries. To avoid automatic creating of entries gbookplus has the option to use a Captcha. This means for each new entry a code of characters and numbers will be created. This code is displayed on the screen and must be reentered by the user as aprovement. Most of the bots can't do this, with the result no entry is created.
The gbookplus displays the approvement code (=CAPTCHA) if the option is set to captcha = True. The captcha is dynamically and individually created for each user.
Another possiblity for spam protection is to use the options blocked_words, blocked_IPs, blocked_domains and blocked_countries. With this options manually created spam can be avoid too.

top

Q: How to avoid < SCRIPT > or < HTML > in the entries?

A: I fyou set the option remove_html = True, gbookplus will remove alle HTML code in the text. These codes are
- Formatting (bold, italic, ...)
- Links (a href)
- Scripts (script)
Therefore no unexpected links or hidden code can be stored in your Guestbookplus entries.

top

Q: How to change the colors of the Guestbookplus?

A: All color definitions for gbookplus are stored in the css file "stylesheet.css", located in the folder "/plugins/gbookplus/css". In this folder there are three additional css files which are containing alternative color definitions. But only the file with the name "stylesheet.css" is used. If you like to use one of the other css files, please rename the choosen one to "stylesheet.css".
If the predefined colors doesn't match to your website, please feel free to modify the css file.

top

Q: How to change the fonts of the Guestbookplus?

A: All font definitions are stored in the css file "stylesheet.css", located in the folder "/plugins/gbookplus/css". Changes of the text layout (eg. font, font size etc.) can be made in this file.

top

Q: How to display the date and time information?

A: The format for date and time can be set up to several formats. The default settings are having the following meaning:

Date format d.m.y
d = display day with leading zero, followed by a dot ".",
m = display month as number with leading zero, followed by a dot "." and at least
y = display the year as two-digit number.

Time format H:i:s
H = display hours in 24 hours format with leading zeros, followed by ":",
i = display minutes with leading zeros, followed by ":" and at least
s = display the seconds with leading zeros.

For more information please see PHP Online Documentation.

top

Q: How to use mail notification?

A: Immediately after successfully storing of a Guestbookplus entry, a info mail to the webmaster can be send. The mail address of the webmaster must be specified in the configuration under info_mail. The e-mail service must be setup by your web provider in the PHP configurations.

Tipp:
Whe you specify in the field info_mail multiple mail addresses, the info will be sent to all of them. The mail addresses must be separated by a comma.

top

Q: Why do I need to switch off the Guestbookplus?

A: In spite of all protection, it can happen a spammer will fill your Guestbookplus. If you want to switch of creating of new entries for some time, use the configuration new_entries = False to switch off the Guestbookplus.

top