PLANWORLD
Planworld is great a number of things to different people. It provides a means for people to share information about themselves, their schedules, their diaries, or anything else they desire. Plans are often used for conversation (through the use of Snitch and Snoop), providing a complex threaded environment with structure provided primarily by planworld's users.
Planworld can be almost anything; it's use is limited only by the imaginations of those who use it. It is unlikely that two planworlds will ever be alike; their uses will vary depending on the needs, desires, and alternative communication methods that users have at their disposal.
Planworld has been designed with the intention of easily allowing users to share their plans with others, within their own planworld-group or with the public at large. If users desire privacy, they may disable world-accessibility through the Preferences page. This will limit viewing of their plan to others in their own community.
If you are interesting in assisting in the development of planworld or have any questions, please contact us at planworld@note.amherst.edu. We welcome suggestions, comments, bug reports, new skins, and especially patches.
Requirements:
Apache 1.3.6+ (AllowOverride All must be set for the directory that
planworld was installed in for the .htaccess files to work;
alternatively, add the directives in
PHP 4.1.0 or higher (tested with PHP 4.1.0+) compiled with mysql, xml, zlib, and xml-rpc support (--with-mysql --with-xml --with-zlib --with-xmlrpc).
In order for planworld to work properly, the querystring delimiter MUST include ';' To do this, uncomment these lines in php.ini (in /usr/local/lib/): arg_separator.output = "&" arg_separator.input = ";&"
If you would like to enable output compression (to reduce bandwidth use or to provide better service to dial-up users), change the value of zlib.output_compression to 'On': zlib.output_compression = On
register_globals, which allows POST/GET variables to be accessed by $var (vs. $HTTP_POST_VARS['var'], does not need to (and should not) be enabled. You needn't do anything about this, as it is disabled in the .htaccess file.
MySQL 3.23.x or higher OR PostgreSQL 7.1 or higher If you choose to use PostgreSQL, usernames will be case-sensitive (i.e., 'jdoe' is not the same as 'JDoe'), unlike MySQL.
Installation notes:
This package includes an experimental finger daemon (for MySQL only) that allows finger access to your planworld node. To configure it for your system, ensure that the database connection information in ffingerd.c is correct before compilation. After compilation (make), you will need to manually copy it over the existing finger as root (often /usr/sbin/in.fingerd) and make sure that finger is enabled in your inetd.conf or xinetd.conf (make backups first). The version provided has been in use at Amherst for over a year. Due to excessive use early on, we were forced to replace inetd with xinetd (which more gracefully handles large numbers of connections without shutting down). Your mileage may vary depending on your volume of use.
Installation:
Uncompress the tarball
% cd
change into the planworld directory % cd planworld
create the planworld database % mysqladmin -uroot -p create planworld
create planworld tables % mysql -uroot -p planworld < SQL/tables.sql
create a planworld user, initialize tables % mysql -uroot -p planworld < SQL/init.sql
fill the cookie jar % mysql -uroot -p planworld < SQL/cookies.sql TODO: either create a script that does this, or re-create cookies.sql to add an id sequence
set up timezones % mysql -uroot -p planworld < SQL/timezone.sql
configure planworld settings % cp config.php.dist config.php edit config.php
set up authentication % cp auth.php.dist auth.php
add backend/cache.php as a cron job set to run every 10 minutes or however often you deem appropriate (this script caches last update and last login times locally to lower the number of requests to other nodes' backends)
10a. (if php is compiled as a CGI) in your crontab: /10 * /path/to/planworld/backend/cache.php
10b. (if php is not compiled as a CGI) in your crontab: /10 * lynx -source http://example.com/planworld/backend/cache.php > /dev/null
11a. (if php is compiled as a CGI) % ./backend/getnodes.php | mysql -uplanworld -p planworld
11b. (if php is not compiled as a CGI) % lynx -source http://example.com/planworld/backend/getnodes.php | \ mysql -uplanworld -p planworld
add yourself to the node list % echo "INSERT INTO nodes (name, hostname, path, port) VALUES ('yourname', 'example.com', '/planworld/backend/', 80);" | mysql -uplanworld -p planworld
Contact planworld@note.amherst.edu with appropriate node information (name, hostname, port, and path to the backend) so that we may add you to the node list. In the future there may be either a web-form or provided scripts to do this. However, by notifying us, we will be sure to inform you of any changes in the node list, the backend, or planworld as a whole.
In addition, you will probably want to tailor the default skin to fit your needs. This will likely involve modifying outline.inc, trailer.inc, about.inc, edit.tpl, preferences.inc, and faq.inc. ('tgerety,' the user that we commonly use as an example user, is Tom Gerety, the president of Amherst College. Unfortunately, he does not have a plan.) For testing, however, you will probably not need to change any of the files (including config.php and auth.php after copying them).
Authentication:
A very simple login script is provided for your use (auth.php.dist). It is invoked by prepend.php at the beginning of each page. As-is, it does not check the validity of any given user, thus you will need to modify it in order to tie it into your existing authentication / authorization scheme.
On NOTE's systems at Amherst, we use an HTTP authentication layer written in PHP that interacts with the college's mail servers using IMAP. In the future, we hope to adapt it to use a PAM module to interact with the college's NT domain controllers as well as cURL to interact with an external alumni mail server accessible by HTTP only.
By not providing any specific authentication method, we leave you free to implement your own or tie it into an existing system. You are limited by your own imagination and skill, but we recommend keeping track of users with a database (such as MySQL) or an LDAP server (such as OpenLDAP).
A caveat: if your authentication system creates users (which is probably will), make sure that it adds user entries for planworld to use with the User::addUser() method. This ensures that initialization is done properly.
Themes:
Themes are stylesheets that are included in each planworld page load. Themes reside in layout/1/themes/ Furthermore, each has its own directory, e.g. 'metal', 'pastis' All necessary files for a theme should be located in its directory. The stylesheet should be named 'styles.css'. If a different planworld logo is desired, it should be named 'planworld.gif'. If you want further CSS positioning, etc., you may also have a file called extras.inc which gets included in each document inside the
. For example, some people like floating graphics.If your theme requires other images, such as backgrounds, etc., these should be included in the theme's directory as well...but you'll need to reference them properly in the stylesheet. e.g. 'background-image: url('layout/1/themes/yourThemeName/yourBGimage.gif')
To make the theme active, you need to add an entry to the 'themes' table in the db. The fields are as follows: id - a unique id for the skin. skin_id - for the future when we include alternate skins. For now just leave it as '1'. name - The name of the theme as you want it to appear in the list of themes users may choose from. dir - the name of the directory that the theme files lie in. This is relative to layout/1/themes/ so if your theme is 'metal' the entry in this field should just be 'metal' author_name - who designed it author_contact - how the designer can be reached.
Of course the best way to make a new theme is look at the others and just follow their lead.
Terminology:
Many of the terms used in planworld (snitch, planwatch, fixplan) are holdovers from the days when plans existed solely on our VMS system. They are left in place as reminders here at Amherst. As with anything else, you may change the terminology by modifying the existing skin or by creating a new one.
History:
A partial history as well as other interesting tidbits can be found in the 'About' section of a standard planworld installation. It is interesting to note that since we released planworld to the Amherst College community, we discovered a similar system at Grinnell (www.math.grin.edu/~heckr/Finger/). During development, we drew inspiration from planwatch.org, a similar community in the Pensacola, FL area developed by Josh Davidson. Planworld.net was started by the author (using this software) as a means for friends of Amherst students to get in on plans. If you know of others, please let us know.
$Id: README,v 1.14.4.2 2003/03/15 21:10:07 seth Exp $