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.