Class AclManager

Description

class for manipulating (edit+save) access control lists

Overview
--------

Every user account is associated with an access control list. This access control list boils down to a total of six tables in the database:

  • acls
  • acls_areas
  • acls_nodes
  • acls_modules
  • acls_modules_areas
  • acls_modules_nodes
These tables are defined as follows.
acls:
acl_id                serial*
permissions_jobs      int
permissions_intranet  int
permissions_modules   int
permissions_nodes     int

acls_areas:
acl_id                int* (link to acls)
area_id               int* (link to areas)
permissions_intranet  int
permissions_modules   int
permissions_nodes     int

acls_nodes:
acl_id                int* (link to acls)
node_id               int* (link to nodes)
permissions_modules   int
permissions_nodes     int

acls_modules:
acl_id                int* (link to acls)
module_id             int* (link to modules)
permissions_modules   int

acls_modules_areas:
acl_id                int* (link to acls)
module_id             int* (link to modules)
area_id               int* (link to areas)
permissions_modules   int

acls_modules_nodes:
acl_id                int* (link to acls)
module_id             int* (link to modules)
node_id               int* (link to nodes)
permissions_modules   int

*marked fields are (part of) the primary key

The six tables mentioned above deal with the following permission bitmasks.

  • permissions_jobs
  • permissions_intranet
  • permissions_modules
  • permissions_nodes
The reasons to split these permission masks into six tables are:

  1. Some permissions only apply to the site-level and it makes no sense to specify them for a particular combination of area, node or module. Example: permissions_jobs.
2. Some permissions can be granted for current and future objects. Example: permissions_intranet. If these permissions are granted at the site level (in table acls), then they apply not oly to all current protected areas but also to all future protected areas. The same permissions could be granted on a per-area-basis but that might require adjusting the permissions once a new protected area is added to the site.

3. Sometimes it is more convenient to specify the permissions on a higher level because otherwise the size of the database may get out of hand. Example: if every user has a permission bitmask for every node on the site, the corresponding acl would have number_of_users x number_of_nodes entries. That is completely unmanageable, even for small to medium size sites.

Users and group/capacities
--------------------------

A user can also participate in a group in a particular capacity, e.g. member of group 'grade8' in the 'pupil'- or the 'teacher'-capacity. Every combination of group and capacity (eg 'grade8/pupil') is also associated with an access control list.

The full access control list for a user is the combination of the ACL directly associated with the user account and the ACLs associated with the group/capacities that apply to the user account. The effective permissions for a user are the result of OR'ing the permissions of all ACLs.

A specific permission is always indicated by a bit set to '1'. If a particular bit is set to '0', the user does not have the corresponding permission. This implies that the (special) bitmask 0 (zero, 32 bits are all not set) corresponds to 'no permissions at all'. It also implies that the (special) bitmask -1 (minus one, 32 bits are all set) equates to 'all permissions'.

Therefore, the *easy* way to grant access is to set the permissions bitmask to -1. This is the so-called Guru-option or -role or the Guru-permissions. However, note that granting a user or a group/capacity Guru-permissions, means that that user (these users) can do serious harm to the system because she (they) are allowed to do anything. The *safe* way is to grant as few permissions as possible.

Roles
-----

In order to make it easier to setup the access controls and stay away from directly manipulating individual bits in a bitmask the various permission bits are combined into roles.

Two roles are always available for selection:

  • permissions == 0: ROLE_NONE
  • permissions == -1: ROLE_GURU
Defining other roles is done at the appropriate place, e.g. inside the code for a module.

Example: suppose that there is a module called 'Forum' which works with authenticated users. Depending on this module's permission bits the users are allowed to perform certain actions, e.g.

  • read messages in the forum (bit 0, value 1)
  • write messages in the forum (bit 1, value 2)
  • edit their own messages (bit 2, value 4)
  • edit other users' messages (bit 3, value 8)
  • manage useraccounts for the forum (bit 4, value 8)
This leads to many possible combinations of set and reset bits. However, it is more practical to combine these bits into a few roles with a descriptive name:

  • permissions = 1: ROLE_FORUM_VISITOR => "Visitor"
  • permissions = 1+2+4 = 7: ROLE_FORUM_MEMBER => "Member"
  • permissions = 1+2+4+8 = 15: ROLE_FORUM_MODERATOR => "Moderator"
  • permissions = 1+2+4+8+16 = 31: ROLE_FORUM_ADMINISTRATOR => "Administrator"
By using these symbolic names for certain combinations of bitmasks it becomes easier to manage many users and many forums without having to know what every bit means, exactly.

Obviously these roles (defined via the module in this example) will end up in a dropdown list where the appropriate role can be assigned.

Note that it is not necessary to have hierarchical roles as demontrated in this example. It is very wel possible to define two roles that must work together: ROLE_EDITOR could be a bitmask that allows for adding (1), editing (2), deleting (4), previewing (8) news articles whereas ROLE_PUBLISHER could be limited to previewing (8) and publishing (16) news articles, but not editing them. That would make sure that at least two different people are required to create and publish an article. (However, any 'Guru', with all permissions granted due to the -1 bitmask, could create + publish articles by herself.)

Module-permissions in acls, acls_areas and acls_nodes
-----------------------------------------------------

The fields permissions_modules in the tables acls, acls_areas and acls_nodes should be considered as 'blanket permissions'. If a permission is set in either of these tables, the permissions apply to *all* modules at site level (acls), area_level (acls_areas) or node_level (acls_nodes).

Because these permissions apply to *all* modules, the only realistic roles in these cases can be either ROLE_NONE (permissions = 0) or ROLE_GURU (permissions = -1). Any other role could be meaningless for one or more modules.

Furthermore, it is a little over the top to specify permissions for *all* modules in a particular node. (It almost doesn't make sense). Therefore, the corresponding dialog only deals with these two roles ROLE_NONE and ROLE_GURU at the site level and the area level. The node level is not used for modules (but it is for pagemanager permissions - the field permissions_nodes - at the node level).

Typical usage
-------------

Example 1: displaying a dialog with intranet permissions for a group

$acl = new AclManager($output,$acl_id,ACL_TYPE_INTRANET);
$acl->set_action(array('job'=>'accountmanager','task'=>'groupsave','group'=>'8');
$acl->set_dialog(GROUPMANAGER_DIALOG_INTRANET);
$acl->show_dialog();
...
The result of this snippet is that a complete dialog is output to the content area of the $output object, including the current values from the database. The whole dialog is wrapped in a FORM-tag with action property based in the array set with the set_action() method. The dialog is POSTed with either a Save, a Done or a Cancel button.

Example 2: saving the data for the intranet permissions for a group

$acl = new AclManager($output,$acl_id,ACL_TYPE_INTRANET);
$acl->set_action(array('job'=>'accountmanager','task'=>'groupsave','group'=>'8');
$acl->set_dialog($dialog);
if (!$acl->save_data()) {
    $acl->show_dialog(); // redo dialog, but without a distracting menu this time
    return;
}
...

The effect of this snippet is that an attempt is done to validate and save the data as it was POSTed (ie: the new values area available in $_POST[]). If, however, saving the data did not work, the dialog is displayed again, this time using the data from $_POST[] rather than from the database.

Example 3: displaying a dialog with admin permissions for a user

$related_acls = array($acl_id1 => "group1/capacity1",$acl_id2 => "group2/capacity2", ...);
$acl = new AclManager($this->output,$acl_id,ACL_TYPE_ADMIN);
$acl->set_related_acls($related_acls);
$acl->set_action(array('job'=>'accountmanager','task'=>'usersave','user'=>'23');
$acl->set_dialog(USERMANAGER_DIALOG_ADMIN);
$acl->show_dialog();

This comparable to example 1. The difference is that in a User-ACL there is an option to display existing permissions from the user's group/capacities. This information is displayed in the third column in the dialog. This provides a clue for the user that certain permissions might already be granted to the user via a group membership. The related permissions are communicated via an array with (integer) acl_id's as key and a string value identifying the group/capacity.

  • todo: there is someting not right with buffering the tabledefs. If an error occurs, we get FALSE instead of an array. Mmmmm....

Located in /program/lib/aclmanager.class.php (line 322)


	
			
Variable Summary
Method Summary
 void AclManager (object &$output, int $acl_id, int $acl_type)
 int|bool calc_areas_total (array &$areas)
 array dialog_tableform (string $href, array &$dialogdef, [ $show_related = FALSE])
 void enable_area_view (array $a_params, array|bool $areas_open)
 void enable_pagination (array $a_params, int $limit, int $offset)
 array get_dialogdef_admin (int $acl_id, [array $related_acls = NULL])
 array get_dialogdef_intranet (int $acl_id, [array $related_acls = NULL])
 void get_dialogdef_pagemanager ( $acl_id,  $related_acls)
 string get_icon_area (int $area_id, bool $area_is_open, int $offset)
 array get_permissions (int $acl_id, [array|null $related_acls = NULL])
 array get_permissions_areas (int $acl_id, [array|null $related_acls = NULL], [array|null $areas = NULL])
 array get_permissions_nodes_in_area (array $area_id, int $acl_id, [array|null $related_acls = NULL])
 array get_roles_pagemanager ([int $level = ACL_LEVEL_NONE])
 bool save_data ()
 bool save_data_admin ()
 void set_action ([array $a_params = NULL])
 void set_dialog ([int $dialog = 0])
 void set_header ([string $header = ''])
 void set_intro ([string $intro = ''])
 void set_related_acls ([array $related_acls = NULL])
 void show_dialog ()
 void show_tree_walk (array &$dialogdef, array &$tree, array &$permissions_nodes, int &$index, int $node_id, int $first, int $last, int $acl_id, array|null &$related_acls)
 array tree_build (int $area_id, int $acl_id, array|null $related_acls)
Variables
int $acl_id (line 330)
  • var: $acl_id identifies the ACL we are dealing with
int $acl_type (line 333)
  • var: $acl_type identifies the type of ACL we are dealing with
array|bool $area_view_areas_open = FALSE (line 374)
  • var: $area_view_areas_open identifies which areas are currently 'open' and 'closed'
array $area_view_a_params = NULL (line 371)
  • var: $area_view_a_params holds the parameters for linking to opening/closing an area
bool $area_view_enabled = FALSE (line 377)
  • var: $area_view_enabled if TRUE we add icons to areas so they can expand/collapse (default=FALSE)
array|null $a_params_save = NULL (line 339)
  • var: $a_params_save holds the parameters for the action property of the HTML-form that is created
int $dialog (line 348)
  • var: $dialog identifies the exact dialog and it is added to the dialog as hidden field
array $dialogdef = NULL (line 388)
  • var: $dialogdef holds the current dialogdef, maybe including error messages from a failed validation
array $dialogdef_areas = array() (line 395)
  • var: $dialogdef_areas holds information of zero or more areas and the number of contained nodes
int $dialogdef_areas_total = NULL (line 392)
  • var: $dialogdef_areas_total holds the total number of items that could be displayed in the dialogdef
string $header (line 342)
  • var: $header the title of the dialog, displayed at the top of the content area
string $intro (line 345)
  • var: $intro the introductory text for the dialog, displayed below the $header
object|null $output = NULL (line 327)
  • var: collects the html output
array $pagination_a_params = NULL (line 355)
  • var: $pagination_a_params holds the parameters for linking to another view of the dialog
bool $pagination_enabled = FALSE (line 364)
  • var: $pagination_enabled if TRUE we do try to paginate the display (default=FALSE)
int $pagination_limit = NULL (line 358)
  • var: $pagination_limit the preferred size of a screenfull of dialog lines
int $pagination_offset = NULL (line 361)
  • var: $pagination_offset the record where the current screen begins
bool $pagination_total (line 384)
  • var: $pagination_total holds the total number of elements to display
array $related_acls = NULL (line 336)
  • var: $related_acls if not NULL identifies a list of acl_id => 'description' pairs with related ACLs
Methods
Constructor AclManager (line 408)

constructor for the AclManager

this constructs a new AclManager object. Essential inforation such as the acl_id and the acl_type are stored, for future reference.

  • return: object setup and data buffered
void AclManager (object &$output, int $acl_id, int $acl_type)
  • object &$output: holds the output that eventually is send to the user's browser
  • int $acl_id: identifies the ACL we are dealing with (primary key in acls table)
  • int $acl_type: identifies the type of ACL we are dealing with, e.g. ACL_TYPE_INTRANET or ACL_TYPE_ADMIN
calc_areas_total (line 902)

calculate the total number of items (site, areas, nodes) to show in dialog

the 'open' or 'closed' status of an area is dictated by $open_areas:

  • if $open_areas is an array the elements look like $area_id => $show, where $show == TRUE indicates the area is 'open' and $show == FALSE indicates the area is 'closed'
  • if $open_area is a boolean and the value is TRUE. _all_ areas are to be considered 'open'
  • otherwise _all_ areas are to be considered 'closed'.
The returned value $total is the sum of the number of areas and the number of 'showable' nodes (as per the information in $open_areas). If there are no areas at all, $total is 0. If an error occurs, this routine returns FALSE.

The parameter $areas is used as a return value. It is keyed with $area_id and filled with pertinent information about the areas:

  • int $area_id: the number of the area (also the key of the the $areas array)
  • string $title the name of the area
  • bool $is_active indicating an active area (TRUE) or an inactive area (FALSE)
  • int $nodes the total number of nodes in this area (could be 0 if no nodes were added yet)
  • int permissions_nodes the bitmap containing the existing node permissions for this area
Also, the following information is added to the resulting array:
  • bool $show if TRUE, all nodes in this area should be displayed
  • int $first indicating the offset of the row for this area, relative from the start of the list of areas
  • int $last indicating the offset of the last item to show in this area (could be the same as $first)
The latter three values are used to skip $offset rows when constructing the dialog.

  • return: FALSE on error + &$areas empty OR the number of items to show + &$areas filled with summary data
  • uses: $DB;
int|bool calc_areas_total (array &$areas)
  • array &$areas: an array with summary information about areas, including the # of nodes to show
dialog_tableform (line 1465)

construct a form with a dialog in a table with 2 or 3 columns

this constructs a 2- or 3-column table and fills it with data from the dialogdef.

The first column holds the labels for the widgets. The second column holds the corresponding widget, e.g. a list box with roles. The optional third column (depends on the flag $show_related) shows related information. This is used to list group/capacities and roles from related groups (ie. groups of which the user is a member).

The table has headers for the columns: 'Realm','Role' and optional 'Related'. Rows in the table can have alternating colours via the odd/even class. This is done via the stylesheet.

  • return: constructed HTML-form with dialog, one line per array element
  • todo: bailing out on non-array is a crude way of error handling: this needs to be fixed
array dialog_tableform (string $href, array &$dialogdef, [ $show_related = FALSE])
  • string $href: the target of the HTML form
  • array &$dialogdef: the array which describes the complete dialog
  • $show_related
enable_area_view (line 532)

further initialise the AclManager and enable the area expand/collapse feature

this stores the necessary information about 'open' and 'closed' areas. The parameter $areas_open indicates the current state of affairs: ($areas_open === FALSE) means all areas are closed ($areas_open === TRUE) means all areas are opened If $areas_open is an array, it contains area_id's as key and TRUE or FALSE as value. A value of TRUE indicates that an area is currently 'open', FALS or no value set means 'closed'.

The parameters in $a_params combined with $WAS_SCRIPT_NAME yield an URL where the changes are processed.

  • return: data is buffered and the area expand/collapse feature is enabled
void enable_area_view (array $a_params, array|bool $areas_open)
  • array $a_params: basic parameters (excluding $area) that lead to the page where expand/collapse is processed
  • array|bool $areas_open: indicator(s) for 'open' and 'closed' areas
enable_pagination (line 504)

further initialise the AclManager and enable the dialog pagination feature

this stores the information that is necessary when a dialog has to be broken up into two or more screens (via the pagination facility in $output). This routine stores the essential information such as the parameters that lead to the correct page (in $a_params) and the current offset. The other necessary parameters are calculated dynamically before add_pagination() is called.

Note that pagination is only enabled after this routine is called at least once; by default we do NOT do pagination. (Actually: pagination is only used in the acl_types ACL_TYPE_PAGEMANAGER and ACL_TYPE_MODULE).

  • return: data is buffered and the pagination feature is enabled
  • uses: $CFG;
void enable_pagination (array $a_params, int $limit, int $offset)
  • array $a_params: basic parameters (excluding $offset and $limit) that lead to the correct page
  • int $limit: the preferred size of a screenfull of dialog lines
  • int $offset: the record where the current screen begins
get_dialogdef_admin (line 1145)

construct an array with the admin dialog information

this creates an array with widgets for all possible admin jobs for $acl_id.

This dialog is supposed to be rendered as a 2-column (group acl) or 3 column (user acl) table. The contents of the 3rd column is a list (an array) of related permissions, ie. the permissions a user has been granted via a group membership. The related information is stored in an extra array element 'related'.

The related information is constructed only in the case where $related_acls is not NULL.

The dialog is filled with the current values via $item['value'] but as a side effect the current value is also recorded in $item['old_value']). This makes it easier to determine whether any values have changed (see save_data_admin()).

  • return: the admin dialog information
  • todo: handle the related information in this dialog
array get_dialogdef_admin (int $acl_id, [array $related_acls = NULL])
  • int $acl_id: the acl of interest
  • array $related_acls: NULL or a list of acl_id => "group/capacity" pairs for related permissions
get_dialogdef_intranet (line 1026)

construct an array with the intranet dialog information

this creates an array with 1 or more list boxes with the current roles for $acl_id for intranet access at the site level and for individual private areas. This dialog is supposed to be rendered as a 2-column (group acl) or 3 column (user acl) table. The contents of the 3rd column is a list (an array) of related permissions, ie. the permissions a user has been granted via a group membership. The related information is stored in an extra array element 'related'.

The related information is constructed only in the case where $related_acls is not NULL.

The dialog is filled with the current values via $item['value'] but as a side effect the current value is also recorded in $item['old_value']). This makes it easier to determine whether any values have changed (see save_data_internet()).

  • return: the intranet dialog information
  • todo: handle the related information in this dialog
array get_dialogdef_intranet (int $acl_id, [array $related_acls = NULL])
  • int $acl_id: the acl of interest
  • array $related_acls: NULL or a list of acl_id => "group/capacity" pairs for related permissions
get_dialogdef_pagemanager (line 1240)

construct a dialog definition for pagemanager permissions

void get_dialogdef_pagemanager ( $acl_id,  $related_acls)
  • $acl_id
  • $related_acls
get_icon_area (line 1886)

construct a clickable icon to open/close this area

This is a toggle: if the area is closed the closed icon is shown, but the action in the A-tag is to open the icon (and vice versa).

  • return: ready-to-use HTML-icon
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
string get_icon_area (int $area_id, bool $area_is_open, int $offset)
  • int $area_id: the area to open/close (0 means: open site level)
  • bool $area_is_open: current status
  • int $offset: the position of this icon in the current list of items
get_permissions (line 1559)

retrieve an array with 0, 1 or more records with permissions from table 'acls'

this constructs an array with all (or selected) permissions from the 'acls' table for the specified acl $acl_id and optionally for all related acl_id's in $related_acls. The resulting array is keyed by acl_id.

  • return: 0, 1 or more acls-records keyed by acl_id
array get_permissions (int $acl_id, [array|null $related_acls = NULL])
  • int $acl_id: the primary acl_id (used for both users and groups)
  • array|null $related_acls: an array with related acls for this user or NULL for group acls
get_permissions_areas (line 1593)

retrieve an array with 0, 1 or more records with permissions from table 'acls_areas'

this constructs an array with all permissions from the 'acls_areas' table for the specified acl $acl_id and optionally for all related acl_id's in $related_acls and optional areas. The resulting array is keyed by area_id and acl_id.

Note that by making the result keyed by area_id first (and then acl_id) it becomes possible to step throug a list of areas and have 0,1 or more acls for that area in a single array, e.g. $acls = $permissions[16] yields the selected acls that apply to area 16. That is handy when constructing dialogs iterating through areas such as intranet permissions.

  • return: 0, 1 or more acls-records keyed by area_id and acl_id
array get_permissions_areas (int $acl_id, [array|null $related_acls = NULL], [array|null $areas = NULL])
  • int $acl_id: the primary acl_id (used for both users and groups)
  • array|null $related_acls: an array with related acls for this user keyed by 'acl_id' or NULL for group acls
  • array|null $areas: an array with areas of interest keyed by 'area_id' or NULL for all areas
get_permissions_nodes_in_area (line 1648)

retrieve an array with 0, 1 or more records with permissions from table 'acls_nodes'

this constructs an array with all permissions from the 'acls_nodes' table for the specified acl $acl_id and optionally for all related acl_id's in $related_acls and optional nodes. The resulting array is keyed by node_id and acl_id.

Note that by making the result keyed by node_id first (and then acl_id) it becomes possible to step throug a list of nodes and have 0,1 or more acls for that node in a single array, e.g. $acls = $permissions[16] yields the selected acls that apply to node 16. That is handy when constructing dialogs iterating through nodes such as pagemanager permissions.

  • return: 0, 1 or more acls-records keyed by node_id and acl_id
array get_permissions_nodes_in_area (array $area_id, int $acl_id, [array|null $related_acls = NULL])
  • array $area_id: the area where the nodes reside
  • int $acl_id: the primary acl_id (used for both users and groups)
  • array|null $related_acls: an array with related acls for this user keyed by 'acl_id' or NULL for group acls
get_roles_intranet (line 1384)

contstruct an option list with roles for intranet access

  • return: ready-to-use options array for listbox or radiobuttons
array get_roles_intranet ()
get_roles_pagemanager (line 1402)

construct an option list with roles for pagemanager access

  • return: ready-to-use options array for listbox or radiobuttons
array get_roles_pagemanager ([int $level = ACL_LEVEL_NONE])
  • int $level: limits permissions to level 'page', 'section', 'area' or 'site'
save_data (line 579)

save the changed data for the selected acl_type

this interprets the data from the selected dialog and saves the (changed) permission data accordingly. This, too, is merely a dispatcher to the subroutines that do the actual work.

  • return: FALSE on error, TRUE otherwise
bool save_data ()
save_data_admin (line 765)

save changed job permissions to the database

this saves the changed job permissions to the acls table.

If the user selected the guru option, we simply set the permissions to JOB_PERMISSION_GURU (i.e. all permissions set). If not, we iterate through all existing permissions and set the corresponding bits. Then the data is saved to the correct acls-record. After that we re-read the dialogdef again because the user may want to continue editing rather than be [Done] with job permissions.

  • return: FALSE on error, TRUE otherwise
  • todo: fix the crude error check on dialogdef === FALSE here
bool save_data_admin ()
save_data_intranet (line 640)

save the changed roles for intranet access to the tables 'acls' and 'acls_areas'

this interprets the data from the intranet dialog and saves the changed roles accordingly

  • return: FALSE on error, TRUE otherwise
bool save_data_intranet ()
save_data_pagemanager (line 989)

save the changed roles for pagemanager to the tables 'acls' and 'acls_areas' and 'acls_nodes'

this interprets the data from the pagemanager dialog and saves the changed roles accordingly

  • return: FALSE on error, TRUE otherwise
bool save_data_pagemanager ()
save_data_permissions (line 655)

save the changed roles in the dialog to the corresponding tables 'acls'

this interprets the data from the current dialog and saves the changed roles accordingly. Note that the information about tables and fields etc. is all contained in the dialogdef so we can use this generic save_data() routine.

  • return: FALSE on error, TRUE otherwise
bool save_data_permissions ()
set_action (line 439)

further initialise the AclManager with the dialog action property

this stores an array with parameters that must be added to the action property of the HTML form that will be POSTed, i.e. the URL to which the dialog will be posted. Example of such an array is: array('job' => 'accountmanager', 'task' => 'user_save', 'user' => 123); The information in this array is later combined with WAS_SCRIPT_NAME.

  • return: data is buffered
void set_action ([array $a_params = NULL])
  • array $a_params
set_dialog (line 480)

further initialise the AclManager with the dialog identification

this stores an integer number that is used to identify the dialog. This number is subsequently added to the dialog as a hidden field, which makes it possible to identify the dialog once it is POSTed

  • return: data is buffered
void set_dialog ([int $dialog = 0])
  • int $dialog: a unique identification (within this job) of the dialog
set_header (line 453)

further initialise the AclManager with the dialog header

this stores a string that is used as a title for the dialog Note that this header may be extended with a (translated) string like '[{FIRST}-{LAST} of {TOTAL}]' in case of a paginated display.

  • return: data is buffered
void set_header ([string $header = ''])
  • string $header: text to show as title
set_intro (line 466)

further initialise the AclManager with the dialog introductory text

this stores a string that is displayed after the dialog header. This text supposedly contains some more information about the dialog.

  • return: data is buffered
void set_intro ([string $intro = ''])
  • string $intro: introductory text for the dialog
set_related_acls (line 423)

further initialise the AclManager with related Acl's

this stores the array with 0, 1 or more key-value-pairs of the form $acl_id => $group_capacity_name, e.g. 3 => 'staff/member', 4 => 'grade7/teacher'

  • return: data is buffered
void set_related_acls ([array $related_acls = NULL])
  • array $related_acls: identifies a list with related ACLs
show_dialog (line 547)

show the dialog where the selected Acl can be modified

this shows the dialog corresponding to the acl_type that was previously selected, including existing data from the previously selected acl_id. Note that this routine is only a simple dispatcher; actual work is done in subroutines.

  • return: output added to $output object
void show_dialog ()
show_dialog_admin (line 738)

display a tabular form for manipulating admin permissions

This dialog is a table consisting of 2 (group acl) or 3 (user acl) columns. The first column holds the various job names/descriptions. The second column holds a checkbox for the job. The optional third column holds corresponding (existing) permissions based on a group/capacity membership of the user. This 3rd column is displayed only when there are related acls (indicated via related_acls not empty)

void show_dialog_admin ()
show_dialog_intranet (line 620)

display a tabular form for manipulating intranet permissions

This dialog is a table consisting of 2 (group acl) or 3 (user acl) columns. The first column holds the text 'All areas' or the name of a private area (if any) The second column holds a listbox where the user can select 1 out of 3 roles: 0 = "--", 1 = "Access", -1 = "Guru". The optional third column holds corresponding (existing) roles based on a group/capacity membership of the user. This 3rd column is displayed only when there are related acls (indicated via related_acls not empty)

void show_dialog_intranet ()
show_dialog_pagemanager (line 842)

display a tabular form for manipulating pagemanager permissions

This dialog is a table consisting of 2 (group acl) or 3 (user acl) columns. The first column identifies the site, areas or nodes within areas. The second column holds a listbox where the user can select a role for that particular item. The roles 0 = "--" and -1 = "Guru" are always available. The optional third column holds corresponding (existing) roles based on a group/capacity membership of the user. This 3rd column is displayed only when there are related acls (indicated by $related_acls not being empty).

The main purpose of this routine is to show some $this->pagination_limit table rows (starting at $this->pagination_offset) and corresponding [Save], [Done] and [Cancel] buttons that eventually lead to the save routine. (If pagination is not enabled, the full overview is displayed).

Note that the actual pagination is performed in get_dialogdef_pagemanager(). The additional feature of expanding/collapsing areas in the display is also done in get_dialogdef_pagemanager().

  • uses: $WAS_SCRIPT_NAME
  • uses: $CFG;
void show_dialog_pagemanager ()
show_tree_walk (line 1799)

add the specified node to dialogdef, optionally all subtrees, and subsequently all siblings

this routine adds a widget to the dialogdef for the specified node After that, any subtrees of this node are added too, using recursion This continues for all siblings of the specified node until there are no more (indicated by a sibling_id equal to zero).

void show_tree_walk (array &$dialogdef, array &$tree, array &$permissions_nodes, int &$index, int $node_id, int $first, int $last, int $acl_id, array|null &$related_acls)
  • array &$dialogdef: collects the widgets
  • array &$tree: a reference to the complete tree built earlier
  • array &$permissions_nodes: contains permissions per node
  • int &$index: only add node to dialogdef if $index is between $first and $last, increments for every node
  • int $node_id: the first node of this tree level to show
  • int $first: lower bound of interval
  • int $last: upper bound of interval
  • int $acl_id: the acl we are rendering
  • array|null &$related_acls: an array with related acls for this user keyed by 'acl_id' or NULL for group acls
tree_build (line 1707)

build a tree of all nodes in an area

this routine constructs a tree-structure of all nodes in area $area_id in much the same way as tree_build() does. However, in this routine we keep the cargo limited to a minimum: the fields we retrieve from the nodes table and store in the tree are:

  • node_id
  • parent_id
  • is_page
  • title
  • link_text
  • module_id
Also, the tree is not cached because that does not make sense here: we only use it to construct a dialogdef and that is a one-time operation too.

  • return: ready to use tree structure w/ permissions
array tree_build (int $area_id, int $acl_id, array|null $related_acls)
  • int $area_id: the area for which to build the tree
  • int $acl_id: the primary acl_id (used for both users and groups)
  • array|null $related_acls: an array with related acls for this user keyed by 'acl_id' or NULL for group acls

Documentation generated on Tue, 28 Jun 2016 19:07:44 +0200 by phpDocumentor 1.4.0