[permissionmanager] removed openRoleEdior function;

changed searchFieldFunction() to use jQuery; fixed checkboxes in
roleeditor not selecting on a click on the label; added selected row
highlighting; disabled buttons if there are no users/roles selected;
made role badges in user/location tables clickable; added phpdoc
comments to most php functions;

3 files changed, 86 insertions, 25 deletions

diff --git a/modules-available/permissionmanager/inc/getpermissiondata.inc.php b/modules-available/permissionmanager/inc/getpermissiondata.inc.php
index 13c7ca89..982fa0b7 100644
--- a/modules-available/permissionmanager/inc/getpermissiondata.inc.php
+++ b/modules-available/permissionmanager/inc/getpermissiondata.inc.php
@@ -2,9 +2,17 @@
 
 class GetPermissionData {
 
-	// get UserIDs, User Login Names, User Roles
+	/**
+	 * Get data for all users.
+	 *
+	 * @return array array of users (each with userid, username and roles (each with roleid and rolename))
+	 */
 	public static function getUserData() {
-		$res = self::queryUserData();
+		$res = Database::simpleQuery("SELECT user.userid AS userid, user.login AS login, role.rolename AS rolename, role.roleid AS roleid
+												FROM user
+												LEFT JOIN user_x_role ON user.userid = user_x_role.userid
+												LEFT JOIN role ON user_x_role.roleid = role.roleid
+												");
 		$userdata= array();
 		while ($row = $res->fetch(PDO::FETCH_ASSOC)) {
 			$userdata[$row['userid'].' '.$row['login']][] = array(
@@ -24,7 +32,11 @@ class GetPermissionData {
 		return $data;
 	}
 
-	// get LocationIDs, Location Names, Roles of each Location
+	/**
+	 * Get data for all locations.
+	 *
+	 * @return array array of locations (each including the roles that have permissions for them)
+	 */
 	public static function getLocationData() {
 		$res = Database::simpleQuery("SELECT role.roleid as roleid, rolename, GROUP_CONCAT(COALESCE(locationid, 0)) AS locationids FROM role
  												INNER JOIN role_x_location ON role.roleid = role_x_location.roleid GROUP BY roleid ORDER BY rolename ASC");
@@ -46,7 +58,11 @@ class GetPermissionData {
 		return array_values($locations);
 	}
 
-	// get all roles from database (id and name)
+	/**
+	 * Get all roles.
+	 *
+	 * @return array array roles (each with roleid and rolename)
+	 */
 	public static function getRoles() {
 		$res = Database::simpleQuery("SELECT roleid, rolename FROM role ORDER BY rolename ASC");
 		$data = array();
@@ -59,6 +75,12 @@ class GetPermissionData {
 		return $data;
 	}
 
+	/**
+	 * Get permissions and locations for a given role.
+	 *
+	 * @param string $roleid id of the role
+	 * @return array array containing an array of permissions and an array of locations
+	 */
 	public static function getRoleData($roleid) {
 		$query = "SELECT roleid, rolename FROM role WHERE roleid = :roleid";
 		$data = Database::queryFirst($query, array("roleid" => $roleid));
@@ -77,14 +99,4 @@ class GetPermissionData {
 		return $data;
 	}
 
-	// UserID, User Login Name, Roles of each User
-	private static function queryUserData() {
-		$res = Database::simpleQuery("SELECT user.userid AS userid, user.login AS login, role.rolename AS rolename, role.roleid AS roleid
-												FROM user
-													LEFT JOIN user_x_role ON user.userid = user_x_role.userid
-													LEFT JOIN role ON user_x_role.roleid = role.roleid
-												");
-		return $res;
-	}
-
 }
\ No newline at end of file
diff --git a/modules-available/permissionmanager/inc/permissiondbupdate.inc.php b/modules-available/permissionmanager/inc/permissiondbupdate.inc.php
index f144b35e..ffe5fac0 100644
--- a/modules-available/permissionmanager/inc/permissiondbupdate.inc.php
+++ b/modules-available/permissionmanager/inc/permissiondbupdate.inc.php
@@ -2,7 +2,12 @@
 
 class PermissionDbUpdate {
 
-	// insert new user_x_role to database. "ignore" to ignore duplicate entry try
+	/**
+	 * Insert all user/role combinations into the user_x_role table.
+	 *
+	 * @param array $users userids
+	 * @param array $roles roleids
+	 */
 	public static function addRoleToUser($users, $roles) {
 		$query = "INSERT IGNORE INTO user_x_role (userid, roleid) VALUES (:userid, :roleid)";
 		foreach($users AS $userid) {
@@ -12,24 +17,34 @@ class PermissionDbUpdate {
 		}
 	}
 
-	// remove user_x_role entry from database
+	/**
+	 * Remove all user/role combinations from the user_x_role table.
+	 *
+	 * @param array $users userids
+	 * @param array $roles roleids
+	 */
 	public static function removeRoleFromUser($users, $roles) {
 		$query = "DELETE FROM user_x_role WHERE userid IN (:users) AND roleid IN (:roles)";
 		Database::exec($query, array("users" => $users, "roles" => $roles));
 	}
 
-	// delete role, delete user_x_role relationships, delete role_x_location relationships, delete role_x_permission relationships
+	/**
+	 * Delete role from the role table.
+	 *
+	 * @param string $roleid roleid
+	 */
 	public static function deleteRole($roleid) {
-		$query = "DELETE FROM role WHERE roleid = :roleid";
-		Database::exec($query, array("roleid" => $roleid));
-		$query = "DELETE FROM user_x_role WHERE roleid = :roleid";
-		Database::exec($query, array("roleid" => $roleid));
-		$query = "DELETE FROM role_x_location WHERE roleid = :roleid";
-		Database::exec($query, array("roleid" => $roleid));
-		$query = "DELETE FROM role_x_permission WHERE roleid = :roleid";
-		Database::exec($query, array("roleid" => $roleid));
+		Database::exec("DELETE FROM role WHERE roleid = :roleid", array("roleid" => $roleid));
 	}
 
+	/**
+	 * Save changes to a role or create a new one.
+	 *
+	 * @param string $rolename rolename
+	 * @param array $locations array of locations
+	 * @param array $permissions array of permissions
+	 * @param string|null $roleid roleid or null if the role does not exist yet
+	 */
 	public static function saveRole($rolename, $locations, $permissions, $roleid = NULL) {
 		if ($roleid) {
 			Database::exec("UPDATE role SET rolename = :rolename WHERE roleid = :roleid",
diff --git a/modules-available/permissionmanager/inc/permissionutil.inc.php b/modules-available/permissionmanager/inc/permissionutil.inc.php
index cd7fb09a..cb70c8bb 100644
--- a/modules-available/permissionmanager/inc/permissionutil.inc.php
+++ b/modules-available/permissionmanager/inc/permissionutil.inc.php
@@ -2,6 +2,14 @@
 
 class PermissionUtil
 {
+	/**
+	 * Check if the user has the given permission (for the given location).
+	 *
+	 * @param string $userid userid to check
+	 * @param string $permissionid permissionid to check
+	 * @param int|null $locationid locationid to check or null if the location should be disregarded
+	 * @return bool true if user has permission, false if not
+	 */
 	public static function userHasPermission($userid, $permissionid, $locationid) {
 		$locations = array();
 		if (!is_null($locationid)) {
@@ -27,6 +35,13 @@ class PermissionUtil
 		return false;
 	}
 
+	/**
+	 * Get all locations where the user has the given permission.
+	 *
+	 * @param string $userid userid to check
+	 * @param string $permissionid permissionid to check
+	 * @return array array of locationids where the user has the given permission
+	 */
 	public static function getAllowedLocations($userid, $permissionid) {
 
 		$res = Database::simpleQuery("SELECT permissionid, COALESCE(locationid, 0) AS locationid FROM user_x_role
@@ -51,6 +66,13 @@ class PermissionUtil
 		return $allowedLocations;
 	}
 
+	/**
+	 * Extend an array of locations by adding all sublocations.
+	 *
+	 * @param array $tree tree of all locations (structured like Location::getTree())
+	 * @param array $locations the array of locationids to extend
+	 * @return array extended array of locationids
+	 */
 	public static function getSublocations($tree, $locations) {
 		$result = array_flip($locations);
 		foreach ($tree as $location) {
@@ -65,6 +87,11 @@ class PermissionUtil
 		return array_keys($result);
 	}
 
+	/**
+	 * Get all permissions of all active modules that have permissions in their permissions/permissions.json file.
+	 *
+	 * @return array permission tree as a multidimensional array
+	 */
 	public static function getPermissions()
 	{
 		$permissions = array();
@@ -89,6 +116,13 @@ class PermissionUtil
 		return $permissions;
 	}
 
+	/**
+	 * Place a permission into the given permission tree.
+	 *
+	 * @param string $permission the permission to place in the tree
+	 * @param string $description the description of the permission
+	 * @param array $tree the permission tree to modify
+	 */
 	private static function putInPermissionTree($permission, $description, &$tree)
 	{
 		$subPermissions = explode('.', $permission);