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
 array $groups
 object|null $output
Method Summary
 GroupManager GroupManager (object &$output)
 bool add_group_capacity (int $group_id, int $capacity_code, int $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])
 int|bool calc_acl_id (int $group_id, int $capacity_code)
 void capacity_admin ()
 void capacity_save ()
 bool delete_group_capacities_records (int $group_id)
 array|bool get_dialogdef_edit_group (int $group_id)
 string get_groupname (int $group_id)
 array get_group_capacity_names (int $group_id, [int $capacity_code = 0])
 array|bool get_group_capacity_records ([ $force = FALSE])
 bool|array get_group_record (int $group_id, [bool $forced = 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 ([int $group_id = NULL])
 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 (int $group_id, [string|null $current_task = NULL], [string|null $current_capacity_code = NULL])
 void show_menu_groupcapacity (int $group_id, int $capacity_code, [string|null $current_task = NULL], [ $current_module_id = NULL], string|null $current_capacity_code)
 bool valid_group_capacity (int $group_id, int $capacity_code)
Variables
array $groups = array() (line 48)
  • var: used to cache group records keyed by group_id
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 56)

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
add_group_capacity (line 1723)

add a group/capacity and corresponding acl to the database

  • return: TRUE on success, FALSE otherwise
bool add_group_capacity (int $group_id, int $capacity_code, int $sort_order)
  • int $group_id: group of interest
  • int $capacity_code: the capacity
  • int $sort_order
areas_expand_collapse (line 1870)

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 1587)

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 1668)

retrieve the acl_id for a particular group/capacity from the database

  • return: FALSE on error, acl_id on success
int|bool calc_acl_id (int $group_id, int $capacity_code)
  • int $group_id: the group to examine
  • int $capacity_code: the capacity to examine
capacity_admin (line 1033)

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 996)

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 818)

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 1070)

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 874)

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_records (line 1779)

actually remove a group and all associated records

this actually deletes the group $group_id and associated records, in a specific order, to satisfy the FK constraints. ACL's are deleted last if there are any at all.

Note This routine looks a lot like the corresponding one in the UserManager. However, we don't know in advance how many ACLs are associated with this group whereas a user record always has exactly 1 ACL. This explains the logic in step 1 below.

  • return:

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

  • 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_records (int $group_id)
  • int $group_id: the group to delete
get_dialogdef_add_group (line 1383)

construct the add group dialog

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

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 1657)

shorthand to get the name of a group

  • return: the name of the group
string get_groupname (int $group_id)
  • int $group_id: the group of interest
get_group_capacity_names (line 1706)

shortcut to retrieve the name and full name of the selected group and optionally a capacity name

  • return: with ready-to-use name/full_name/capacity name
array get_group_capacity_names (int $group_id, [int $capacity_code = 0])
  • int $group_id: identifies the group of interest
  • int $capacity_code: identifies the capacity (optional)
get_group_capacity_records (line 1559)

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_group_record (line 1841)

retrieve a single group's record possibly from the cache

  • return: FALSE if there were errors, the group record otherwise
bool|array get_group_record (int $group_id, [bool $forced = FALSE])
  • int $group_id: identifies the group record
  • bool $forced: if TRUE unconditionally fetch the record from the database
get_icon_delete (line 1612)

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 1636)

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 1541)

construct a simple option list with all available capacity names keyed by capacity code

  • return: ready to use array with capacity names keyed by capacity code
array get_options_capacities ()
groups_overview (line 133)

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 252)

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 668)

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: 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 415)

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 ([int $group_id = NULL])
  • int $group_id: which group do we want to edit?
group_save (line 448)

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 286)

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 1258)

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 1353)

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 1273)

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 1139)

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 1301)

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 (int $group_id, [string|null $current_task = NULL], [string|null $current_capacity_code = NULL])
  • int $group_id: the group of interest
  • string|null $current_task: the name of the task to emphasise in the menu (underlined)
  • string|null $current_capacity_code: the name of the capacity to emphasise in the menu (underlined)
show_menu_groupcapacity (line 1178)

show a menu for a group capacity with options to modify privileges, etc.

etc.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME;
void show_menu_groupcapacity (int $group_id, int $capacity_code, [string|null $current_task = NULL], [ $current_module_id = NULL], string|null $current_capacity_code)
  • int $group_id: the group of interest
  • int $capacity_code: identifies the capacity to manage
  • string|null $current_task: the name of the task to emphasise in the menu (underlined)
  • string|null $current_capacity_code: the name of the capacity to emphasise in the menu (underlined)
  • $current_module_id
show_parent_menu (line 92)
void show_parent_menu ()
valid_group_capacity (line 1687)

shorthand to test the validity of a particular group/capacity

  • return: TRUE if valid combination, FALSE otherwise
bool valid_group_capacity (int $group_id, int $capacity_code)
  • int $group_id: the group to examine
  • int $capacity_code: the capacity to examine

Documentation generated on Tue, 28 Jun 2016 19:09:37 +0200 by phpDocumentor 1.4.0