IMPORTANT NOTES ~~~~~~~~~~~~~~~ * Version 0.7 adds the option to require the user to introduce a confirmation code when signing the guestbook, in order to avoid automated signing. This option is enable by default, and requires a new GB_TAG to be included in temp_sign.html file. This new GB_TAG is , it will be replaced by a X characters confirmation code. Version 0.7 has a new error notification method, when the script finds errors in data entered by the user, it reloads the sign page and fills in previously entered data (so that it's not lost as before, annoying the user), and errors are shown using the new GB_TAG, you can place it wherever you want in temp_sign.html file. In order to allow the script to fill signing form fields automatically, name, email and message input fields in temp_sign.html have been change from: to: * Version 0.6.1 introduces the ability to show a succesful page after the user has signed the guestbook. This succesful page is loaded from a new temp_signsuccesful.html file located within current theme's directory (or by default from melody1 theme). If you enable this option, you'll need to add this new temp_signsuccesful.html file to your current theme. * Since version 0.6, temp_admin.html and temp_modify.html won't need to provide a password input field since the new admin login interface will be used instead. Also, temp_message.html shouldn't "build" the administration link by using the GB_TAG but use the new tag instead. This GB_TAG will be replaced by a link to the administration interface of current entry, but only when admin is logged in. This link will try to use a gbadminlink.gif image located in current theme's directory. Besides , two more GB_TAGS have been added: and , these work similar to the administration link but for entries' email and url links. These will look for gbemail.gif and gburl.gif image files within current theme's directory. * Since version 0.5, temp_admin.html theme files will need this line: within the deleteMessage form. Please add it to your current temp_admin.html theme file to be able to delete entries. Themes included with version 0.5 have already been edited to include it. * Also, since version 0.5, the melody1 theme will be taken as the default theme for administration purposes. So, when creating new themes, you won't need to create a temp_admin.html file, if YapGB does not found a temp_admin.html file in the current theme folder, it will look for the one in the melody1 theme (themes/melody1/temp_admin.html), just make sure that melody1 theme has been uploaded :). It works the same for the temp_modify.html theme file. It also works with temp_sign.html, temp_body.html and temp_sign.html, but has been implemented mainly to let you create new themes without needing to create new temp_admin.html and temp_modify.html files :). It has been decided so that when creating new themes, you just need to focus on the user's interface (main and signing pages) by creating (or editing) only temp_body.html, temp_entry.html and temp_sign.html files. THEMES ~~~~~~ YapGB uses a theme system for defining its appearance, this file shows information on themes structure so that you can modify the included themes or create your own. This release includes two themes: 'melody1' and 'gbwhite'. You can download more themes at http://yapgb.sourceforge.net/themes.php YapGB THEMES STRUCTURE ~~~~~~~~~~~~~~~~~~~~~~ All YapGB are stored in its own folder in the themes/ directory, that folder is named after the name of the theme. For example, melody1 theme is stored in a folder called 'melody1' inside the themes/ directory, like this: yapgb/themes/melody1/ YapGB themes consist of five files: - temp_message.html defines the appearance of each entry - temp_body.html defines the appearance of the main page - temp_sign.html defines the appearance of the signing form - *temp_admin.html defines the appearance of the edit/delete entry page (optional) - *temp_modify.html defines the appearance of the modify entry page (optional) - *temp_signsuccesful.html showed after signing the guestbook (optional) You can see two temp files marked as optional, when those files do not exist for the theme, YapGB will use melody1's files. So it is not necessary for you to create those files when creating a new theme. So let's say you want to create your own theme "myTheme", you have to create those five HTML files, and put them in a folder named "myTheme" inside the themes directory, like this: yapgb/themes/myTheme/temp_mess.html temp_body.html temp_sign.html temp_admin.html temp_signsuccesful.html All of these files are HTML standard files, the important thing is that they include "special" tags (GB_TAGS) in the HTML comment style to let YapGB insert data and show the user interface. Let's have a look at each of those five HTML template files: * temp_message.html This file defines the appearance of each entry in the guest book, it'd include generally a HTML table to create the desired structure to show guest book entries. You should take a look at file themes/melody/temp_message.html to have a better view of it. Note that this it not completely a standard HTML file since it does not need any of the following tags: , and . This is because this file is used as a "template" for entries, this "template" will be included in temp_body.html (which does need those HTML tags). The GB_TAGS for this file are: - (*NEW*) This tag will be replaced by a link to the administration interface, but only when administrator is logged in. This link will try to use a gbadminlink.gif image located in current theme's directory. This new GB_TAG has been added for administration purposes and should be used instead of "building" the administration link using the GB_TAG as in previous versions. - (*NEW*) This tag will be replaced by a link to entry's email, but only when the entry email exists. This link will look for a gbemail.gif image within current theme's directory. - (*NEW*) Similar to but for entry's URL. This one will try to use a gburl.gif image within current theme's directory. This and the GB_TAGS have been added so that email and URL links won't be showed when they actually don't exist (in previous versions, those links would appear even when the user didn't provide them because of the way the temp_message.html included them). - This is the id of the current entry. It was used for administration purposes in previous versions (you'd create a link to the admin page using it), but since version 0.6, the new tag should be used instead. - This tag is sustituted by the email of the current entry. - This tag is sustituted by the message entered by the poster of the current entry. - This tag is sustituted by the url entered by the poster of the actual entry (notice that no url could be entered). The next set of tags are related to the date of the entry, there are several of them so that you can define how to show the date of the entry. - The name of the day (reduced form), e.g.: Sun, Mon, Tue, Wed, etc. - Full name of day, e.g.: Sunday, Monday, Tuesday, Wednesday, etc. - Number of the day in month (from 00 to 31). - The name of the month in reduced form, e.g.: Jan, Feb, Mar, Apr, etc. - The complete name of the month, e.g.: January, February, March, etc. - Number of the month, from 01 (January) to 12 (December). - Year in two numbers format, from 00 to 99. - Year in four digits format, e.g.: 2003, 2004. - Time in preferred format (defined by the server) without date. Generally it looks like "12:19:33". - Date and time in preferred format (defined by the server), generally it looks like "01/04/04 12:19:33" for the date Jan 04, 2004 12:19:33. * temp_body.html This template file defines the style of the main guest book web page, generally it shows the title of the guest book, a link to the sign book page, a link for going back to the site and the guest book entries. The GB_TAGS for this file are: - This tag is sustituted by the title of the guest book as defined in $cfgTitle in gbconfig.php. - This tag represents the index file for YapGB, it's defined by $cfgGBIndex in gbconfig.php. This is used so that you can rename the main YapGB file to whatever you want without having to edit anything but the $cfgIndex variable in gbconfig.php. YapGB main file can refer to itself using the $PHP_SELF variable, but if you rename the main YapGB file, other files (like gbadmin.php) wouldn't be able to refer to YapGB main file. - This one is sustituted by the url of your site, so that you can have a link for going back to your web page. This option is defined by the $cfgSiteIndex variable in gbconfig.php. - This is the most important tag in temp_body.html, it will be substituted by the guestbook entries (after being formatted using temp_message.html). - YapGB generates links to every page in the book (the number of pages is defined by dividing the number of entries by the desired entries per page defined by $cfgEntriesPerPage in gbconfig.php). - This tag is sustituted by a "Powered by YapGB" message including a link to YapGB main site. You could edit it to add some info about you or your site, but please keep the "Powered by YapGB" message intact and don't delete it from the included temp_body.html files. Also, please include this tag in every new template you create. This tag exists so that you can place the "Powered by YapGB" message wherever you want. I know it's very easy to remove it so that no YapGB mention appears on your guestbook, but if you wanted to do so, you could do it even if there wasn't this option, as you could edit the main YapGB file by yourself :P. It's just that I decided to have this option so that you can decide where to put this message. * temp_sign.html This is the signing form page, it defines the appearance of the form for adding new entries to the guest book. The GB_TAGS you can use are: - The title of the guest book defined by $cfgTitle in gbconfig.php. - Main YapGB file, defined by $cfgGBIndex in gbconfig.php. - Index for your site. Defined by $cfgSiteIndex in gbconfig.php. - You can use this tag for letting know the user the HTML tags that are allowed in your guestbook. This tag is sustituted by the value of the $cfgAllowedHTML variable in gbconfig.php. - It shows a "Powered by YapGB" message, please don't remove it from the included templates and add it to every template you create. - (*NEW*) It is replaced by a 3 characters code that must be introduced by the user in order to sign the guestbook. This requiremen prevents automated bots (spammers) from signing the guestbook. This new option adds another requirement to temp_sign.html file, it needs another input field named 'codeConfirm', this is where the user will introduce the confirmation code. Take a look at the melody1/temp_sign.html file included with this release. - These are not new GB_TAGS, but are new to temp_sign.html file. These will be used to allow the script to automatically fill in data when there is an error, so that this data is not lost (as happened before), annoying the user (and very likely, making him/her not to post again). Please take a look at the templates/melody1/temp_sign.html file for a better idea of what this file should include. Also in this file, you can see a script (written using JavaScript) used to make sure that the poster writes his/her name, email and a message (it does not check for an url). I recommend you to use this script (or a similar one) so that you can be sure that the poster includes some data. Since version 0.5, melody1 and gbwhite temp_sign.html theme files include a useful function to make the use of smilies more friendly to users. I'd recommend you to include a similar feature in your custom temp_sign.html files if you are planning to enable the use of smilies. Also, you'll note that themes melody1 and gbwhite include a link (in the signing guestbook page) that opens a new window containing some info about BBCode. This link will appear even if you disable BBCode in config.php since it has been included in the temp_sign.html theme file, so you'll need to delete that link yourself if you don't want to enable BBCode. The link is located in temp_sign.html file and looks like this: BBCode It calls a function called openHelp (written in JavaScript) that opens the page gbhelp.php in a new window, this function can be found between the tags before and in temp_sign.html, if you disable BBCode and delete the link above, you can delete this function if you want to :). Besides, if you don't need BBCode and you disabled the hyperlink just mentioned above, you won't need to upload the gbhelp.php to your guestbook folder. * temp_admin.html This template file defines the appearance of the page for deleting an entry. *** DEPRECATED INFO since version 0.6 includes administrator login interface There is no page for introducing the id of the entry to delete, so the only way to access the delete entry page is trough a link to admin.php in the form admin.php?id=entryNumber where entryNumber is the number of the entry to delete. I recommend you to have a look at the themes/melody1/temp_admin.html to have a better understanding of it. *** END OF DEPRECATED INFO Since version 0.6, there is a nevw way of accessing the administration page: by using the link showed by the , and this should be used instead of the previous method. Here is the list of the GB_TAGS available for this file: - All of the tags for temp_message.html They are used so that you can use them to view the message you are just about to delete. - The title of the guest book defined by $cfgTitle in gbconfig.php. - Main YapGB file, defined by $cfgGBIndex in gbconfig.php. - Index for your site. Defined by $cfgSiteIndex in gbconfig.php. - It shows a "Powered by YapGB" message, please don't remove it from the included templates and add it to every template you create. *** START OF DEPRECATED INFO NOTE: this info is deprecated since version 0.6 doesn't need the password to be passed as parameter because of the new administrator login interface. Notice that the password you write in the delete entry page is passed to the admin.php file, so you should make sure that your temp_admin.html include the form fields used by admin.php. *** END OF DEPRECATED INFO Also, the date field (in integer format) needs to be passed to the delete script, you can use the GB_TAG for this purpose. So every temp_admin.html file should include these lines: The important thing here is the name property of these fields, since that is how gbadmin.php recognizes the values passed to it. Also, remember to set the action property of your form to gbadmin.php, like this:
You MUST use the post method for this form (and in general, for all forms in YapGB themes). * temp_modify.html This new file was introduced since v0.3, it is used to define the appearance of the page for modifying an entry. Basically, it is a modified version of temp_sign.html, it just adds the tags for the entries in the value fields of the tags. One of the important differences here is the "special" GB_TAG that is used for storing the date of the entry being modified in integer format (you can see it by looking at the page source code when modifying an entry), so that it can be passed to the update script. It could have been done using another method, but this one is simple and does the job. Here is the list of tags for this file: - All tags for temp_message.html, temp_sign.html and temp_admin.html - Used for passing the date field of the entry being modified. The date field can not be modified, so it is passed using a hidden input field: *** DEPRECATED INFO since version 0.6 includes an administrator login interface. Since this file passes a password to admin.php for confirming the update of the entry, you should remember to include: *** END OF DEPRECATED INFO This is an example form for temp_modify.html: Name:
Email:
Url:
Message: