ABSTRACT

This class encapsulates course events.

Course Events combine a Course (name and description of a course) with a Location (a course room description) and a TeacherGroup (a group of Users; they can view subscriptions with the property tim_course_view_subscriptions_own) and a date and some flags:

Id
The ident is an internal datatype (a number). It never changes.

Location_ID
A reference to a Locations object.

Teacher_ID
A reference to a TeacherGroups object.

Date
An iso-8859-1 string describing the date; this can be anything like 'every second sunday of a month' to '1 - 5-MAR 08:30-17:30'.

Begin
A UNIX time value. Used to sort events in lists and as time limit for subscriptions.

End
A UNIX time value. Students will not see the event after this time.

Closed
A String. Any false value is interpreted as 'not closed'; Any true value is interpreted as 'closed' (students can not subscribe or unsubscribe). A true value should be a short text describing the reason, like 'canceled'.

Visible
Boolean: A true value (1) is interpreted as 'visible for students'. A false value (empty string) is interpreted as 'invisible for students'. This flag should be used to hide predefined course events, where students should not yet be able to subscribe.

Max Participants
A number > 0.

Mail Template names
for confirmation mails at subscription or unsubscription and for reminders per mail or SMS.


SYNOPSIS

 use CourseEvents;
 use Locations;
 use Courses;
 use TeacherGroups;
 use CourseSubscriptions;
 ...
 $event = CourseEvents->find(-id=>$id);
 $string = $event->date();
 $time = $event->begin();
 $event->update(...);
 $location = Locations( -id=>$event->location_id );
 $course = Courses( -id=>$event->location_id );
 $teacher = TeacherGroups( -id=>$event->location_id );
 $subscriptions = CourseSubscriptions->get_object_list( -course_event_id=>event->id );
 foreach my $subscr (@$subscriptions) {
     ...
 }


DESCRIPTION

Object Constructor

$event = CourseEvents->find( -id=>Ident );
Object constructor. CourseEvents are identified by an Ident, which is unique and will never change. If the desired event group is not found, an empty object is returned.

$event = CourseEvents->create( );
Creates an object in memory but not on the VIP database. Its content should be set with the $event->update()-method, which will update the VIP database as well if the input checks pass. The first update should define all attributes.

$aref = CourseEvents->get_object_list( );
Returns a reference to a list of eventgroup objects orderd by begin. Default is all course events. This can be reduced with arguments (if more than one is specified, they are combined with 'and'):
-course_id => $id
An ID of a Courses object.

-teacher_id => $id
An ID of a TeacherGroups object.

-teacher_id => \@ids
A reference to an array of TeacherGroups ids (a user may be a member of several teacher groups).

-location_id => $id
An ID of a Locations object.

-begin_after => $unix_time
-begin_before => $unix_time
-end_after => $unix_time
-end_before => $unix_time
-closed => 1
Closed for any reason;

-closed => 'canceled'.
Closed with reason 'canceled'.

-closed => 0
Not closed.

visible => 1
Only visible.

visible => 0
Only invisible.

$aref = EventGroups->get_id_list( ... );
Returns a reference to a list of eventgroup idents, not blessed objects. Unsorted. Same arguments as get_object_list.

Object Accessor Methods

The following methods return the current state of a eventgroup object:

$unix_time = $event->begin
$string = $event->closed
$course_id = $event->course_id
$string = $event->date
$unix_time = $event->end
$event_id = $event->id
$location_id = $event->location_id
$n = $event->max_participants
$teacher_id = $event->teacher_id
$template_name = $event->template($template_type)
where $template_type is 'subscribe_mail', 'unsubscribe_mail', 'reminder_mail' or 'reminder_sms'. It returns the corresponding template name.

$boolean = $event->visible

Object Modifier Method

($field, $errmsg) = $event->update( ... )
Updates an event (object state and data base permanent storage). Before any data is changed, all values are checked. If a check fails, the update will not change any data but return a list of two values: the name of the field and an error message. If all checks are ok, the update method will change the objects state in memory and on the VIP database and return undef. What will be updated is determinated by arguments as follows:
-course_id => $course_id
Must be an ident of a Courses object.

-teacher_id => $teacher_id
Must be an ident of a TeacherGroups object.

-location_id => $location_id
Must be an ident of a Locations object.

-date => $date
An iso-8859-1 string describing to surfers, when the event will be.

-begin => $begin
An UNIX time value

-end => $end
An UNIX time value

-closed => $string
A reason, why the event is closed; iso-8859-1; empty string is interpreted as 'not closed'.

-visible => $boolean
-max_participants => $number
$event->delete;
Deletes the object, both in memory and on the VIP database.


SEE ALSO

A CourseEvent combines a Courses.pm object with a date, a Locations.pm object and a TeacherGroups object and adds informations like max_participants, closed and visible flag.


COPYRIGHT

Copyright 2005-2014 Thedi gerber@id.ethz.ch