This is the readme which accompanies my web-absence CGI application. -------------------------------------------------------------------- The current version is 1.8.1 The project home is located at: http://www.unix-wissen.de/absence/ DESCRIPTION =========== absence is a CGI-based tool for keeping track of people on a daily basis. In principle it can be used to keep track of anything. For example it could be used to manage computer systems, or cars. The user interface revolves around a monthly display in the form of a matrix. Days are represented by columns, and people (or objects) by rows. This monthly unit I call a "month-image". So-called "absences" are entered by clicking on the starting-day of the absence, and then entering the ending day, along with a short description. If you select client-side image maps (as opposed to server-side), hovering over a particular absence will cause your browser to display the full text in the "short description" field as a so-called "tool-tip". Absence can now mark the current month and current day. The current month is marked in a variety of ways: different (configurable) colors are used for the normal background, weekend background, calendar-week color, grid lines, and for the month-name and year text. Additionally, a 2-pixel-wide frame is drawn around the whole month-image, also using a configurable color. The colors are specified in AbsenceConfig.pm, or in your instance config file. If you use the default colors supplied with absence, the current month normal background will be lighter, the weekend background lighter, the calendar-week lighter, and the grid lines darker. The month and year text will be blue, and the frame will be white. How the current day is displayed is configurable: "fill" or "box". If "fill" is chosen, the column corresponding to the current day, will be colored using a configurable color. If "box" is chosen, a frame 2 pixels wide will be drawn just inside the column using the same configurable color. There are different kinds of absence-types which are freely definable by the administrator. Also arbitrary colors can be assigned to the various absence-types. An existing "absence" can be edited simply by clicking on it. Multiple separate "groups" are supported. As of version 1.7, absence supports access control. Users are authenticated using a CGI form or via the standard http mechanism. read, write, and admin permissions can be assigned on a group basis, and write permission can be assigned on a per-person basis. Please see "00README-AUTH" for more information about authentication and authorization. Cookies are used to hold information about what was last displayed (and therefore what will be displayed the next time). JavaScript must be enabled for administrators, but is not absolutely necessary for users. see bottom for tips on getting absence to run on windoze. Prerequisites ============= - the GD library (see http://www.boutell.com/gd/) prerequisites for libgd are: - libpng (linked dynamically) - libz - libjpeg - the Perl GD module (see http://www.cpan.org/modules/by-module/GD/) - the Perl CGI module (see http://www.cpan.org/modules/by-module/CGI/) - the Perl Digest::MD5 module. (see http://www.cpan.org/modules/by-module/Digest/) I have successfully used gd versions 1 and 2. (I'm currently using gd-2.0.11 and GD-2.06) Version 2 no longer supports GIF images. If you choose version to use version 1.8.4, do not install it until you have unpacked the Perl GD module, as this contains a patch for gd to produce a shared library using gnu configure. CHANGES ======= 1.8.1: - fixed bug which caused current month/day to be incorrectly displayed 1.8: - if "absence-types.db" is edited, the legend image will automatically be regenerated. - options added to mark current month or day - fixed bug that caused wrong month-images to be displayed after modifying an absence if "Next"/"Previous" buttons were used - made all colors used configurable in AbsenceConfig.pm - added option to alternate background color in the people-rows - bank holidays can be indicated with a small or large mark. 1.7.2: - fixed bug that caused incorrect group to be displayed when modifying a person when group_policy is set to "single". 1.7.1: - fixed silly syntax error 1.7: - authentication and authorization added. see 00README-AUTH for details. This may not sound like much, but it is. - lots of small improvements 1.6.2: - repaired small bug which snuck in along with multi-group-membership. The group-number was getting botched in "month_mod_times.db" which caused month-images to always be generated new, even if the cached versions were unchanged. - fixed month-modification-time database. It was not working at all, causing month-images to always be re-created. 1.6.1: mainly cosmetic stuff: - fixed the handling of conflicts when two users are modifying/deleting the same entity. (reservation/group/person). The scripts would exit with die(), causing a server error (but not necessarily a data-inconsistency). Now such situations are recognized and an appropriate error-message is displayed. - sorted groups and people alphabetically in management page. - added more information about reservation conflicts - other stuff 1.6: - users can be members of multiple groups (if so configured) - various bug fixes and minor improvements: logging improved added JavaScript to auto-submit when group is chosen logging improved db-file handling a bit safer bank-holiday label configurable when CW-bar is only one day long, CW-number is not printed cookie-handling improved (simplified) other stuff I can't remember 1.5: - added support for multiple "instances" of absence which all use the same Perl scripts and modules. This will not work on windoze/IIS. See windoze notes. - added a comprehensive installation script, "install.pl" - documented all modules and scripts. 1.4c: - added windoze info to Readme.txt. - added "binmode()" statements to "AbsenceImage.pm" for stoopid windoze. - added comments to "AbsenceConfig.pm" for windoze users. 1.4b: - the wrong "index.html" file was included in the 1.4 and 1.4a kit. 1.4a: - a configuration option was added for the cookie domain, which had been hard-coded into 'absence.pl' :(. - An error message is now printed if a user who has disallowed cookies tries to use the "Next" or "Previous" buttons. 1.4: - the broken URLS produced in v1.3 have been fixed. v1.3 only worked if the browser did *not* fix the broken URLS. Specifically, targets of the month-images were in the form: "/path/absence-click.pl?G-M/YYYY" The browser then appended "?," to the end. - either client-side or server-side image maps can be used. The client-side map option is new. - cookie administration was cleaned up an iota. INSTALLATION ============ Distribution Files: ------------------- [HTML] index.html absence-help.html [data] absence-types.db holiday.db [CGI scripts] absence.pl absence-click.pl absence-control.pl absence-manage.pl nph-absence-logout.pl [Perl Modules] AbsenceDB.pm AbsenceDate.pm AbsenceHolidays.pm AbsenceImage.pm AbsenceTypes.pm AbsenceConfig.pm AbsenceLog.pm AbsenceAuthentication.pm AbsenceAuthorization.pm [JavaScript Files] acl.js First, unpack the contents of the kit in some temporary directory. As of v1.5 there is an installation script, "install.pl". I put a lot of work into this script, please use it. The script asked at the end if it may be allowed to send me a mail. Please allow the poor script to send me a mail! Otherwise it gets sad. To use the script: The script can be given its parameters on the command-line. run "install.pl -h" to get a list of all parameters. The short or the long form can be used. It is possible to use previously defined parameters as part of later-defined parameters. I recommend making use of this capability. If you do not supply parameters on the command-line, you will be prompted for them. You can use install.pl to update an existing configuration. install.pl will not overwrite your datafiles (database-file, holidays-db, types-db, log-file). The following is an example invocation with command-line params: install.pl -ddr '/absence' \ -dda '$DOCUMENT_ROOT${data_dir_rel}' \ -cdr '/cgi-bin' \ -cda '$DOCUMENT_ROOT/..${cgi_dir_rel}' \ -idr def -ida def -dbf def -mdbf def -hdbf def \ -auth no "def" means take the default. The defaults are printed in interactive mode. As you can see, you must use the "${long-name}" construct when referring to previously defined parameters. This is mandatory. Also, you may use "$DOCUMENT_ROOT" in the definition. Make sure you protect any strings with metacharacters in them (such as "$") but putting the whole string in single-quotes, as above. Everywhere you see references to "absolute" and "relative" paths. "absolute" paths are paths as a CGI-script needs them to be able to locate files. Example: "/users/apache/html/absence" "relative" paths are the path component of a URL, i.e., what needs to go into HTML. Given the URL: http://www.unix-beratung.de/absence The "relative" path would be "/absence". If you have any trouble with the installation script, please take the time to figure out what went wrong and let me know! How to install manually: -------------------- 0. Configuration as of v1.5, it is possible to have multiple "instances" of absence, however v1.5 is backwards compatible, which means if you are upgrading you can simply copy the modules and scripts to your cgi-bin directory. The install-script will do this for you without overwriting your database, type-file, or holiday-db. See "00README-INSTANCES" for more information. 1. Prerequisites see above. 2. web-server hierarchy - create a directory (label: "absence") somewhere under $DOCUMENT_ROOT, for example "$DOCUMENT_ROOT/absence" This will contain the few pure-html pages and the datafiles. - create a subdirectory "img" (label: "image") under the new directory, for example "$DOCUMENT_ROOT/absence/img" 3. copy files - copy the HTML files and the "absence-types.db" and "holiday.db" data file into the absence directory. - make the the absence-dir, the image-dir, and the ".db" files read and writable by the httpd user. This can be done by performing "chmod 777 " on the image directory and on all "*.db" files, or by setting their owner to be the same as the httpd-user. - copy the CGI scripts, Perl modules, and JavaScript file into the appropriate "cgi-bin" directory of your web-server. 4. edit files - edit "AbsenceConfig.pm" and make any necessary changes. You will probably want to set $data_dir_* and $cgi_dir_* to something appropriate. legend_style can have two values: 1. "constant:X" where X is a number. For example, "constant:60" this means the legend colored rectangles should have a constant width of 60 pixels. You will have to experiment with this depending on the lengths of your types. 2. "fit" means the legend colored rectangles will be fit to the legend label strings. As of v1.4, you can use either client or server image maps. Server image maps allow the web pages to be much much smaller, but you must click and load a new page to get any additional information, such as the name of a holiday or the full text of an absence (if the block is too small to display the full text). Client-side image maps cause the web pages to be bloated, but then tool-tips are used. If you can live with the size of the pages created when using client-side image maps, they are better. I have tested them while displaying 12 months of a group with 20 people. The resulting web page was circa 700 KB large, with circa 7500 lines. You can change the image map type at any time. Because the server-side images map configuration depends on PATH_INFO functioning, only the client-side image map configuration will work on windoze. To choose one or the other, edit AbsenceConfig.pm and set "map_type" appropriately. - you may want to add or change holidays in "holiday.db" - you may need a "use lib '...';" line in "AbsenceImage.pm" to tell Perl where you keep the GD module. - you may need to fix paths in "index.html" in the absence directory. - see 00README-AUTH for information about configuriont authentication & authorization 5. test Problems: ---------------- If you're getting weird behaviour, such as clicking on "modify user" in the manage page, and getting the same manage page again, you probably want to increase the values for $CGI::POST_MAX. In particular, you may notice such problems after adding more objects to the database. Bugs: ---------------- Don't know of any currently. Notes: ---------------- Please let me know about any bugs you may find, and feel free to make suggestions for improvements. I don't guarantee to take them to heart, or to respond in a timely manner. I will do my best. Please send me a short mail if you use absence, and perhaps tell me what you're doing with it. License: ---------------- Absence is available under the terms of the GNU General Public License (GPL). Windoze: ---------------- Warning: recent versions have *NOT* been tested with windoze. Feel free to send me suggesions for improving this section. general installation comments ----------------------------- Step 1: load gun Step 2: locate foot (optional: head) Step 3: point gun at foot Step 5: pull trigger I don't know much about windoze. I don't like it very much. Nevertheless, I was able to get absence running on w3k (sp3) with IIS (whatever version one has after installing w2k and sp3) by doing the following: - installed ActiveState Perl v5.8 - installed the GD ppm by going into PPM and typing "ppm> install http://theoryx5.uwinnipeg.ca/ppms/GD.ppd" ("ppm>" is the prompt) - created a virtual directory called "absence" where I put the html-files, and the db-files. Also I created a subdirectory called "img", renamed "index.html" to "Default.htm", and created an empty file called "absence.db" here. - created a virtual directory called "cgi-bin" where I put all the perl modules and scripts. I made it executable. - edited "AbsenceImage.pm" and added "binmode()" to both open statements. (This has already been done in the current kit.) - edited "AbsenceConfig.pm" and changed "$data_dir_abs" to have a hard-coded path instead of using "$ENV{DOCUMENT_ROOT}". - make sure you set the image-map type to "client". "server" WILL NOT WORK. naturally I did all this stuff as "administrator". windoze/IIS and multiple instances ---------------------------------- because IIS does not support the PATH_INFO variable, multiple instances will not work. I have read somewhere that it is possible to fix this by fiddling with some hidden IIS variable of the name AllowPathInfoForScriptMappings but I have not verified this. --------------------------------------------------------------------- Robert Urban September, 2003