SchoolTool GUI Guide
====================

XXX The GUI client is deprecated, so this piece of documentation should
    probably be removed.

To start the SchoolTool GUI client, first install or unpack the software.
Then,

* On MS Windows, double-click on wxschooltool.py in the folder where you
  extracted the zip archive.

* On a Debian system, run 'wxschooltool'.

When you have run the GUI client, a Server Settings (login) dialog pops up.
There you can choose a server, a port to connect to and a user/password to
use.  The Server Settings dialog can be accessed at any time via the
Settings->Server menu item.

The window that you see after logging in is the main SchoolTool window.  It is divided
into three panes:

* The group pane, which shows you groups, subgroups and their members.

* The members pane, showing the members of a selected group.

* The relationships pane, showing all the relationships of a selected
  member.

In this document, we use the following conventions:

* The "context menu" is accessed by right-clicking on an object.

* The notation Menu->Submenu->Subsubmenu shows a particular menu item
  to select.


Organisational Structure
------------------------

SchoolTool represents a school's organisational structure as a tree of groups,
subgroups, and persons. The tree structure shows the relationship between
groups and their members. In addition to the relationship 'Membership', there
are other relationships for specific cases. For example, there is a 'Teaching'
relationship between a teacher and a class that is taught.

You can create new persons and groups using the File->New Person and
File->New Group menu items.

A group or person can be added to a parent group by selecting the parent group
in the tree, then right-clicking in its relationships pane, choosing Add Member
or Add Subgroup, and choosing a new member from the appearing list of persons
or groups respectively.

A member can be removed by breaking the membership relationship from either
side by choosing the "Remove Relationship" from the context menu of a
relationship.


Absence Tracking
----------------

A roll-call is an act of finding out which members of a group are absent
by checking either "present" or "absent" against each group member.

The group membership as used for roll calls works transitively.  That is, a
group's members and any subgroups' members and any sub-subgroups' members (and
so on) are included in the roll call.

Roll calls can be run on all the groups by right-clicking on a group in the
tree and choosing "Roll Call" in the context menu.  The roll call dialog lists
all persons in a group and presents a choice present or absent, and a facility
to add a comment.

Absences of persons can be viewed by right-clicking on a person in the
Members pane and choosing "View Absences".  Every absence can consist
of several absence comments.

An absense tracker is an object in the database that listens for absense
events, and keeps track of people who are marked as absent. An absense
tracker can be added onto any group to track absenses for that group.

To create an absence tracker for a group, right click on a group in the tree
and choose "Absence Tracker".  Later, you can use the same menu item to view
the absences collected in the tracker.


Timetables
----------

A timetable is a matrix describing the activities that occur during the periods
of a particular kind of day. For example, the activities that occur in the five
periods in each day of a four day cycle: periods 1-5, days A-D.

A timetable applies to some named period of time, or some purpose, such as
a particular year or a particular school term, or something like
"fortnightly inter-school sports coaching".

Every group or person can have a number of timetables.  First, the timetables
can vary in the timetable schema.  For instance, in a school with a 4-day
rotating timetable there might be some events recurring weekly.  Second, there
are separate timetables for different time periods, such as semesters.

Every group or person can have a number of own timetables and a number of
composite timetables.  Own timetables consist of the events private to a group
or a person, and composite timetables consist of all events related to a group or
a person.  For example, a composite timetable for a teacher will contain all the
lessons they are teaching, and a composite timetable of a pupil will contain
all the events from the private timetables of the groups the're in, in other
words -- all the lessons they need to attend.  In general, a composite
timetable cannot directly be altered, but an 'own' timetable may be altered.

The private and composite timetables of persons and groups can be viewed by
choosing the "View timetables" and "View composite timetables" in the context
menus for groups and persons.

The timetable can be edited by the school administrator by choosing
"View->School Timetable" menu item.  The user will be presented with a list of
possible timetables.  After choosing one, the user will be presented with a
grid listing all teachers as rows and all timetable periods as colums.  When a
cell of the timetable is double-clicked, a dialog for editing that cell
appears.  The dialog contains a selectable list of all the groups a given
teacher is teaching, and a button for booking of resources, including venue,
for a given timetable activity.  Conflicts in a timetable (such as booking the
same resource for two activities at the same time) are represented and no
attempt is given to try to resolve them.


Calendars
---------

A calendar applies to a particular range of dates, and describes the events
that take place on each of those days.

Every group and person has two calendars: a private calendar which can
be edited and a read-only calendar formed out of the group's or
person's composite timetable.

Mozilla Calendar or a similar calendaring application has to be used
to access the calendars.  A list of all calendars, available at
http://localhost:7001/calendars.html (if the SchoolTool server is
running on localhost port 7001) can be helpful in adding a calendar
to the calendaring application.


Resource Search and Booking
---------------------------

A resource is something that is not a person or a group that can have its
own timetables and calendars. For example, overhead projectors, meeting
rooms, portable computers, sports fields, changing rooms, minibuses.

The resource availability search dialog is accessible via the
"View->Search for Available Resources" menu item.  In this dialog, a
user can choose the resources they are interested in, the range of
dates, the hours within a day, and a minimum duration of a free period
of time.

Then, a resource can be booked by choosing a free period of time and
clicking the Book Resource button.  In the resource booking dialog,
the user has to choose the exact time and duration, the resource being
booked, and the person who is booking the resource.  Only the managers
can choose other users, teachers can choose only themselves.

When the resource is booked, an event is added to both the calendars
of the resource and of the person booking.  The booking is cancelled
if the booking event is deleted in the person's private calendar.


Security
--------

There are three kinds of users:  Pupils, Teachers, and Managers.
Mostly, pupils can only view the information on the server, teachers
can additionaly run roll calls and book resources, and the managers
can edit all information.

The username for a user is set when the user is created and cannot be
changed.  The password can be changed by the user himself or a
manager by right-clicking on a user and choosing "Change Password".

People can be given teacher or manager privileges by adding them to the
Teachers and System Managers groups respectively.

All successful user actions and failed logins are recorded in the
application log, which is accessible through the "View->Application Log"
menu item.  Each entry includes a timestamp and the user name of the person
who performed the action.  Only Managers can view the application log.

