From 2040275191f2e808d1c721f98342506fc955ba43 Mon Sep 17 00:00:00 2001
From: Jannik Schönartz
Date: Tue, 21 Mar 2017 13:52:23 +0100
Subject: Locationinfo: Added Comments to the functions.

---
 modules-available/locationinfo/api.inc.php         | 79 ++++++++++++++++++++--
 .../locationinfo/inc/locationinfo.inc.php          |  6 ++
 modules-available/locationinfo/page.inc.php        | 65 +++++++++++++++++-
 .../locationinfo/templates/config.html             | 27 +++++++-
 .../locationinfo/templates/location-info.html      | 36 +++++++++-
 .../locationinfo/templates/server-settings.html    | 13 ++++
 .../locationinfo/templates/timetable.html          |  7 +-
 7 files changed, 224 insertions(+), 9 deletions(-)

(limited to 'modules-available')

diff --git a/modules-available/locationinfo/api.inc.php b/modules-available/locationinfo/api.inc.php
index 7ad83067..55f21e55 100644
--- a/modules-available/locationinfo/api.inc.php
+++ b/modules-available/locationinfo/api.inc.php
@@ -2,6 +2,9 @@
 
 HandleParameters();
 
+/**
+ * Handles the API paramenters.
+ */
 function HandleParameters()
 {
 
@@ -36,6 +39,12 @@ function HandleParameters()
 	}
 }
 
+/**
+ * Filters the id list. Removes Double / non-int / hidden rooms.
+ *
+ * @param $roomids Array of the room ids.
+ * @return array The filtered array of the room ids.
+ */
 function filterIdList($roomids)
 {
 	$idList = explode(',', $roomids);
@@ -46,6 +55,12 @@ function filterIdList($roomids)
 	return $filteredIdList;
 }
 
+/**
+ * Filters the hidden rooms from an array.
+ *
+ * @param $idArray Id list
+ * @return array Filtered id list
+ */
 function filterHiddenRoom($idArray)
 {
 	$filteredArray = array();
@@ -67,7 +82,13 @@ function filterHiddenRoom($idArray)
 }
 
 // ########## <Roominfo> ##########
-
+/**
+ * Gets the room info of the given rooms.
+ *
+ * @param $idList Array list of ids.
+ * @param bool $coords Defines if coords should be included or not.
+ * @return string Roominfo JSON
+ */
 function getRoomInfo($idList, $coords = false)
 {
 
@@ -125,7 +146,12 @@ function getRoomInfo($idList, $coords = false)
 // ########## </Roominfo> ###########
 
 // ########## <Openingtime> ##########
-
+/**
+ * Gets the Opening time of the given locations.
+ *
+ * @param $idList Array list of locations
+ * @return string Opening times JSON
+ */
 function getOpeningTime($idList)
 {
 	$dbresult = array();
@@ -172,7 +198,12 @@ function getOpeningTime($idList)
 	return json_encode($finalArray, true);
 }
 
-// Format the openingtime in the frontend needed format.
+/**
+ * Format the openingtime in the frontend needed format.
+ *
+ * @param $openingtime The opening time in the db saved format.
+ * @return mixed The opening time in the frontend needed format.
+ */
 function formatOpeningtime($openingtime)
 {
 	$weekarray = array("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday");
@@ -202,6 +233,12 @@ function formatOpeningtime($openingtime)
 	return $result;
 }
 
+/**
+ * Recursively gets the opening time from the parent location.
+ *
+ * @param $locationID Id of the location you want to get the parent opening time.
+ * @return array|mixed The opening time from the parent location.
+ */
 function getOpeningTimesFromParent($locationID)
 {
 	// Get parent location id.
@@ -223,6 +260,11 @@ function getOpeningTimesFromParent($locationID)
 	}
 }
 
+/**
+ * Creates the basic opening time where everything is closed.
+ *
+ * @return array Basic opening time.
+ */
 function createBasicClosingTime()
 {
 	$weekarray = array("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday");
@@ -241,7 +283,11 @@ function createBasicClosingTime()
 }
 
 // ########## </Openingtime> ##########
-
+/**
+ * Gets the config of the location.
+ *
+ * @param $locationID ID of the location
+ */
 function getConfig($locationID)
 {
 	$dbresult = Database::queryFirst("SELECT l.locationname, li.config, li.serverroomid, s.servertype, s.serverurl FROM `location_info` AS li
@@ -266,6 +312,12 @@ function getConfig($locationID)
 	}
 }
 
+/**
+ * Gets the pc states of the given locations.
+ *
+ * @param $idList Array list of the location ids.
+ * @return string PC state JSON
+ */
 function getPcStates($idList)
 {
 	$pcStates = array();
@@ -299,6 +351,12 @@ function getPcStates($idList)
 	return json_encode($pcStates);
 }
 
+/**
+ * Gets the room tree of the given locations.
+ *
+ * @param $idList Array list of the locations.
+ * @return string Room tree JSON.
+ */
 function getRoomTree($idList)
 {
 	$roomTree = array();
@@ -318,6 +376,13 @@ function getRoomTree($idList)
 	return json_encode($roomTree);
 }
 
+/**
+ * Recursively gets the Childs of a location.
+ *
+ * @param $id Location id you want all childs from.
+ * @param $filteredIdList Pointer to the filtered list to avoid double ids.
+ * @return array List with all the Childs.
+ */
 function getChildsRecursive($id, &$filteredIdList)
 {
 	$dbquery = Database::simpleQuery("SELECT locationid, locationname FROM `location` WHERE parentlocationid=:locationID", array('locationID' => $id));
@@ -344,6 +409,12 @@ function getChildsRecursive($id, &$filteredIdList)
 }
 
 // ########## <Calendar> ###########
+/**
+ * Gets the calendar of the given ids.
+ *
+ * @param $idList Array list with the location ids.
+ * @return string Calendar JSON.
+ */
 function getCalendar($idList)
 {
 	$serverList = array();
diff --git a/modules-available/locationinfo/inc/locationinfo.inc.php b/modules-available/locationinfo/inc/locationinfo.inc.php
index 02a7e2c1..4e2ea8aa 100644
--- a/modules-available/locationinfo/inc/locationinfo.inc.php
+++ b/modules-available/locationinfo/inc/locationinfo.inc.php
@@ -3,6 +3,12 @@
 class LocationInfo
 {
 
+	/**
+	 * Gets the pc data and returns it's state.
+	 *
+	 * @param $pc The pc data from the db. Array('logintime' =>, 'lastseen' =>, 'lastboot' =>)
+	 * @return int pc state
+	 */
 	public static function getPcState($pc)
 	{
 		/*   pcState:
diff --git a/modules-available/locationinfo/page.inc.php b/modules-available/locationinfo/page.inc.php
index 9b6df0b6..6490e722 100644
--- a/modules-available/locationinfo/page.inc.php
+++ b/modules-available/locationinfo/page.inc.php
@@ -62,6 +62,9 @@ class Page_LocationInfo extends Page
 
 	}
 
+	/**
+	 * Updates the server in the db.
+	 */
 	private function updateServer() {
 		$id = Request::post('id', 0, 'int');
 		if ($id == 0) {
@@ -76,11 +79,17 @@ class Page_LocationInfo extends Page
 		$this->checkConnection();
 	}
 
+	/**
+	 * Deletes the server from the db.
+	 */
 	private function deleteServer() {
 		$id = Request::post('id', 0, 'int');
 		Database::exec("DELETE FROM `setting_location_info` WHERE serverid=:id", array('id' => $id));
 	}
 
+	/**
+	 * Updated the config in the db.
+	 */
 	private function updateConfig()
 	{
 		$result = array();
@@ -113,6 +122,9 @@ class Page_LocationInfo extends Page
 		 Util::redirect('?do=locationinfo');
 	}
 
+	/**
+	 * Updates the server settings in the db.
+	 */
 	private function updateServerSettings() {
 		$serverid = Request::post('id', -1, 'int');
 		$servername = Request::post('name', 'unnamed', 'string');
@@ -143,6 +155,9 @@ class Page_LocationInfo extends Page
 		}
 	}
 
+	/**
+	 * Updates the opening time in the db from the expert mode.
+	 */
 	private function updateOpeningTimeExpert()
 	{
 		$days = Request::post('days');
@@ -227,6 +242,9 @@ class Page_LocationInfo extends Page
 		Util::redirect('?do=locationinfo');
 	}
 
+	/**
+	 * Updates the opening time in the db from the easy mode.
+	 */
 	private function updateOpeningTimeEasy() {
 		$locationid = Request::post('id', 0, 'int');
 		$openingtime = Request::post('openingtime');
@@ -255,6 +273,11 @@ class Page_LocationInfo extends Page
 		Util::redirect('?do=locationinfo');
 	}
 
+	/**
+	 * Checks if the server connection to a backend is valid.
+	 *
+	 * @param int $id Server id which connection should be checked.
+	 */
 	private function checkConnection($id = 0) {
 		$serverid = Request::post('id', 0, 'int');
 		if ($id != 0) {
@@ -281,6 +304,12 @@ class Page_LocationInfo extends Page
 		}
 	}
 
+	/**
+	 * Sets the new hidden value and checks childs and parents.
+	 *
+	 * @param $id The location id which was toggled
+	 * @param $val The hidden value true / false
+	 */
 	protected function toggleHidden($id, $val) {
 		Database::exec("INSERT INTO `location_info` (locationid, hidden) VALUES (:id, :hidden) ON DUPLICATE KEY UPDATE hidden=:hidden", array('id' => $id, 'hidden' => $val));
 
@@ -289,6 +318,12 @@ class Page_LocationInfo extends Page
 
 	}
 
+	/**
+	 * Recursivly sets all hidden values to all childs.
+	 *
+	 * @param $id The location id which childs should be checked
+	 * @param $val The hidden value
+	 */
 	protected function checkChildRecursive($id, $val) {
 		$dbquery = Database::simpleQuery("SELECT locationid FROM `location` WHERE parentlocationid = :locationid", array('locationid' => $id));
 		$childs = array();
@@ -303,6 +338,11 @@ class Page_LocationInfo extends Page
 		}
 	}
 
+	/**
+	 * Recursively check all parent locations and updates the hidden values if necessary
+	 *
+	 * @param $id The id of the location which was toggled.
+	 */
 	protected function checkParentRecursive($id) {
 		$dbquery = Database::simpleQuery("SELECT parentlocationid FROM `location` WHERE locationid = :locationid", array('locationid' => $id));
 		$parent = 0;
@@ -335,7 +375,9 @@ class Page_LocationInfo extends Page
 		}
 	}
 
-// Loads the Infoscreen pange in the admin-panel and passes all needed information.
+	/**
+	 * Loads the Infoscreen page in the admin-panel and passes all needed information.
+	 */
 	protected function getInfoScreenTable() {
 
 		// Get a table with the needed location info. name, id, hidden, pcState (Count of pcs that are in use), total pcs
@@ -444,6 +486,11 @@ class Page_LocationInfo extends Page
 		}
 	}
 
+	/**
+	 * Ajax the server settings.
+	 *
+	 * @param $id Serverid
+	 */
 	private function ajaxServerSettings($id) {
 		$dbresult = Database::queryFirst('SELECT servername, serverurl, servertype, credentials FROM `setting_location_info` WHERE serverid = :id', array('id' => $id));
 
@@ -514,6 +561,11 @@ class Page_LocationInfo extends Page
 		echo Render::parse('server-settings', array('id' => $id, 'name' => $dbresult['servername'], 'url' => $dbresult['serverurl'], 'servertype' => $dbresult['servertype'], 'backendList' => array_values($serverBackends)));
 	}
 
+	/**
+	 * Ajax the time table
+	 *
+	 * @param $id id of the location
+	 */
 	private function ajaxTimeTable($id) {
 		$array = array();
 		$dbquery = Database::simpleQuery("SELECT openingtime FROM `location_info` WHERE locationid = :id", array('id' => $id));
@@ -555,6 +607,12 @@ class Page_LocationInfo extends Page
 		}
 	}
 
+	/**
+	 * Checks if easymode or expert mode is active.
+	 *
+	 * @param $array Array of the saved openingtimes.
+	 * @return bool True if easy mode, false if expert mode
+	 */
 	private function isEasyMode($array) {
 		if(count($array[0]) == 3) {
 			if ($array[0][0]['days'] == array ("Monday","Tuesday","Wednesday","Thursday","Friday")
@@ -570,6 +628,11 @@ class Page_LocationInfo extends Page
 		}
 	}
 
+	/**
+	 * Ajax the config of a location.
+	 *
+	 * @param $id Location ID
+	 */
 	private function ajaxConfig($id) {
 		$array = array();
 
diff --git a/modules-available/locationinfo/templates/config.html b/modules-available/locationinfo/templates/config.html
index 1b42ff34..adce047b 100644
--- a/modules-available/locationinfo/templates/config.html
+++ b/modules-available/locationinfo/templates/config.html
@@ -279,7 +279,9 @@
 	initBootstrap();
 	loadValues();
 
-
+	/**
+	 * Initialize the bootstrap elements.
+	 */
 	function initBootstrap() {
 		// Init Bootstrap stuff.
 		$('#help-updateroom').tooltip();
@@ -298,6 +300,9 @@
 		$('#help-switchtime').tooltip();
 	}
 
+	/**
+	 * Loads the Values in the config form elements.
+	 */
 	function loadValues() {
 		$("#{{language}}").attr("selected", "selected");
 
@@ -394,14 +399,29 @@
 		modeChange(mode.val());
 	}
 
+	/**
+	 * Updates the value from the scale slider.
+	 *
+	 * @param newValue The new value the scale slider was set to.
+	 */
 	function showScaleValue(newValue) {
 		$("#scale").text(newValue + " %");
 	}
 
+	/**
+	 * Updates the value from the switchtime slider.
+	 *
+	 * @param newValue The new value the switchtime slider was set to.
+	 */
 	function showSwitchValue(newValue) {
 		$("#switch").text(newValue + " " + '{{lang_sec}}');
 	}
 
+	/**
+	 * If the mode was changed the mode settings have to be adjusted.
+	 *
+	 * @param value The new mode that was set. 1-4
+	 */
 	function modeChange(value) {
 		$('#item-vertical').hide();
 		$('#item-autoscale').hide();
@@ -429,6 +449,11 @@
 		}
 	}
 
+	/**
+	 * If the auto scale changes the days to show must be shown / hided
+	 *
+	 * @param value The new value of the autoscale switch.
+	 */
 	function autoScaleChange(value) {
 		autoscale = value;
 		if (value) {
diff --git a/modules-available/locationinfo/templates/location-info.html b/modules-available/locationinfo/templates/location-info.html
index 86d30260..f14faa23 100644
--- a/modules-available/locationinfo/templates/location-info.html
+++ b/modules-available/locationinfo/templates/location-info.html
@@ -123,6 +123,12 @@
 <script type="text/javascript">
 	var lastPcSubTable = false;
 
+	/**
+	 *	Sets the checkbox value and calls the php hide action.
+	 *
+	 * @param cb The checkbox which was clicked.
+	 * @param locID the locationID of the checkbox.
+	 */
 	function cbClick(cb, locID) {
 		var value;
 
@@ -134,6 +140,12 @@
 		window.location.href = "?do=locationinfo&action=hide&id=" + locID + "&value=" + value;
 	}
 
+	/**
+	 * Loads the settings modal of a server.
+	 *
+	 * @param serverid The id of the server.
+	 * @param servername The name of the server.
+	 */
 	function loadSettingsModal(serverid, servername) {
 		$('#myModalHeader').text("{{lang_locationSettings}}").css("font-weight", "Bold");
 
@@ -141,6 +153,12 @@
 		$('#myModalBody').load("?do=locationinfo&action=serverSettings&id=" + serverid);
 	}
 
+	/**
+	 * Load a opening time modal of a location.
+	 *
+	 * @param locationId The id of the location.
+	 * @param locationName The name of the location.
+	 */
 	function loadTimeModal(locationId, locationName) {
 		$('#myModalHeader').text("[" + locationId + "] " + locationName).css("font-weight", "Bold");
 
@@ -149,9 +167,10 @@
 	}
 
 	/**
+	 * Loads the config modal of a location.
 	 *
-	 * @param locationId
-	 * @param locationName
+	 * @param locationId The id of the location
+	 * @param locationName the name of the location
 	 */
 	function loadConfigModal(locationId, locationName) {
 		$('#myModalHeader').text("[" + locationId + "] " + locationName).css("font-weight", "Bold");
@@ -167,6 +186,11 @@
 	var preEditPassword;
 	var preEditType;
 
+	/**
+	 * Deletes a server.
+	 *
+	 * @param id The serverid
+	 */
 	function deleteButtonClick(id) {
 		var del = confirm("{{lang_deleteConfirmation}}");
 		if (del == true) {
@@ -175,12 +199,20 @@
 		}
 	}
 
+	/**
+	 * Calls the checkConnection php function to check a server connection.
+	 *
+	 * @param id The id of the server.
+	 */
 	function refreshButtonClick(id) {
 		$('#refresh-btn-animate-' + id).addClass('glyphicon-refresh-animate');
 		$('#serverFormAction-' + id).val("checkConnection");
 		$('#submit-serverForm-' + id).trigger("click");
 	}
 
+	/**
+	 * Loads a new / empty server settings modal.
+	 */
 	function addServer() {
 		loadSettingsModal(0, '');
 	}
diff --git a/modules-available/locationinfo/templates/server-settings.html b/modules-available/locationinfo/templates/server-settings.html
index f885c0c1..641873ef 100644
--- a/modules-available/locationinfo/templates/server-settings.html
+++ b/modules-available/locationinfo/templates/server-settings.html
@@ -82,12 +82,20 @@
 	loadCredentials();
 	initalizeBootstrap();
 
+	/**
+	 * Initialize the bootstrap elements.
+	 */
 	function initalizeBootstrap() {
 		$('#help-name').tooltip();
 		$('#help-url').tooltip();
 		$('#help-type').tooltip();
 	}
 
+	/**
+	 * Loads the dynamic credentials forms.
+	 *
+	 * @param {bool} useValue If false the form elements will be empty. Default = true.
+	 */
 	function loadCredentials(useValue = true) {
 		// {{name}} name of auth {{type}} type of auth (string, int etc.) {{value}} value from the db
 		{{#backendList}}
@@ -145,6 +153,11 @@
 
 	}
 
+	/**
+	 * After the servertype switch changed, the new credentials needs to be loaded.
+	 *
+	 * @param {string} value The new type of the server which credentials needs to be loaded.
+	 */
 	function servertype_changed(value) {
 		type = value;
 		$('#credentials-div').fadeOut('fast', function() {
diff --git a/modules-available/locationinfo/templates/timetable.html b/modules-available/locationinfo/templates/timetable.html
index 78d13e29..7143facd 100644
--- a/modules-available/locationinfo/templates/timetable.html
+++ b/modules-available/locationinfo/templates/timetable.html
@@ -146,6 +146,9 @@
 		}
 	});
 
+	/**
+	 * Sets the timepicker element.
+	 */
 	function setTimepicker() {
 		$('.timepicker2').timepicker({
 			minuteStep: 1,
@@ -157,6 +160,9 @@
 		});
 	}
 
+	/**
+	 * Adds a new opening time to the table in expert mode.
+	 */
 	function newOpeningTime() {
 		$('#lastOpenTimesTableElement').before('<tr>\
       <td>\
@@ -172,7 +178,6 @@
         <input type="hidden" name="days[]" value="-">\
         </td>\
         <td>\
-        \
         <div class="input-group bootstrap-timepicker">\
         		<span class="input-group-addon">\
         			<span class="glyphicon glyphicon-time"></span>\
-- 
cgit v1.2.3-55-g7522