================================
The Voidspace Python Guestbook
================================
------------------------------
Installation and Use Guide
------------------------------
:Author: Michael Foord
:Contact: fuzzyman AT voidspace DOT org DOT uk
:Version: The Voidspace Python Guestbook v1.4.3
:Doc Revision: 7, 2005/05/23
:Original Date: 2004/12/04
:License: `BSD License`_
:Home Page: `Guestbook Homepage`_
:Sourceforge: `Sourceforge Project`_
:Support and Bug Reports: `Pythonutils Mailing List`_
.. meta::
:description: The homepage of the Voidspace Python Guestbook.
:keywords: python, script, voidspace, website, tool, tools, guest, book, visitor, feedback, guestbook, webmaster
.. contents::
.. sectnum::
What Is the Voidspace Python Guestbook ?
============================================
Guestbook is a Python_ script that allows you to add a 'guestbook' facility to your website. It is fully customisable using HTML templates - so the guestbook can be fully integrated with your website. The entries are saved in a plain text file, for easy editing, and there is a naughty word filter as well. Have a look at the `Default Guestbook Example`_, and the `Voidspace Guestbook`_ which makes use of the HTML templates to integrate with Voidspace_.
Almost every aspect of the appearance can be edited using the templates. Various user settings can also be configured. Full instructions are contained in the template file.
It can email you when an entry is made, and features smilies, anti-spam protection, javascript form validation, and allows a limited set of html in comments. It is regularly improved and updated.
Anyway, enough advertising - I hope you find it useful.
*Fuzzyman*
Downloading
============
There is only one file for this distribution :
* **Python Source (120k)** `Guestbook 1.4 .zip`_
If you have any questions, or need help installing the guestbook, feel free to contact me. This is best done at the `Pythonutils Mailing List`_.
Installing the Guestbook
============================
Guestbook is a straightforward CGI script, so installing it isn't difficult. Even if you're not a Python programmer, the templates can easily be customised with any text editor [#]_. It can then be nicely integrated into any website that supports Python CGIs. It's even possible to host it on a different site, and have it appear to be fully integrated with your main site. (Useful if your current site doesn't host Python and you don't want to move the whole site). The most important thing, is that the server you use must have Python_ [#]_ installed. Python comes with most Linux installations, but is still less common on Microsoft servers.
The Guestbook Files
---------------------
When you get the *guestbook.zip*, it will contain the following files and directories :
* **guestbook.html** - this helpfile
* **guestbook.txt** - the ReST source to this helpfile
* **blue_box.css** - the css file for this html page
* **guestbook.py** - the main guestbook Python script (the CGI)
* **guest_template.py** - the html templates
* **guestentries.txt** - a simple example guestbook file
* **BSD-LICENSE.txt** - the license that this is released under
* *images* directory - the alert image, and images for this file
* *smilies* directory - a set of smilies with the relevant **pak** file
* *modules* directory - the necessary python modules for smilies and handling html
* *scripts* directory - the javascript file for form validation
Step By Step
-------------
Since version 1.4.0 there is a bit more to do if you want to use all the features of the guestbook. You'll need to install the python files correctly, put the smilies in the right place, put the javascript and alert image in the right place, and finally - edit the templates.
Upload the Python Files
~~~~~~~~~~~~~~~~~~~~~~~~
You'll need to upload ``guestbook.py``, ``guest_templates.py``, and the ``modules`` directory.
You'll need to do the usual things for CGI - like make sure that the first line of guestbook.py is set correctly for the server. It will usually need to be something like **'#!/usr/bin/python'** or **'#!/usr/bin env python'**. You will also have to change (chmod) the permissions of guestbook.py to '755' (executable by everyone). The files will probably need to be located in the 'cgi-bin' directory, or a subdirectory. The last thing is to make sure that the script is uploaded to your server in 'ascii' mode, rather than binary - this ensures that the line endings are properly converted when uploading. A desktop based FTP client like Filezilla is a good way to do this - just make sure it is set to 'ascii' mode for '.py' files.
Upload the Smilies
~~~~~~~~~~~~~~~~~~~
The Voidspace guestbook now supports smilies - hurrah. It comes with a standard set, but you can use alternative sets as well.
You need to upload the smiley images. In the distribution they come in a directory called ``smilies``. You will need to tell guestbook where to find this directory - this is the ``smiley_url`` and ``smiley_path`` values in the templates. If you put the guestbook in your ``cgi-bin`` directory and the ``smilies`` directory in the root web directory, you might not need to edit these values.
Smiley support is done using a modified version of ``smiley.py`` by `Mark Andrews`_. It supports smiley sets with a **.pak** file, as used by phpbb_. You can find alternative sets of smilies at the stylesdb_ website.
If you don't want to use smilies, delete ``smiley.py`` from the modules directory.
Smilies are entered as text. They can also be inserted from the images using a piece of javascript. They are then replaced with the image when the entry is displayed. A smiley must be surrounded by spaces to be displayed. Sometimes a smiley gets inserted next to the edge of the text box and a line break gets inserted. This means an occasional smiley won't get converted. Hey, there are worse things in life.
The Scripts Directory
~~~~~~~~~~~~~~~~~~~~~~~
The scripts directory only has one file in it - ``guestform.js``. This is the javascript file used to validate the form entry. If you use it then the user will be warned before submitting an entry with required fields missing, or an apparently invalid homepage url or email address. The guestbook will still work without using the javascript. This means that people who access your guestbook with javascript disabled can still make entries.
The advantage of using the script is that it will reduce rubbish in your guestbook (obviously invalid URLs and email addresses). Additionally, if a user omits a required field they don't lose their entry.
The path to script is set in ``pageheader`` in the template. It doesn't matter where you put the script - so long as the path is correct. By default it is expected in a directory called ``scripts`` in the root directory. If you don't want to use the javascript, delete the part of ``pageheader`` that refers to it. You may also want to delete ``onsubmit="return checkform(this);"`` in ``entrytable``.
``guestform.js`` *does* expect another file to be in a specified place though. See the section below, about *the images directory*.
The Images Directory
~~~~~~~~~~~~~~~~~~~~~~
The ``images`` directory contains a few images for this file. It also contains a single file that you will need to put on your server. This is ``alert.gif`` which is used by ``guestform.js``. Unfortunately the path to this is set in the javascript file. It expects the image to be at ``'/images/alert.gif'``. If you put it anywhere else you'll need to change this path in ``guestform.js`` [#]_.
Summary
~~~~~~~~
That might sound complicated. *But*, for a default install you can just do the following :
* Upload the python files into the ``cgi-bin`` directory [#]_
* Upload the ``images``, ``smilies``, and ``scripts`` directories into the root web directory.
Customising Guestbook - Using the HTML Templates
===================================================
Guestbook uses HTML templates to generate it's output. This means it can be easily incorporated into any website. All of the templates are contained in a file called *guest_template.py*, which can be edited with any text editor. It has several variables containing the HTML, in sections, which are put together and output by the script. You choose the look of the pages produced by guestbook, by inserting your own HTML into these variables (everything between the triple-quotations). There is a note by each one explaining where each one is used, and also explaining the layout of the page. There are also a few variables relating to `the email feature`_. See the next section on how to set these, or to switch it off.
If you have never used HTML forms before, then it's probably best to leave alone the form that collects the information from the user. This is the variable called ``entrytable`` in *guest_template.py*. Some of the values in this section are crucial to guestbook. If you do edit it, you mustn't use the '%' character anywhere in it. If this causes you problems, let me know and I can do a fix.
In actual fact you can create quite a nice guestbook just by editing the pageheader and the pagefooter entries. (Which is basically all I've done in my `example two`_ - which is the guestbook for my main website, Voidspace_). You might also want to just edit the name displayed in ``pageheader2``, and the greeting in ``blankout``, but most of the rest of the settings are fine as defaults.
Don't forget to keep my credits intact somewhere on the page please. This is the section : ::
The Voidspace Guestbook
is written and maintained by Fuzzyman,
using Python.
When displayed it looks like this :
.. raw:: html
The Voidspace Guestbook
is written and maintained by Fuzzyman,
using Python.
Inside the zip file is an example 'guestentries.txt' file. If you upload the example one you'll probably need to set the permissions (chmod again) to '666' so that it can be written by anyone - because the script needs to write to it. If you don't upload the example one then the script ought to create it's own, which should be fine. The example one shows you the file format the entries are saved in. You can edit the actual entries in your guestbook, by editing this file (but beware if you mess it up then it's likely to crash !). It just saves the different parts of each entry (name, email, location, homepage, date and comments) separated by ``'||'``, all on one line. If a value isn't present (e.g. the user didn't specify a location) then you will see ``'||||'``. You can delete a whole entry by deleting the whole line.
The last two lines in the file are used as a counter of how many times your website has been viewed, and a number that represents the first time it was looked at.
.. note::
Because we send the guestbook web page as ``UTF8``, your template **must** be saved as a UTF8 file. Most modern text editors, including notepad, can do this - but they probably have to be told to ! On windows the default encoding for non-ASCII characters is likely to be ``cp1252``, and things might not appear how you expect.
The Email Feature
===================
Guestbook can be setup to email you whenever anyone makes an entry. This needs either a working 'smtp library' on your server (which will be most servers), *or* access to the sendmail progam (which means Lunix type platforms only).
If you want to use sendmail then you will need to specify the path to the sendmail program, using the **SENDMAIL** value in the template. A likely default value comes in the standard template. If you want to use the smtp server (host 'localhost', no username or password) then change SENDMAIL to ``''``.
The email feature comes with the email variable set to ``''``. In order to switch it on you will need to put your email address into this value.
The other values (``email_subject`` etc) make up the email message - it's probably best not to mess with these.
Unicode and Character Sets
============================
As of version 1.2.0 the main guestbook page is sent as **UTF-8**. This is *the* unicode encoding that web browsers speak. It also means that the form submission should be sent back encoded as UTF-8. This means that guestbook ought to cope with input from almost any character set. Haha.. I'm sure that statement will be tested though. Anyway, if you have any problems with it, please let me know. Sending in UTF-8 is enforced by sending the http header **Content-type: text/html; charset=UTF-8**. This means that if you want to include non-ascii characters in your template, you should use the UTF-8 encoding and not latin-1 (or anything else). By default 'guest_template.py' is now UTF-8 encoded, with the appropriate declaration at the start of the file.
As of version 1.3.0 the form includes a '_charset_' parameter that detects if the user has changed the character set. If they have then the submission is converted to UTF8. This is slightly more flexible than before.
Anti-Spam Features
======================
Unfortunately spam is a fact of life. This includes guestbook spam. The Voidspace Guestbook includes a few features to help reduce this. The most obvious one is that the geustbook files are saved as plain text. This means you can edit them with any standard text editor and delete offending entries !
The next method is using the naughty word list in the template file. As well as containing naughty words it also contains some words used by a lot of spammers - these include the obvious like 'viagra' and 'cialis'. If you are regularly bothered by the same sort of spam you can add extra words here to block entries.
As of version 1.3.0 some new features have been added. You'll need to update your template file to take advantage of them - see the values in the 1.3.0 template file. The first is that links displayed (the homepage entry) have the *rel="nofollow"* tag. This means that search engines don't follow the link and they are no use to spammers. (Spammers make entries in guestbooks to increase the number of pages linking to their sites and increase their search engine rankings). This change is in the *g_homepage* value in the template.
Also, in version 1.3.0 - email addresses are displayed by the browser using javascript. This means the email address isn't in the page source in a plain format. This ought to make it harder for spammers to gather email addresses from your guestbook. This change is in the *g_email* value in the template.
The entry table now has a message telling your viewers about these two facts.
The final feature is new in version 1.4.0. We now make a basic check that the POST has been made by a human, rather than an automated POST. First, the IP address of the GET must match the IP of the POST. Second, the time of the POST must be less than 15 minutes after GET - and more than 5 seconds.
HTML in Entries
=================
Supplied in the *modules* directory is a file called *htmldata.py* by *Connelly Barnes*. This allows us to process HTML based on what tags are used. All this is a long winded way of saying that *some* html is allowed in entries.
Exactly what html tags we allow is set in the ``allowed_tags`` list. Any other tags, and related text, will be removed. This means that some styles like **bold** and *italics*, etc, can be used by people who know html. I haven't allowed ````, because it breaks the layout of my pages.
If you delete the *htmldata.py* file from the modules directory, then the whole entry will be treated as text (any html will show up as text).
If the user enters badly formed HTML then we attempt to sort this - *guestbook.py* should close any unclosed tags, and we don't allow any tags that can affect layout. If you encounter any problems with this let me know.
datestring and language
=========================
Earlier on I proudly proclaimed that all the values in the templates could easily be edited by non programmers. That's not *quite* true any more I'm afraid. There are a few values with slightly techie meanings.
The first of these is called **datestring**. It controls how guestbook displays the dates of entries [#]_. This string is actually used by a function called *strftime* in the Python *time* module. If you check the `documentation on the time module`_ it gives instructions on how to edit this.
The next techie value is one called **language**. This enables you to change a setting called the ``locale`` on the computer that guestbook runs on. In practical terms, it affects the way that guestbook displays the dates of entries made [#]_. See the `documentation on the locale module`_ for details of *what* it does. Unfortunately the way to configure it varies across different platforms. For example, to change guestbook to using german dates on a windows server you need to set language to ``'german'``. On Linux you *probably* need to set it to ``'de_DE'``. It may require some experimentation to get it to work for you.
Their is another geeky value called **SENDMAIL**. This is documented in `The Email Feature`_ section.
-----------
TODO
=====
Features I *could* add :
* Proper admin page for deleting/editing entries via a web interface (use logintools)
* A DNSBL lookup as an additional anti-spam measure.
* Preview entry ?
* Allow alternative encodings in the template.
* Check html tags in comments for javascript - in the stripHTML function.
* When a naughty or incomplete entry is made - fill the values back into the form.
Version 2.0 ?
---------------
It would be possible to move all the templates into a config file, the sort read by ConfigObj_. This would naturally mesh with logintools_ and an admin interface.
This would make it easier to add an admin interface for editing/deleting entries and *also* editing the templates. Installing guestbook would also mean installing logintools and ConfigObj though [#]_. ConfigObj would also need to support multiline values (which it currently does through the obscure '&mjf-lf;' escaping). This is one of the targets of ConfigObj 4.
It would even be feasible for a single install of guestbook to support multiple *different* guestbooks. All of this would make it an order of magnitude harder to install in the first place of course.
BUGS ?
=======
Please remember it's possible a few bugs may be uncovered in guestbook - but I'll fix them as they arrive. If you want to be kept up to date with bugfixes and improvements then join the `Pythonutils Mailing List`_.
Changelog
===========
::
2005/05/23 Version 1.4.3
Added a setting to change the locale (language) in guest_template.py
Added a setting to change the date formatting in guest_template.py
uses strftime format - 'datestring'
Time of entries now saved as numbers
(so changes to 'datestring' can affect all entries saved as numbers)
Removed strftime from pageheader2 - uses **time** and **version**
A better ObscenityCheck function
Thanks to Marius Soutier for inspiring the above changes.
Changed position of entrytable when displaying at the top.
Bugfix - cgi escaping name etc - even if we are using htmldata for comments.
Moved other logic out of template - now use **htmltags**
Moved versionstring out of templates.
Remove UTF8 BOM from the guestentries.txt file if necessary.
2005/05/04 Version 1.4.2
Fixed Python 2.3 incompatibility in CheckStamp - oops.
Fixed Python 2.2 incompatibility in ObscenityCheck (yes I'm testing now)
Fixed second image location in guestform.js
2005/04/28 Version 1.4.1
Fixed bug in handling of self closing tags with htmldata.
Upgraded to htmldata 1.0.7
Smileys by the edge of the textarea get displayed now.
Optimised the ObscenityCheck function.
Javascript improved in smiley.py
Added checks for automated entries - comparing IP and time of GET and POST
Added the 'counter' - displays how many times the guestbook has been displayed.
2005/04/23 Version 1.4.0
Support for smilies - needs path.py and smiley.py
We now replace ' ' with ' ' (whitespace preserevd in entries)
' wrap="hard"' added to textarea.
Use the htmldata module to allow certain html tags.
Better use of CSS.
Fixed bug causing page number not to be displayed.
Added javascript form validation.
2005/04/06 Version 1.3.0
Lots of restyling in the HTML templates - not *quite* so horrible now.
We write new entries at the start of the file rather than the end (undoes a bug introduced in 1.2.0)
Max of two URLs in an entry.
A few extra words added to the banned list. (Still trying to combat guestbook span)
New value 'BREAKVAL' added to templates (so we can use the XHTML
if needed)
The '_charset_' field added to the form and value checked (in case page encoding changed by guests browser)
Now use rel="nofollow" in links to foil spammers
Email addresses shown using javascript in an attempt to foil address harvesters.
Obviously invalid email addresses and urls are removed. (very basic)
2004/12/04 Version 1.2.0
You can now use sendmail instead of smtplib as an option (my current host will only allow sendmail).
License change (again!) - now the BSD license, which is OSI accepted.
Changed to use the UTF-8 encoding. We ought to be able to accept 'foreign' entries now.
Less danger of trashing the guestbook file (append instead of write is used).
Updated the docs (using reST) and the templates.
2004/10/09 Version 1.1.2
Added the environment information back into emails sent.
20-09-04 Version 1.1.1
Email function is now cross platform, not just for Linux servers. (Uses smtplib rather than sendmail).
Attempted to fix a problem with carriage returns - odd.
Changed license text.
Various minor tinkerings..
Removed the need to have the script name in the template.
Added the word poker to the list of banned words (to stop certain adverts).
Added from_email to the templates - which means this version of guestbook.py isn't compatible with an old template file.
(and added a work around so people won't notice...)
01-07-04 Version 1.1.0
Added the 'e-mail administrator' function.
24-04-04 Version 1.0.1
Corrected bug in displaying the links for multiple page books.
02-10-04 Version 1.0.0
Working guestbook.
Credits
==========
The *Voidspace Guestbook*, is written by `Michael Foord`_ [#]_.
*smiley.py* is written by `Mark Andrews`_. It is licensed under the same license as the `Guestbook License`_ [#]_.
*path.py* (needed by *smiley.py*) is written by `Jason Orendorff`_. He has placed it in the public domain.
*htmldata.py* is written by `Connelly Barnes`_, he has placed it in the public domain.
*guestform.js* is adapted from the `unobtrusive javascript`_ articles by *Christian Heilmann*. It is licensed under a `Creative Commons License`_.
The *smilies* come from a gentleman called Spider_.
Guestbook License
==================
These files are licensed under the BSD license. This is a very unrestrictive license - but it comes with the usual disclaimer. This is free software - test it, break it, just don't blame me if it eats your data ! (If it does though, let me know and I'll (try to) fix that it so it doesn't happen to anyone else :-) ::
Copyright (c) 2003-2005, Michael Foord
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
* Neither the name of Michael Foord nor the name of Voidspace
may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
You should also be able to find a copy of this license at : `BSD License`_
If you let me know of any places where you use my scripts, I can include a link back to you as an examples. If you use this program, please help `Sponsor Voidspace`_, to help cover the costs of hosting Voidspace_ and all the Pythonutils_ projects. Even $1 or $2 is helpful !
.. [#] The two exceptions to this rule are the 'datestring' value for formatting the way dates appear, and the 'language' setting for changign the native language of the guestbook, otherwise known as the 'locale'. The template file has details.
.. [#] It is tested, and ought to work with Python 2.2 or more recent. If you have any problems *please* report them and I'll fix them.
.. [#] This path occurs twice in ``guestform.js`` - both very close to each other.
.. [#] Which we assume is a subdirectory of the root web directory. If it isn't you'll have to alter the ``smiley_path`` value.
.. [#] Or more properly *formats* the dates of entries.
.. [#] This only applies to entries made *after* version 1.4.3 (or later) is installed. Entries made prior to this will have been saved with the date as text.
.. [#] Both logintools_ and ConfigObj_ are pure python modules - so they could just be bundled with guestbook.
.. [#] Also known as *Fuzzyman*
.. [#] Known as the 'BSD License'
.. _Guestbook Homepage: http://www.voidspace.org.uk/python/guestbook.html
.. _PythonUtils Mailing List: http://www.voidspace.org.uk/mailman/listinfo/pythonutils_voidspace.org.uk
.. _BSD License: http://www.voidspace.org.uk/documents/BSD-LICENSE.txt
.. _Python: http://www.python.org
.. _example one:
.. _Default Guestbook Example: http://www.voidspace.org.uk/cgi-bin/voidspace/guestbook.py
.. _example two:
.. _Voidspace Guestbook: http://www.voidspace.org.uk/cgi-bin/voidspace/guestbook2.py
.. _`Guestbook 1.4 .zip`: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=guestbook.zip
.. _sponsor voidspace: http://www.voidspace.org.uk/sponsorship.shtml
.. _Michael Foord:
.. _Voidspace: http://www.voidspace.org.uk
.. _pythonutils: http://www.voidspace.org.uk/python/index.shtml
.. _Jason Orendorff: http://www.jorendorff.com/articles/python/path
.. _Mark Andrews: http://www.la-la.com
.. _unobtrusive javascript: http://www.onlinetools.org/articles/unobtrusivejavascript/chapter5.html
.. _Creative Commons License: http://creativecommons.org/licenses/by-nd-nc/1.0/
.. _phpbb: http://www.phpbb.com/
.. _stylesdb: http://www.stylesdb.com/smilies_styles.html
.. _Spider: http://web.spidercode.de/smilies
.. _Connelly Barnes: http://oregonstate.edu/~barnesc/htmldata/
.. _Sourceforge Project: http://sourceforge.net/projects/guestbook
.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
.. _logintools: http://www.voidspace.org.uk/python/logintools.html
.. _documentation on the time module: http://docs.python.org/lib/module-time.html
.. _documentation on the locale module: http://docs.python.org/lib/module-locale.html
.. raw:: html
