WebUserPrefs 0.5
SpamAssassin web-based preferences editor.

This PHP template is released under the terms of the
GNU General Public License (GPL). There is no warranty
on this piece of software.

Thank you for downloading WebUserPrefs!

WebUserPrefs is a PHP template designed to enable web-based editing
of SpamAssassin user preferences. It supports either user_prefs files or
preferences stored in a MySQL database.

You can find more information about SpamAssassin at
http://www.spamassassin.org.

CREDITS
	Patrick Bores <patrick@pipegrep.net> (main programmer)
	Chadwick L. Sorrell <chad@hrtc.net> (MySQL code)

WHAT'S NEW

	* Authentication modules
	* Bug fixes
	* Code cleanups (panels mostly)

INSTALLATION

	1. Unpack the archive into a web directory.

	2. Configure an authentication module.

	   If you are in a multi-user environment, you may want to
	   configure an authentication module. Modules are in the "auth/"
	   directory at the root of this installation. Open your preferred
	   module with your favorite text editor and set the configuration
	   variables within.

	3. Configure WebUserPrefs.

	   Open the file "config.php". If you configured an authentication
	   module, uncomment the "require" for that file at the top of
	   the config.php file.

	   Now set the rest of the configuration variables:


	$prefs_source	Set to "file" if you want WUP to read and write a
			user_prefs file. Set to "db" if you want WUP to
			read and write from a MySQL database.

	$user_prefs	If you set $prefs_source to "file", then set this
			variable to the path to the target user_prefs file.
			If you included an authentication module, use the
			$auth_user variable to set this one. Example:

			$user_prefs = /home/$auth_user/.spamassassin/user_prefs

			IMPORTANT: This file must be writable by the web
			server!

			If you set $prefs_source to "db", set the following
			database variables;

	$db_host	MySQL Database host address.

	$db_username	Username to access the required database.
 
        $db_password    Password relevant to the username.

        $db_database	The name of the database you are accessing.

	$db_table	The table name the prefs are stored in.

	$db_sauser	The 'username' field of the table, so
			WebUserPrefs knows which rows to read/write.
			Again, you can use the $auth_user variable
			if you included an auth module. Example:

			$db_sauser = $auth_user;


	$table_border_color		These variables affect the colors
	$table_titlebar_color		of the tables and text of
	$table_background_color		WebUserPrefs. There are some
	$table_alt_row_color		suggestions in the config.php
	$text_titlebar_color		file.

	$panels_dir	This should be the path (relative to the server) to
			your "panels" directory, which contains plugin files
			for each preferences panel you want to use. Read
			below for more information on panel files.

	$header_file	This should be the path (relative to the server) to
			a file that contains HTML code which WebUserPrefs
			will insert at the top of its output. Use this file
			for customization. There is a sample file included
			in this distribution.

	$footer_file	This should be the path (relative to the server) to
			a file that contains HTML code which WebUserPrefs
			will insert at the bottom of its output. Use this file
			for customization. There is a sample file included
			in this distribution.

        $group_sort	Set to "yes" if you want user rules to be grouped
			and sorted. They will be sorted in this order:
				whitelist_to
				whitelist_from
				blacklist_from

	$usessl		If the page is loaded without SSL encryption, auto-
			matically reload with https:// prefix.


3. Make sure your user_prefs file is writable by the web server, or that your
   MySQL database is properly configured.

4. Set up your panels directory. Remove any panels you don't want, rename them
   to change their order, and be sure to check out the "contrib" directory for
   user-contributed panels.

4. Load the index.php file and go! 

HOW PANEL FILES WORK

Beginning with version 0.3 of WebUserPrefs, you can add and subtract support
for different configuration options using custom "panel files". Each panel
file in the "panels" directory defines a different preferences panel in the
program. Preferences panels are displayed as cells in a 2 column table, in
order from left to right, top to bottom.

Panel files are named with a numerical identifier, then an underscore, then
the name of the panel. For example:

	01_panelname

This panel file's name is "panelname" and it will be first panel loaded to
the upper, left cell of the preferences table.

The panel file is a simple PHP file that gets included into the main program.
It must contain 3 functions, each containing the name of the panel. Example:

	function panelname_keys()
		should return an array containing each preference option it
		is going to work with, such as "required_hits" or "subject_tag"

	function panelname_html()
		should echo the HTML for the panel display. You may use the
		get_pref() function to retrieve the initial values of
		preferences options.

	function panelname_apply()
		should access the $_POST variables to see what values the
		user entered, and then use the set_pref() function to
		update the user_prefs file.

If you've written a good preferences panel, e-mail it to me, and I'll
include it in an archive available for download from the web page.


Please send questions, comments, suggestions, bugs, etc to patrick@pipegrep.net
