Location: PHPKode > projects > YapGB - Yet Another PHP GuestBook > docs/themeinfo.txt
IMPORTANT NOTES
~~~~~~~~~~~~~~~
 * Version 0.7.3 adds the ability to log visitors' IP addresses, in order
  to show it a new GB_TAG has been introduced: <!--GB_ENTRYIP-->, it is
  used only in temp_message.html.

 * 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
  <!--GB_CONFIRMCODE-->, 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_SIGNERRORS--> 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:

  <input type="text" name="name" />
  <input type="text" name="email" />
  <input type="text" name="url" />
  <textarea name="message"></textarea>

  to:

  <input type="text" name="name" value="<!--GB_ENTRYNAME--> />
  <input type="text" name="url" value="<!--GB_ENTRYURL-->" />
  <input type="text" name="url" value="<!--GB_ENTRYURL-->" />
  <textarea name="message"><!--GB_ENTRYMESSAGE--></textarea>
  
 * 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_ENTRYID--> GB_TAG but use the new
  <!--GB_ENTRYADMINLINK--> 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 <!--GB_ENTRYADMINLINK-->, two more GB_TAGS have been added:
  <!--GB_ENTRYEMAILLINK--> and <!--GB_ENTRYURLLINK-->, 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:
  <input type="hidden" name="date" value="<!--GB_ENTRYDATEINT-->">
  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: <html></html>, <head></head> and <body></body>.
  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*) <!--GB_ENTRYADMINLINK-->
    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_ENTRYID--> GB_TAG as in previous versions.
  - <!--GB_ENTRYEMAILLINK-->
    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.
  - <!--GB_ENTRYURLLINK-->
    Similar to <!--GB_ENTRYEMAILLINK--> but for entry's URL. This one will try
   to use a gburl.gif image within current theme's directory. This and the
   <!--GB_ENTRYEMAILLINK--> 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).   
  - <!--GB_ENTRYID-->
    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 <!--GB_ENTRYADMINLINK-->
   tag should be used instead.
  - <!--GB_ENTRYEMAIL-->
    This tag is sustituted by the email of the current entry.
  - <!--GB_ENTRYMESSAGE-->
    This tag is sustituted by the message entered by the poster of the
   current entry.
  - <!--GB_ENTRYURL-->
    This tag is sustituted by the url entered by the poster of the actual
   entry (notice that no url could be entered).
  - ( *NEW )<!--GB_ENTRYIP-->
    This tag is used for showing visitors' IPs to the administrator.
    (The IP is only showed when an administrator is logged in, there is no
    option to change this behaviour).

    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.
  - <!--GB_ENTRYDAY-->
    The name of the day (reduced form), e.g.: Sun, Mon, Tue, Wed, etc.
  - <!--GB_ENTRYDAYFULL-->
    Full name of day, e.g.: Sunday, Monday, Tuesday, Wednesday, etc.
  - <!--GB_ENTRYDAYN-->
    Number of the day in month (from 00 to 31).
  - <!--GB_ENTRYMONTH-->
    The name of the month in reduced form, e.g.: Jan, Feb, Mar, Apr, etc.
  - <!--GB_ENTRYMONTHFULL-->
    The complete name of the month, e.g.: January, February, March, etc.
  - <!--GB_ENTRYMONTHN-->
    Number of the month, from 01 (January) to 12 (December).
  - <!--GB_ENTRYYEAR-->
    Year in two numbers format, from 00 to 99.
  - <!--GB_ENTRYYEARFULL-->
    Year in four digits format, e.g.: 2003, 2004.
  - <!--GB_ENTRYTIME-->
    Time in preferred format (defined by the server) without date.
   Generally it looks like "12:19:33".
  - <!--GB_ENTRYDATEFULL-->
    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:
  - <!--GB_TITLE-->
    This tag is sustituted by the title of the guest book as defined in
   $cfgTitle in gbconfig.php.
  - <!--GB_INDEX-->
    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.
  - <!--GB_SITEINDEX-->
    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.
  - <!--GB_ENTRIES-->
    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).
  - <!--GB_PAGINATION-->
    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).
  - <!--GB_INFO-->
    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:
  - <!--GB_TITLE-->
    The title of the guest book defined by $cfgTitle in gbconfig.php.
  - <!--GB_INDEX-->
    Main YapGB file, defined by $cfgGBIndex in gbconfig.php.
  - <!--GB_SITEINDEX-->
    Index for your site. Defined by $cfgSiteIndex in gbconfig.php.
  - <!--GB_ALLOWEDTAGS-->
    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.
  - <!--GB_INFO-->
    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*) <!--GB_CONFIRMCODE-->
    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.
  - <!--GB_ENTRYNAME-->
    <!--GB_ENTRYEMAIL-->
    <!--GB_ENTRYURL-->
    <!--GB_ENTRYMESSAGE-->
    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:
  <a href="javascript:openHelp('BBCode');">BBCode</a>
  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
  <script language="JavaScript"> and </script> tags before </head> and
  <link> 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 <!--GB_ENTRYADMINLINK-->,
  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.
  - <!--GB_TITLE-->
    The title of the guest book defined by $cfgTitle in gbconfig.php.
  - <!--GB_INDEX-->
    Main YapGB file, defined by $cfgGBIndex in gbconfig.php.
  - <!--GB_SITEINDEX-->
    Index for your site. Defined by $cfgSiteIndex in gbconfig.php.
  - <!--GB_INFO-->
    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_ENTRYDATEINT--> GB_TAG for this purpose.
  So every temp_admin.html file should include these lines:

    <input type="hidden" name="id" value="<!--GB_ENTRYID-->">
    <input type="hidden" name="date" value="<!--GB_ENTRYDATEINT-->">
    <input type="password" maxlength="25" size="15" name="passwd">

   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:
    <form action="gbadmin.php" method="post">
  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 <input> tags.
   One of the important differences here is the "special" GB_TAG
  <!--GB_DATEENTRYINT--> 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
  - <!--GB_DATEENTRYINT-->
    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:
    <input type="hidden" name="date" value="<!--GB_DATEENTRYINT-->">

   *** 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:
    <input type="password" name="passwd">
    
   *** END OF DEPRECATED INFO

    This is an example form for temp_modify.html:
    <form action="admin.php" method="post">
    <input type="hidden" name="id" value="<!--GB_ENTRYID-->">
    <input type="hidden" name="action" value="update">
    <input type="hidden" name="date" value="<!--GB_ENTRYDATEINT-->">
    Name: <input type="text" name="name" value="<!--GB_ENTRYNAME-->"><br>
    Email: <input type="text" name="email" value="<!--GB_ENTRYEMAIL-->"><br>
    Url: <input type="text" name="url" value="<!--GB_ENTRYURL-->"><br>
    Message:<br><textarea name="message"><!--GB_ENTRYMESSAGE--></textarea><br>
    <input type="submit" name="submit>
    </form>

   Remember that the temp_message.html does not include the <html></html>,
  <head></head> and <body></body> tags, since the content of this file
  is used to format entries that will be included in the temp_body.html
  file.
  
* temp_signsuccesful.html
   This file is introduced since version 0.6.1, it will be used for showing
  a sign succesful page after the user has signed the guestbook.
   This file can use most GB_TAGS for temp_message.html and for temp_body.html
  files, with the exception of:
  <!--GB_ENTRYID-->, <!--GB_ENTRYADMINLINK-->, <!--GB_ENTRIES--> and
  <!--GB_PAGINATION-->.

   That is all about themes that I can think of at the moment, if you have
  any questions please send them to hide@address.com or use the feedback form
  at YapGB website: http://yapgb.sourceforge.net/. Thanks.
Return current item: YapGB - Yet Another PHP GuestBook