This is the readme which accompanies my web-absence CGI application. -------------------------------------------------------------------- The current version is 2.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 "README-AUTH.txt" 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. Multiple-Reservation Mode ========================= As of version 2.0 absence can be configured to support multiple reservations for the same person on the same day. The various reservations that coincide with one another (i.e., have overlapping dates) must be display above or below one another. A new characteristic, priority, determines how reservations are arranged graphically. Priorities are whole numbers and go from 10 to 1, and from -1 to -10. 10 indicates that a reservation of that type should be placed as close to the top of the person-row as possible. It can only lose to another reservation of priority 10. A priority of 9 will be placed as close to the top as possible, but only after all priority 10 reservations have been placed. The same method is used for the positive priorities. The same method is used in reverse for negative priorities, i.e., -10 means place as close to bottom as possible. -9 means place as close to bottom as possible, except for -10 priority reservations, et cetera. The above applies to all non-block type reservations, i.e., full, half, or quarter height. Block reservations are always displayed using the current full height of the person-row, and can overlap, or underlap non-block reservations. Positive priorities overlap, and negative underlap. Thus, a block reservation of prio 10 would cover everything else, except another block reservation or prio 10. A block reservation of -10 could be covered by everything else: non-block reservations and block reservations with all priorities except -10. Reservation types have another new characteristic: transparency, which allows the administrator to configure how transparent the displayed reservations are, that is, to what extent they allow what's underneath to show through. Block reservations could be used, for example, for holiday. Skipping non-workdays ===================== As of v2.0 it is possible to configure reservations such that a reservation is interrupted by non-workdays, i.e., weekends and holidays. using Absence on Windoze ======================== you're on your own. Character Sets ============== Absence stores its data as UNICODE. This might sound promising, but there's a hitch: the GD fonts I use can only display ISO-8859-1 (Latin1). So if you want anything but the Latin1, you're pretty much out of luck. Sorry about that. If you have a need for other character sets, let me know. I won't promise that I'll support them, but if enough are interested, I'll have a look. Holiday descriptions that are imported are assumed either to be stored as UTF-8 or Latin1. The same is true if you are migrating old (v1.8) Absence data. Prerequisites ============= - the PostgreSQL database, at least V8.X.X - the perl DBI and DBD-PostgreSQL modules - the GD library, at least V2.X (see http://www.boutell.com/gd/) prerequisites for libgd are: - libpng (linked dynamically) - libz - libjpeg - the Perl GD module, V2.X (see http://www.cpan.org/modules/by-module/GD/) - the Perl CGI module (see http://www.cpan.org/modules/by-module/CGI/) - the Perl CGI::Session module - the Perl Digest::MD5 module. (see http://www.cpan.org/modules/by-module/Digest/) I'm currently using gd-2.0.36 and GD-2.41. LICENSE ======= Absence is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Absence is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Absence. If not, see . CHANGES ======= 2.1: - if "holiday_scheme" is set to "advanced", added country and region fields to the "Add Person" and "Modify Person" management forms. If the parameters "header_holiday_country" and "header_holiday_region" are set in AbsenceConfig.pm, they are used as the default values. - added ability to change username (when authentication is enabled) - changed logout mechanism to use javascript. This works for Firefox and IE, but not for Opera. Safari, Chrome et al not tested. - fixed a bug: after authenticating the string "Not Authenticated" was displayed in the upper ("control") frame. - added username to the "Logout" button, so user can see as whom he's authenticated 2.0.4: - fixed a few minor bugs: - content frame did not get reloaded after deleting an absence - 'skip-non-workdays' attribute in absence types not being honored - added copyright and licensing information to relevant files 2.0.3: - added ability to submit absence.pl a GET request to retrieve a page of month-images for a particular group, optionally starting at a particular month and for a specified number of months. The GET parameters are "group_id", "start_month", "start_year", and "num_months". 2.0.2: - added functionality to absence.pl to accept a HTTP GET request to display selected months for a particular group. 2.0.1: - fixed bug when MULTI-RES mode enabled that caused reservation conflicts not to be discovered. 2.0: tons of stuff: - no more flatfile databases. Everything except some config params goes in a real database. - added functionality to allow multiple reservations (absences) on a particular day for a particular person. Which reservation types are allowed to coincide with other types is configurable, as is the maximum height of a person-row. Person-rows can be fixed or variable height, and if variable is configured, minimum and maximums can be specified. - reservation types now have a "height" characteristic. They can be full, half, or quarter height, or "block" height. "full" height corresponds to the old reservation type; the text absence description is displayed on such reservations. The "half" and "quarter" heights are one-half and one-quarter as high as "full", and cannot accept any text. "full", "half" and "quarter" height reservations cannot overlap one another. "block" height reservations are always the current entire height of the person-row, and overlap, or underlap (depending on priority) the full/half/quarter height reservations. - reservation types can be assigned prorities, which influence whether the corresponding reservations are displayed at the top, or the bottom of a person-row. - reservation types are now administered from the "manage" page. - several old bugs have been fixed, for example one involving incorrect display of the current month/day. - since holidays are now stored in the database, there is a holiday-management script. People and Holidays can be associated with a particular country or region, thus allowing the per-person display of holidays, which might be useful if absence is used to manage virtual groups based about the world. - legacy (v1.8.x) flatfiles can be imported into the database during installation. - multiple instances are not currently supported. If you want support, let me know. - reservation-types can be configured to skip non-workdays. 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 README-AUTH.txt 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.