 |
PostIt
Synopsis
This gadget allows you to implement web-based discussion areas, very
similar in nature to usenet newsgroups or mailing lists. With full support for
threaded discussions, keyword searches, reply quoting, icons, and more,
it is one of the best "bulletin board" gadgets available anywhere.
Setup
Each "topic" (similar to a single usenet newsgroup) you wish to have
requires
its own configuration file. A configuration file can be empty, in which
case
default settings are used for everything, or it may contain a list of
options that specify how this particular topic is to be handled.
You can have as many topics as you want, as long as each topic has a
unique
name. This name must be a single word, no spaces, etc. Think of it as
a file name for the topic (in fact it will form the prefix for several
files).
Let's say you want to create a place where vistors can discuss current
events. We might name this topic "cevents". Our first step is to create
a file called "cevents.cfg" inside the "www" directory of our account.
This is a plain ASCII text file that has one configartion setting per
line. All options are optional, they all have default values. Let's
examine each possible option and what it does:
- headers = {header codes}
- This option lets you specify which article headers should be
displayed,
and in which order (when viewing an individual article). Each possible
header has a corresponding single-letter code. Simply provide a list of
letters after the equal sign. For example, headers=sf would
display the Subject and the From headers, in that order. All other
headers would not be displayed. The different headers include:
S Subject
F From
D Date
K Keywords
H Host Name or IP Address of Author's Computer
A Article Number
P Previous Article Subject
N Next Article Subject
The default value is SDFKPN.
- new = {n}
- Replace {n} with a number that represents how many days old an article
can get before it is no longer considered "new". Articles younger than
this
will appear with a small icon (
 ) beside
them.
The default is 7 days.
- newest = {n}
- This option is identical to the option above, except that articles
that
iyounger than this have a slightly different icon
(
 ) beside them. The idea
is that the newest articles will have one icon, articles that are slightly
older will have a different icon, and all the others will have no icon.
The default is 3 days.
- newicon = {url}
- Replace {url} with the URL of a graphic to be used in place of the
default "new" icon.
- newesticon = {url}
- Replace {url} with the URL of a graphic to be used in place of the
default "newest" icon.
- maxage = {n}
- Replace {n} with the maximum age (in days) of articles. Any articles
that are older than this value will be automatically deleted. This means
you don't have to worry about manually removing old articles yourself.
Set
it to 0 to disable automatic purging of old articles. The default is 30
days.
- maxarts = {n}
- Replace {n} with the maximum number of articles allowed. Once this
limit is reached, the oldest message will be deleted to make room for a
new posting. This means you don't have to worry about the topic growing
in size beyond a reasonable number. Set this to 0 to disable this
feature.
There is an internal limit of 250 articles per topic. The default is
100.
- bodybg = {color}
- Replace {color} with an HTML color code. This option will cause the
body of an article to be displayed within a table. The table will have
a border, and the background will be the specified color. The default is
to not do anything special and simply display the body of the article
"plain". For example, bodybg=#FFFFFF will result in a white
background.
- bodyfg = {color}
- Replace {color} with an HTML color code. This option controls the
color of the text used to display the article body. This option is
normally used in conjunction with the option above. The default is to
simply display the body text with no color specification. For example,
bodyfg=#000000 will result in black text.
- icons = {n}
- Replace {n} with either 0 or 1. A value of 0 indicates that you do
not want to allow users to pick a small icon to appear in the subject
of their message. A value of 1 turns this option on. The default is 0.
Although there is a default set of icons available, see below for details
on how to create your own icon list.
- buttons = {n}
- Replace {n} with either 0 or 1. A value of 0 indicates that you do
not want to have graphical buttons. A value of 1 turns on graphical
buttons.
The default is 1.
- {button-name} = {url}
- If you have buttons = 1 then the gadget will use some
default graphical buttons. By replacing {button-name} with the name of
a button, and {url} with the URL that points to the graphic, you can
specify your own set of graphical buttons. Simply add one of these
entries
for each button name listed below:
- bottom
- top
- refresh
- post
- reply
- delete
- list
- article
- author
- date
- subject
- thread
- keyword
- listtype = {x}
- Replace {x} with either the letter 'u' or the letter 'o'. This
controls
whether the gadget will use unordered lists (bullets) or ordered lists
(numbers) when showing a list of articles.
- reverse = {n}
- Replace {n} with either 0 or 1. A value of 0 means that date-sorted
articles lists will have the newest articles nearest the bottom. This is
the
default. A value of 1 will cause the newest articles to appear near the
top.
- receipts = {n}
- Replace {n} with either 0 or 1. A value of 1 means that a copy of
each
article will be emailed to the poster. This can help to eliminate forged
articles. The default value is 0.
- mailto = {address}
- Replace {address} with an email address, and a copy of every article
posted will also be emailed to this address. This is useful if you want
to be notified whenever someone posts something to your discussion group,
or it can be used to forward copies of postings to a mailing list.
- mailfrom = {address}
- Replace {address} with an email adress that will be used as the FROM:
header when copies of articles are emailed to the above mentioned mailto
address. Without this, the address is taken from the article's FROM:
header.
If you are forwarding mail to a mailing list, however, it may be necessary
to force the use of a specific address regardless of who actually posted
it.
- acceptfile = {filename}
- This setting specifies the name of an accept/reject file, relative
to your root directory. This file can be used to block access to your
chat page from specific domains and/or IP numbers. This is very
useful if you have an abusive user on your hands.
Click here for more details about accept files.
- rejectmsg = {filename}
- This setting specifies an HTML file that will be displayed if the
user is attempting to connect from a banned IP or host name, according
to your accept file. This is relative to your "www" directory.
That's it! No additional files need to be created in order to start using
your discussion group. You need only create a pointer to your topic. Do
this by adding a link on one of your web pages that looks like this:
<a href=/cgi-bin/postit?login=guest&topic=cevents>Current
Events</a>
Note that you must replace guest with your real
islandnet login (you cannot use an email alias here). Also note
that you would change "cevents" and "Current Events" to match your particular
example.
As long as you have a .cfg file for each topic, you're off and running.
Other Files
The gadget itself will create many files within your account. If you were
using the "cevents" example, it would create a file called "cevents.adb"
in your "www" directory. This is the article database. You should avoid
messing with this file directly, unless you want to delete it
completely.
As well, each posted message will generate a "cevents-xxxxx.art" file,
where "xxxxx" is actually a number. This contains the body of an
article.
Note that the gadget itself provides a mechanism for manually deleting
individual articles.
Subdirectories
Most people who have more than one topic will likely want to place them
in subdirectories below their "www" directory. To do this simply add
the directory name to the topic value. For example, if we were creating
a topic called "news" and placing it within the "abc" subdirectory,
we would specify the topic as "abc/news". Note that all files
associated with a topic MUST reside in the same directory.
Customizing the Look
It is often desirable to make the various PostIt-generated web pages have
a look that is consistant with your other pages. You can do this by
creating a header and a footer file that will automatically be included
whenever a page is generated.
Assuming we are still using the "cevents" example, you would simply create
the file "cevents.hdr" and "cevents.ftr". These may contain HTML tags or
they may be plain text. You may use one or the other or both.
If you have icons = 1 in the config file, the gadget will
first
look for a .ico file (same name as the config file, but
with
a .ico extension instead of .cfg). If it exists then the list of
available icons presented when a user is composing an article will be
taken
from this file. If the file does not exist, then the default list will be
used. The format of the file is simple: it is an ASCII text file
containing
an URL, followed by a space, followed by an icon description. Here's an
example:
http://www.islandnet.com/icons/smile.gif Smiley Face
http://www.islandnet.com/icons/angry.gif Angry Face
Examples
| |
