Class GroupManager

Description

Group management

  • todo: Perhaps this class should be merged with the UserManager class because there is a lot of overlap. Mmmmm.... maybe in a future refactoring operation.

Located in /program/lib/groupmanager.class.php (line 37)


	
			
Variable Summary
 object|null $output
Method Summary
 GroupManager GroupManager (object &$output)
 bool acl_delete (int|array $acl)
 void add_group_capacity ( $group_id,  $capacity_code,  $sort_order)
 array|bool areas_expand_collapse (array|bool $areas_open, int|null $area_id)
 array a_params ([string|null $task = NULL], [int|null $group_id = NULL], [int|null $capacity_code = NULL], [int|null $module_id = NULL])
 void calc_acl_id ( $group_id,  $capacity_code)
 void capacity_admin ()
 void capacity_save ()
 bool delete_group_capacities_acls (int $group_id)
 array|bool get_dialogdef_edit_group (int $group_id)
 void get_groupname ( $group_id)
 void get_group_capacity_names ( $group_id, [ $capacity_code = 0])
 array|bool get_group_capacity_records ([ $force = FALSE])
 string get_icon_delete (int $group_id)
 string get_icon_edit (int $group_id)
 void groups_overview ()
 void group_add ()
 void group_delete ()
 void group_edit ()
 void group_save ()
 data group_savenew ()
 bool has_job_permission (int $group_id, int $capacity_code, int $job)
 void show_breadcrumbs_groupcapacity ( $group_id,  $capacity_code)
 void show_menu_group ( $group_id, [ $current_task = NULL], [ $current_capacity_code = NULL])
 void show_menu_groupcapacity ( $group_id,  $capacity_code, [ $current_task = NULL], [ $current_module_id = NULL])
 void valid_group_capacity ( $group_id,  $capacity_code)
Variables
array|null $group_capacity_records = NULL (line 42)
  • var: caches the list of group-capacity-combinations
object|null $output = NULL (line 39)
  • var: collects the html output
bool $show_parent_menu = FALSE (line 45)
  • var: if TRUE the calling routing is allowed to use the menu area (e.g. show account mgr menu)
Methods
Constructor GroupManager (line 53)

construct a GroupManager object

This initialises the GroupManager and also dispatches the task to do.

GroupManager GroupManager (object &$output)
  • object &$output: collects the html output
acl_delete (line 1679)

remove all records relating to 1 or more acl_id's from various acl-tables

this bluntly removes all records from the various acls* tables for the specified acl_id's. Whenever there's an error deleting records, the routine bails out immediately and returns FALSE. If all goes well, TRUE is returned. Any errors are logged, success is logged to DEBUG-log.

  • return: TRUE on success, FALSE on failure
  • todo: should this routine be moved to an acl-object? Hmmm....
bool acl_delete (int|array $acl)
  • int|array $acl: the key(s) to the ACL(s) to delete
add_group_capacity (line 1711)
void add_group_capacity ( $group_id,  $capacity_code,  $sort_order)
  • $group_id
  • $capacity_code
  • $sort_order
areas_expand_collapse (line 1824)

manipulate the current state if indicator(s) for 'open' and 'closed' areas

this manipulates the current state of 'open' and 'closed' areas in $areas_open. If $area_id is NULL, we don't have to do anything but simply return the current state. If $area_id is 0 (zero), we need to toggle all areas at once (area_id = 0 implies the site level toggle) If $area_id is an integer, it is assumed to be a valid area_id and that area should be toggled.

  • return: new state of indicator(s) for 'open' and 'closed' areas
array|bool areas_expand_collapse (array|bool $areas_open, int|null $area_id)
  • array|bool $areas_open: current state of indicator(s) for 'open' and 'closed' areas
  • int|null $area_id: the area to expand/collapse or NULL if nothing needs to be done
a_params (line 1559)

shorthand for the anchor parameters that lead to the group manager

  • return: ready-to-use array with parameters for constructing a-tag
array a_params ([string|null $task = NULL], [int|null $group_id = NULL], [int|null $capacity_code = NULL], [int|null $module_id = NULL])
  • string|null $task: the next task to do or NULL if none
  • int|null $group_id: the group of interest or NULL if none
  • int|null $capacity_code: the capacity of interest or NULL if none
  • int|null $module_id: the module of interest or NULL if none
calc_acl_id (line 1637)
void calc_acl_id ( $group_id,  $capacity_code)
  • $group_id
  • $capacity_code
capacity_admin (line 1024)

show a dialog for modifying admin permissions for a group/capacity

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $CFG
void capacity_admin ()
capacity_intranet (line 987)

show a dialog for modifying intranet permissions for a group/capacity

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $CFG
void capacity_intranet ()
capacity_overview (line 821)

display an overview of all members of a group with a particular capacity

this constructs a clickable list of users that are associated with a particular combination of group_id and capacity_code. The name of the user is a link to the usermanager for that user. Users are sorted by name.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $DB
void capacity_overview ()
capacity_pagemanager (line 1061)

show a dialog for modifying page manager permissions for a group/capacity

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $CFG
void capacity_pagemanager ()
capacity_save (line 877)

save data from a dialog for a group/capacity

  • return: data saved and results are returned as readable output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $CFG
void capacity_save ()
delete_group_capacities_acls (line 1767)

actually remove a group and all associated data

this actually deletes the group $group_id and associated data, in the following order: First all acls associated with the group-capacities are deleted. If that worked, we delete the group-capacity records. If that worked, we delete the group record itself.

  • return:

    FALSE if there were errors, TRUE if delete was completely successful

  • todo: should we also require the user to delete any files associated with the area before we even consider deleting it? Or is is OK to leave the files and still delete the area. We do require that nodes are removed from the area, but that is mainly because of maintaining referential integrity. Mmmmm... Maybe that applies to the files as well, especially in a private area. Food for thought.
  • todo: since multiple tables are involved, shouldn't we use transaction/rollback/commit? Q: How well is MySQL suited for transactions? A: Mmmmm.... Which version? Which storage engine?
bool delete_group_capacities_acls (int $group_id)
  • int $group_id: the group to delete
get_dialogdef_add_group (line 1359)

construct the add group dialog

  • return: contains the dialog definition
array get_dialogdef_add_group ()
get_dialogdef_edit_group (line 1418)

construct the edit group dialog

  • return: FALSE on errors retrieving data, otherwise array containing the dialog definition
array|bool get_dialogdef_edit_group (int $group_id)
  • int $group_id: the group that will be edited
get_groupname (line 1631)
void get_groupname ( $group_id)
  • $group_id
get_group_capacity_names (line 1661)
void get_group_capacity_names ( $group_id, [ $capacity_code = 0])
  • $group_id
  • $capacity_code
get_group_capacity_records (line 1531)

return an array of group-capacity records (possibly buffered)

  • return: FALSE on error, array with records otherwise (could be empty)
  • uses: $DB
array|bool get_group_capacity_records ([ $force = FALSE])
  • $force
get_icon_delete (line 1584)

construct a clickable icon to delete this group

  • return: ready-to-use A-tag
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
string get_icon_delete (int $group_id)
  • int $group_id: the group to delete
get_icon_edit (line 1611)

construct a clickable icon to edit the properties of this group

  • return: ready-to-use A-tag
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
string get_icon_edit (int $group_id)
  • int $group_id: the group to edit
get_options_capacities (line 1513)
void get_options_capacities ()
groups_overview (line 163)

display list of existing groups and an option to add a group

this constructs the heart of the group manager: a link to add a group followed by a list of links for all existing groups and additional links per capacity per group.

This list of groups is ordered as follows. All active groups come first, the inactive groups follow. The sort order is based on the (short) name of the group.

Example:

Add a group
[D] [E] faculty (Member, Principal)
[D] [E] grade12 (Pupil, Teacher)
...
[D] [E] zebra (Member, Project lead)
[D] [E] aardvark (inactive)
[D] [E] grade45 (inactive)

Note that both the links '[E]' and 'faculty' lead to edit of group properties The links 'Member' and 'Principal' lead to the group-capacity overview screen The link '[D]' leads to a group delete confirmation screen

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
void groups_overview ()
group_add (line 282)

present 'add group' dialog where the user can enter minimal properties for a new group

this displays a dialog where the user can enter the minimal necessary properties of a new group. These properties are:

  • name (e.g. 'grade7')
  • full name (e.g. 'Pupils of grade 7')
  • the active flag
  • the allowable capacities for this group (e.g. 'Pupil' and 'Teacher')
Other properties (if any) will be set to default values and can be edited lateron by editing the group.

The new group is saved via performing the task TASK_GROUP_SAVE_NEW

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
void group_add ()
group_delete (line 712)

delete a group after confirmation

this either presents a confirmation dialog to the user OR deletes a group with associated capacities and acls.

Note that this routine could have been split into two routines, with the first one displaying the confirmation dialog and the second one 'saving the changes'. However, I think it is counter-intuitive to perform a deletion of data under the name of 'saving'. So, I decided to use the same routine for both displaying the dialog and acting on the dialog.

  • return: results are returned as output in $this->output
  • todo: should we also require the user to delete any files associated with the group before we even consider deleting it? Or is is OK to leave the files and still delete the group. Food for thought.
  • todo: since multiple tables are involved, shouldn't we use transaction/rollback/commit? Q: How well is MySQL suited for transactions? A: Mmmmm.... Which version? Which storage engine?
void group_delete ()
group_edit (line 448)

show a dialog with the basic properties of a group

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
void group_edit ()
group_save (line 479)

save an edited group to the database, including adding/modifying/deleting group/capacity-records

Note: no error checking when inserting new capacity because we more or less know that that capacity does not exist already or it would have been in the array already. (But what if there are more than GROUPMANAGER_MAX_CAPACITIES in the database? Mmmm....

  • uses: $WAS_SCRIPT_NAME;
void group_save ()
group_savenew (line 316)

save a new group to the database

this saves a new group to the database. This quite a complex task because of the number of tables involved.

First we have the table 'groups' which stores the basic group information. Then there is the table 'groups_capacities'. For every combination of group and capacity requested by the user a record must be added to this table. Then there is also a separate acl for every group_capacity, so there.

The strategy should be something like this. new_group_id = insert_new_group_into_groups() for all GROUPMANAGER_MAX_CAPACITIES do if capacity != CAPACITY_NONE && capacity_not_added_yet() prepare_new_acl_record(); new_acl_id = insert_new_acl_in_acls(); prepare_new_groups_capacities_record(); insert_new_group_capacity_in_table()

  • return: saved to the database, output created via groups_overview()
  • todo: maybe we should find a more elegant way to check a field for uniqueness
  • todo: should we delete the datadirectory if something goes wrong?
data group_savenew ()
has_job_permission (line 1242)

determine whether a group/capacity has permissions for a particular job

this determines whether this group/capacity has permissions to access the specified job, e.g. do they have access to the page manager. If so, we can display the menu option, otherwise we can suppress it and keep the menu clean(er).

  • return: TRUE if the group/capacity has the permission, FALSE otherwise
bool has_job_permission (int $group_id, int $capacity_code, int $job)
  • int $group_id: group to check
  • int $capacity_code: capacity of this group to check
  • int $job: job a bitmask indicating a particular job
show_breadcrumbs_addgroup (line 1329)

display breadcrumb trail that leads to the add new group dialog

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME;
void show_breadcrumbs_addgroup ()
show_breadcrumbs_group (line 1257)

display breadcrumb trail that leads to groups overview screen

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME;
void show_breadcrumbs_group ()
show_breadcrumbs_groupcapacity (line 1137)

display breadcrumb trail that leads to group capacity overview screen

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME;
void show_breadcrumbs_groupcapacity ( $group_id,  $capacity_code)
  • $group_id
  • $capacity_code
show_menu_group (line 1282)

show a menu for a group including links to the group's capacity overview screens

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME;
void show_menu_group ( $group_id, [ $current_task = NULL], [ $current_capacity_code = NULL])
  • $group_id
  • $current_task
  • $current_capacity_code
show_menu_groupcapacity (line 1167)
void show_menu_groupcapacity ( $group_id,  $capacity_code, [ $current_task = NULL], [ $current_module_id = NULL])
  • $group_id
  • $capacity_code
  • $current_task
  • $current_module_id
show_parent_menu (line 122)
void show_parent_menu ()
valid_group_capacity (line 1650)
void valid_group_capacity ( $group_id,  $capacity_code)
  • $group_id
  • $capacity_code

Documentation generated on Wed, 11 May 2011 23:45:10 +0200 by phpDocumentor 1.4.0