From 9fa510d2a8e7c0204f3ac7c0b1d2abacb55b0ef7 Mon Sep 17 00:00:00 2001 From: Molkobain Date: Wed, 27 Nov 2019 20:40:39 +0100 Subject: [PATCH] Internal: PHPDoc and warning suppression --- application/cmdbabstract.class.inc.php | 201 +++++++++++++++- application/datatable.class.inc.php | 307 ++++++++++++++++++++---- application/webpage.class.inc.php | 312 +++++++++++++++++++++---- 3 files changed, 728 insertions(+), 92 deletions(-) diff --git a/application/cmdbabstract.class.inc.php b/application/cmdbabstract.class.inc.php index dcebc6f7b..133a39baa 100644 --- a/application/cmdbabstract.class.inc.php +++ b/application/cmdbabstract.class.inc.php @@ -63,6 +63,8 @@ abstract class cmdbAbstractObject extends CMDBObject implements iDisplay * @param string $sClassAlias * @param array $aAttToLoad * @param array $aExtendedDataSpec + * + * @throws \CoreException */ public function __construct($aRow = null, $sClassAlias = '', $aAttToLoad = null, $aExtendedDataSpec = null) { @@ -83,6 +85,13 @@ abstract class cmdbAbstractObject extends CMDBObject implements iDisplay return 'UI.php'; } + /** + * @param \WebPage $oPage + * @param \DBObject $oObj + * @param array $aParams + * + * @throws \Exception + */ public static function ReloadAndDisplay($oPage, $oObj, $aParams) { $oAppContext = new ApplicationContext(); @@ -135,7 +144,7 @@ EOF } /** - * Set a message diplayed to the end-user next time this object will be displayed + * Set a message displayed to the end-user next time this object will be displayed * Messages are uniquely identified so that plugins can override standard messages (the final work is given to the * last plugin to set the message for a given message id) In practice, standard messages are recorded at the end * but they will not overwrite existing messages @@ -168,6 +177,17 @@ EOF } } + /** + * @param \WebPage $oPage + * @param bool $bEditMode + * + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MySQLException + * @throws \OQLException + */ public function DisplayBareHeader(WebPage $oPage, $bEditMode = false) { // Standard Header with name, actions menu and history block @@ -359,6 +379,16 @@ EOF ); } + /** + * Display history tab of an object + * + * @param \WebPage $oPage + * @param bool $bEditMode + * @param int $iLimitCount + * @param int $iLimitStart + * + * @throws \CoreException + */ public function DisplayBareHistory(WebPage $oPage, $bEditMode = false, $iLimitCount = 0, $iLimitStart = 0) { // history block (with as a tab) @@ -370,6 +400,17 @@ EOF $oBlock->Display($oPage, 'history'); } + /** + * Display properties tab of an object + * + * @param \WebPage $oPage + * @param bool $bEditMode + * @param string $sPrefix + * @param array $aExtraParams + * + * @return array + * @throws \CoreException + */ public function DisplayBareProperties(WebPage $oPage, $bEditMode = false, $sPrefix = '', $aExtraParams = array()) { $aFieldsMap = $this->GetBareProperties($oPage, $bEditMode, $sPrefix, $aExtraParams); @@ -452,6 +493,7 @@ EOF * @throws \MySQLException * @throws \MySQLHasGoneAwayException * @throws \OQLException + * @throws \Exception */ public function DisplayBareRelations(WebPage $oPage, $bEditMode = false) { @@ -690,6 +732,21 @@ EOF } } + /** + * @param \WebPage $oPage + * @param bool $bEditMode + * @param string $sPrefix + * @param array $aExtraParams + * + * @return array + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MySQLException + * @throws \OQLException + * @throws \Exception + */ public function GetBareProperties(WebPage $oPage, $bEditMode, $sPrefix, $aExtraParams = array()) { $sStateAttCode = MetaModel::GetStateAttributeCode(get_class($this)); @@ -951,6 +1008,13 @@ EOF } } + /** + * @param \WebPage $oPage + * + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \DictExceptionMissingString + */ public function DisplayPreview(WebPage $oPage) { $aDetails = array(); @@ -966,6 +1030,14 @@ EOF $oPage->details($aDetails); } + /** + * @param \WebPage $oPage + * @param \CMDBObjectSet $oSet + * @param array $aExtraParams + * + * @throws \ApplicationException + * @throws \CoreException + */ public static function DisplaySet(WebPage $oPage, CMDBObjectSet $oSet, $aExtraParams = array()) { $oPage->add(self::GetDisplaySet($oPage, $oSet, $aExtraParams)); @@ -1008,16 +1080,18 @@ EOF /** * Get the HTML fragment corresponding to the display of a table representing a set of objects * - * @param WebPage $oPage The page object is used for out-of-band information (mostly scripts) output + * @see DisplayBlock to get a similar table but with the JS for pagination & sorting + * * @param CMDBObjectSet The set of objects to display * @param array $aExtraParams Some extra configuration parameters to tweak the behavior of the display * + * @param WebPage $oPage The page object is used for out-of-band information (mostly scripts) output + * * @return String The HTML fragment representing the table of objects. Warning : no JS added to handled * pagination or table sorting ! * + * @throws \CoreException*@throws \Exception * @throws \ApplicationException - * @throws \CoreException - * @see DisplayBlock to get a similar table but with the JS for pagination & sorting */ public static function GetDisplaySet(WebPage $oPage, CMDBObjectSet $oSet, $aExtraParams = array()) { @@ -1165,6 +1239,18 @@ EOF return $oDataTable->Display($oPage, $oSettings, $bDisplayMenu, $sSelectMode, $bViewLink, $aExtraParams); } + /** + * @param \WebPage $oPage + * @param \CMDBObjectSet $oSet + * @param array $aExtraParams + * + * @return string + * @throws \CoreException + * @throws \DictExceptionMissingString + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public static function GetDisplayExtendedSet(WebPage $oPage, CMDBObjectSet $oSet, $aExtraParams = array()) { if (empty($aExtraParams['currentId'])) @@ -1265,11 +1351,36 @@ EOF return $oDataTable->Display($oPage, $oSettings, $bDisplayMenu, $sSelectMode, $bViewLink, $aExtraParams); } + /** + * @param \WebPage $oPage + * @param \CMDBObjectSet $oSet + * @param array $aParams + * @param string $sCharset + * + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public static function DisplaySetAsCSV(WebPage $oPage, CMDBObjectSet $oSet, $aParams = array(), $sCharset = 'UTF-8') { $oPage->add(self::GetSetAsCSV($oSet, $aParams, $sCharset)); } + /** + * @param \DBObjectSet $oSet + * @param array $aParams + * @param string $sCharset + * + * @return string + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + * @throws \Exception + */ public static function GetSetAsCSV(DBObjectSet $oSet, $aParams = array(), $sCharset = 'UTF-8') { $sSeparator = isset($aParams['separator']) ? $aParams['separator'] : ','; // default separator is comma @@ -1399,6 +1510,13 @@ EOF return $sHtml; } + /** + * @param \WebPage $oPage + * @param \CMDBObjectSet $oSet + * @param array $aParams + * + * @throws \Exception + */ public static function DisplaySetAsHTMLSpreadsheet(WebPage $oPage, CMDBObjectSet $oSet, $aParams = array()) { $oPage->add(self::GetSetAsHTMLSpreadsheet($oSet, $aParams)); @@ -1407,6 +1525,17 @@ EOF /** * Spreadsheet output: designed for end users doing some reporting * Then the ids are excluded and replaced by the corresponding friendlyname + * + * @param \DBObjectSet $oSet + * @param array $aParams + * + * @return string + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + * @throws \Exception */ public static function GetSetAsHTMLSpreadsheet(DBObjectSet $oSet, $aParams = array()) { @@ -1592,6 +1721,17 @@ EOF return $sHtml; } + /** + * @param \WebPage $oPage + * @param \CMDBObjectSet $oSet + * @param array $aParams + * + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public static function DisplaySetAsXML(WebPage $oPage, CMDBObjectSet $oSet, $aParams = array()) { $bLocalize = true; @@ -1659,6 +1799,14 @@ EOF $oPage->add("\n"); } + /** + * @param \WebPage $oPage + * @param \CMDBObjectSet $oSet + * @param array $aExtraParams + * + * @throws \CoreException + * @throws \DictExceptionMissingString + */ public static function DisplaySearchForm(WebPage $oPage, CMDBObjectSet $oSet, $aExtraParams = array()) { @@ -2607,6 +2755,20 @@ EOF return $oObj->DisplayModifyForm($oPage, $aExtraParams); } + /** + * @param \WebPage $oPage + * @param string $sStimulus + * @param null $aPrefillFormParam + * + * @throws \ApplicationException + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public function DisplayStimulusForm(WebPage $oPage, $sStimulus, $aPrefillFormParam = null) { $sClass = get_class($this); @@ -3913,6 +4075,20 @@ EOF /** * Special display where the case log uses the whole "screen" at the bottom of the "Properties" tab + * + * @param \WebPage $oPage + * @param string $sAttCode + * @param string $sComment + * @param string $sPrefix + * @param bool $bEditMode + * + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MySQLException + * @throws \OQLException + * @throws \Exception */ public function DisplayCaseLog(WebPage $oPage, $sAttCode, $sComment = '', $sPrefix = '', $bEditMode = false) { @@ -4302,6 +4478,20 @@ EOF /** * Process the reply made from a form built with DisplayBulkModifyForm + * + * @param \WebPage $oP + * @param string $sClass + * @param array $aSelectedObj + * @param string $sCustomOperation + * @param bool $bPreview + * @param string $sCancelUrl + * @param array $aContextData + * + * @throws \ArchivedObjectException + * @throws \CoreCannotSaveObjectException + * @throws \CoreException + * @throws \DictExceptionMissingString + * @throws \OQLException */ public static function DoBulkModify($oP, $sClass, $aSelectedObj, $sCustomOperation, $bPreview, $sCancelUrl, $aContextData = array()) { @@ -4433,6 +4623,7 @@ EOF * * @throws \CoreException * @throws \DictExceptionMissingString + * @throws \Exception */ public static function DeleteObjects(WebPage $oP, $sClass, $aObjects, $bPreview, $sCustomOperation, $aContextData = array()) { @@ -4728,6 +4919,8 @@ EOF /** * Find redundancy settings that can be viewed and modified in a tab * Settings are distributed to the corresponding link set attribute so as to be shown in the relevant tab + * + * @throws \Exception */ protected function FindVisibleRedundancySettings() { diff --git a/application/datatable.class.inc.php b/application/datatable.class.inc.php index 00d97d9ee..d687de538 100644 --- a/application/datatable.class.inc.php +++ b/application/datatable.class.inc.php @@ -1,25 +1,20 @@ /** - * Data Table to display a set of objects in a tabular manner in HTML + * Copyright (C) 2013-2019 Combodo SARL * - * @copyright Copyright (C) 2010-2017 Combodo SARL - * @license http://opensource.org/licenses/AGPL-3.0 + * This file is part of iTop. + * + * iTop is free software; you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * iTop is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License */ class DataTable @@ -36,8 +31,13 @@ class DataTable /** * @param $iListId mixed Unique ID for this div/table in the page * @param $oSet DBObjectSet The set of data to display - * @param $aClassAliases Hash The list of classes/aliases to be displayed in this set $sAlias => $sClassName + * @param $aClassAliases array The list of classes/aliases to be displayed in this set $sAlias => $sClassName * @param $sTableId mixed A string (or null) identifying this table in order to persist its settings + * + * @throws \CoreException + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException */ public function __construct($iListId, $oSet, $aClassAliases, $sTableId = null) { @@ -50,7 +50,19 @@ class DataTable $this->oDefaultSettings = null; $this->bShowObsoleteData = $oSet->GetShowObsoleteData(); } - + + /** + * @param \WebPage $oPage + * @param \DataTableSettings $oSettings + * @param $bActionsMenu + * @param $sSelectMode + * @param $bViewLink + * @param $aExtraParams + * + * @return string + * @throws \CoreException + * @throws \MySQLException + */ public function Display(WebPage $oPage, DataTableSettings $oSettings, $bActionsMenu, $sSelectMode, $bViewLink, $aExtraParams) { $this->oDefaultSettings = $oSettings; @@ -119,7 +131,23 @@ class DataTable return $this->GetAsHTML($oPage, $oCustomSettings->iDefaultPageSize, $oCustomSettings->iDefaultPageSize, 0, $oCustomSettings->aColumns, $bActionsMenu, $bToolkitMenu, $sSelectMode, $bViewLink, $aExtraParams); } - + + /** + * @param \WebPage $oPage + * @param $iPageSize + * @param $iDefaultPageSize + * @param $iPageIndex + * @param $aColumns + * @param $bActionsMenu + * @param $bToolkitMenu + * @param $sSelectMode + * @param $bViewLink + * @param $aExtraParams + * + * @return string + * @throws \ArchivedObjectException + * @throws \CoreException + */ public function GetAsHTML(WebPage $oPage, $iPageSize, $iDefaultPageSize, $iPageIndex, $aColumns, $bActionsMenu, $bToolkitMenu, $sSelectMode, $bViewLink, $aExtraParams) { $sObjectsCount = $this->GetObjectCount($oPage, $sSelectMode); @@ -198,7 +226,13 @@ class DataTable } return $sHtml; } - + + /** + * @param \WebPage $oPage + * @param $sSelectMode + * + * @return string + */ protected function GetObjectCount(WebPage $oPage, $sSelectMode) { if (($sSelectMode == 'single') || ($sSelectMode == 'multiple')) @@ -211,6 +245,15 @@ class DataTable } return $sHtml; } + + /** + * @param \WebPage $oPage + * @param $iPageSize + * @param $iDefaultPageSize + * @param $iPageIndex + * + * @return string + */ protected function GetPager(WebPage $oPage, $iPageSize, $iDefaultPageSize, $iPageIndex) { $sHtml = ''; @@ -295,7 +338,17 @@ class DataTable EOF; return $sHtml; } - + + /** + * @param \WebPage $oPage + * @param $aExtraParams + * + * @return string + * @throws \CoreException + * @throws \DictExceptionMissingString + * @throws \MissingQueryArgument + * @throws \MySQLException + */ protected function GetActionsMenu(WebPage $oPage, $aExtraParams) { $oMenuBlock = new MenuBlock($this->oSet->GetFilter(), 'list'); @@ -303,7 +356,14 @@ EOF; $sHtml = $oMenuBlock->GetRenderContent($oPage, $aExtraParams, $this->iListId); return $sHtml; } - + + /** + * @param \WebPage $oPage + * @param $aExtraParams + * + * @return string + * @throws \Exception + */ protected function GetToolkitMenu(WebPage $oPage, $aExtraParams) { if (!$oPage->IsPrintableVersion()) @@ -326,7 +386,15 @@ EOF; } return $sHtml; } - + + /** + * @param \WebPage $oPage + * @param $aColumns + * @param $bViewLink + * @param $iDefaultPageSize + * + * @return string + */ protected function GetTableConfigDlg(WebPage $oPage, $aColumns, $bViewLink, $iDefaultPageSize) { $sHtml = "
iListId}\" style=\"display: none;\">"; @@ -362,13 +430,27 @@ EOF; return $sHtml; } - + + /** + * @param $oSetting + * + * @return array + */ public function GetAsHash($oSetting) { $aSettings = array('iDefaultPageSize' => $oSetting->iDefaultPageSize, 'oColumns' => $oSetting->aColumns); return $aSettings; } - + + /** + * @param $aColumns + * @param $sSelectMode + * @param $bViewLink + * + * @return array + * @throws \CoreException + * @throws \DictExceptionMissingString + */ protected function GetHTMLTableConfig($aColumns, $sSelectMode, $bViewLink) { $aAttribs = array(); @@ -401,7 +483,21 @@ EOF; } return $aAttribs; } - + + /** + * @param $aColumns + * @param $sSelectMode + * @param $iPageSize + * @param $bViewLink + * @param $aExtraParams + * + * @return array + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ protected function GetHTMLTableValues($aColumns, $sSelectMode, $iPageSize, $bViewLink, $aExtraParams) { $bLocalize = true; @@ -484,7 +580,24 @@ EOF; } return $aValues; } - + + /** + * @param \WebPage $oPage + * @param $aColumns + * @param $sSelectMode + * @param $iPageSize + * @param $bViewLink + * @param $aExtraParams + * + * @return string + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public function GetHTMLTable(WebPage $oPage, $aColumns, $sSelectMode, $iPageSize, $bViewLink, $aExtraParams) { $iNbPages = ($iPageSize < 1) ? 1 : ceil($this->iNbObjects / $iPageSize); @@ -585,7 +698,12 @@ EOF } return $sHtml; } - + + /** + * @param \WebPage $oPage + * @param $iDefaultPageSize + * @param $iStart + */ public function UpdatePager(WebPage $oPage, $iDefaultPageSize, $iStart) { $iPageSize = $iDefaultPageSize; @@ -609,11 +727,48 @@ EOF */ class PrintableDataTable extends DataTable { + /** + * @param \WebPage $oPage + * @param $iPageSize + * @param $iDefaultPageSize + * @param $iPageIndex + * @param $aColumns + * @param $bActionsMenu + * @param $bToolkitMenu + * @param $sSelectMode + * @param $bViewLink + * @param $aExtraParams + * + * @return string + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public function GetAsHTML(WebPage $oPage, $iPageSize, $iDefaultPageSize, $iPageIndex, $aColumns, $bActionsMenu, $bToolkitMenu, $sSelectMode, $bViewLink, $aExtraParams) { return $this->GetHTMLTable($oPage, $aColumns, $sSelectMode, -1, $bViewLink, $aExtraParams); } - + + /** + * @param \WebPage $oPage + * @param $aColumns + * @param $sSelectMode + * @param $iPageSize + * @param $bViewLink + * @param $aExtraParams + * + * @return string + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \DictExceptionMissingString + * @throws \MissingQueryArgument + * @throws \MySQLException + * @throws \MySQLHasGoneAwayException + */ public function GetHTMLTable(WebPage $oPage, $aColumns, $sSelectMode, $iPageSize, $bViewLink, $aExtraParams) { $iNbPages = ($iPageSize < 1) ? 1 : ceil($this->iNbObjects / $iPageSize); @@ -638,7 +793,13 @@ class DataTableSettings implements Serializable public $iDefaultPageSize; public $aColumns; - + + /** + * DataTableSettings constructor. + * + * @param $aClassAliases + * @param null $sTableId + */ public function __construct($aClassAliases, $sTableId = null) { $this->aClassAliases = $aClassAliases; @@ -646,14 +807,22 @@ class DataTableSettings implements Serializable $this->iDefaultPageSize = 10; $this->aColumns = array(); } - + + /** + * @param $iDefaultPageSize + * @param $aSortOrder + * @param $aColumns + */ protected function Init($iDefaultPageSize, $aSortOrder, $aColumns) { $this->iDefaultPageSize = $iDefaultPageSize; $this->aColumns = $aColumns; $this->FixVisibleColumns(); } - + + /** + * @return string + */ public function serialize() { // Save only the 'visible' columns @@ -679,7 +848,12 @@ class DataTableSettings implements Serializable ) ); } - + + /** + * @param string $sData + * + * @throws \Exception + */ public function unserialize($sData) { $aData = unserialize($sData); @@ -712,7 +886,16 @@ class DataTableSettings implements Serializable } $this->FixVisibleColumns(); } - + + /** + * @param $aClassAliases + * @param $bViewLink + * @param $aDefaultLists + * + * @return \DataTableSettings + * @throws \CoreException + * @throws \DictExceptionMissingString + */ static public function GetDataModelSettings($aClassAliases, $bViewLink, $aDefaultLists) { $oSettings = new DataTableSettings($aClassAliases); @@ -762,7 +945,10 @@ class DataTableSettings implements Serializable $oSettings->Init($iDefaultPageSize, $aSortOrder, $aColumns); return $oSettings; } - + + /** + * @throws \CoreException + */ protected function FixVisibleColumns() { foreach($this->aClassAliases as $sAlias => $sClass) @@ -799,7 +985,15 @@ class DataTableSettings implements Serializable } } } - + + /** + * @param $aClassAliases + * @param null $sTableId + * @param bool $bOnlyOnTable + * + * @return \DataTableSettings|null + * @throws \Exception + */ static public function GetTableSettings($aClassAliases, $sTableId = null, $bOnlyOnTable = false) { $pref = null; @@ -828,7 +1022,10 @@ class DataTableSettings implements Serializable return $oSettings; } - + + /** + * @return array + */ public function GetSortOrder() { $aSortOrder = array(); @@ -846,7 +1043,12 @@ class DataTableSettings implements Serializable } return $aSortOrder; } - + + /** + * @param null $sTargetTableId + * + * @return bool + */ public function Save($sTargetTableId = null) { $sSaveId = is_null($sTargetTableId) ? $this->sTableId : $sTargetTableId; @@ -857,6 +1059,9 @@ class DataTableSettings implements Serializable return true; } + /** + * @return bool + */ public function SaveAsDefault() { $sSettings = $this->serialize(); @@ -886,7 +1091,12 @@ class DataTableSettings implements Serializable } return true; } - + + /** + * @param null $sTableId + * + * @return string + */ protected function GetPrefsKey($sTableId = null) { if ($sTableId == null) $sTableId = '*'; @@ -897,7 +1107,18 @@ class DataTableSettings implements Serializable } return implode('/', $aKeys).'|'.$sTableId; } - + + /** + * @param $sAlias + * @param $sAttCode + * @param $oAttDef + * @param $bChecked + * @param $sSort + * + * @return array|bool + * @throws \CoreException + * @throws \DictExceptionMissingString + */ protected function GetFieldData($sAlias, $sAttCode, $oAttDef, $bChecked, $sSort) { $ret = false; diff --git a/application/webpage.class.inc.php b/application/webpage.class.inc.php index 4f02cc4bd..cf227f59b 100644 --- a/application/webpage.class.inc.php +++ b/application/webpage.class.inc.php @@ -1,45 +1,80 @@ - - /** - * Class WebPage + * Copyright (C) 2013-2019 Combodo SARL * - * @copyright Copyright (C) 2010-2015 Combodo SARL - * @license http://opensource.org/licenses/AGPL-3.0 + * This file is part of iTop. + * + * iTop is free software; you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * iTop is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License */ - /** * Generic interface common to CLI and Web pages */ Interface Page { + /** + * Outputs (via some echo) the complete HTML page by assembling all its elements + * + * @return mixed + */ public function output(); + /** + * Add any text or HTML fragment to the body of the page + * + * @param string $sText + * + * @return mixed + */ public function add($sText); + /** + * Add a paragraph to the body of the page + * + * @param string $sText + * + * @return mixed + */ public function p($sText); + /** + * Add a pre-formatted text to the body of the page + * + * @param string $sText + * + * @return mixed + */ public function pre($sText); + /** + * Add a comment + * + * @param string $sText + * + * @return mixed + */ public function add_comment($sText); + /** + * Adds a tabular content to the web page + * + * @param string[] $aConfig Configuration of the table: hash array of 'column_id' => 'Column Label' + * @param string[] $aData Hash array. Data to display in the table: each row is made of 'column_id' => Data. A + * column 'pkey' is expected for each row + * @param array $aParams Hash array. Extra parameters for the table. + * + * @return void + */ public function table($aConfig, $aData, $aParams = array()); } @@ -86,7 +121,12 @@ class WebPage implements Page protected $bPrintable; protected $bHasCollapsibleSection; - + /** + * WebPage constructor. + * + * @param string $s_title + * @param bool $bPrintable + */ public function __construct($s_title, $bPrintable = false) { $this->s_title = $s_title; @@ -115,6 +155,8 @@ class WebPage implements Page /** * Change the title of the page after its creation + * + * @param string $s_title */ public function set_title($s_title) { @@ -123,6 +165,9 @@ class WebPage implements Page /** * Specify a default URL and a default target for all links on a page + * + * @param string $s_href + * @param string $s_target */ public function set_base($s_href = '', $s_target = '') { @@ -131,7 +176,7 @@ class WebPage implements Page } /** - * Add any text or HTML fragment to the body of the page + * @inheritDoc */ public function add($s_html) { @@ -142,6 +187,9 @@ class WebPage implements Page * Add any text or HTML fragment (identified by an ID) at the end of the body of the page * This is useful to add hidden content, DIVs or FORMs that should not * be embedded into each other. + * + * @param string $s_html + * @param string $sId */ public function add_at_the_end($s_html, $sId = '') { @@ -149,7 +197,7 @@ class WebPage implements Page } /** - * Add a paragraph to the body of the page + * @inheritDoc */ public function p($s_html) { @@ -157,7 +205,7 @@ class WebPage implements Page } /** - * Add a pre-formatted text to the body of the page + * @inheritDoc */ public function pre($s_html) { @@ -165,7 +213,7 @@ class WebPage implements Page } /** - * Add a comment + * @inheritDoc */ public function add_comment($sText) { @@ -174,6 +222,10 @@ class WebPage implements Page /** * Add a paragraph to the body of the page + * + * @param string $s_html + * + * @return string */ public function GetP($s_html) { @@ -181,20 +233,22 @@ class WebPage implements Page } /** - * Adds a tabular content to the web page - * - * @param string[] $aConfig Configuration of the table: hash array of 'column_id' => 'Column Label' - * @param string[] $aData Hash array. Data to display in the table: each row is made of 'column_id' => Data. A - * column 'pkey' is expected for each row - * @param array $aParams Hash array. Extra parameters for the table. - * - * @return void + * @inheritDoc + * @throws \Exception */ public function table($aConfig, $aData, $aParams = array()) { $this->add($this->GetTable($aConfig, $aData, $aParams)); } + /** + * @param array $aConfig + * @param array $aData + * @param array $aParams + * + * @return string + * @throws \Exception + */ public function GetTable($aConfig, $aData, $aParams = array()) { $oAppContext = new ApplicationContext(); @@ -222,6 +276,12 @@ class WebPage implements Page return $sHtml; } + /** + * @param array $aRow + * @param array $aConfig + * + * @return string + */ public function GetTableRow($aRow, $aConfig) { $sHtml = ''; @@ -246,6 +306,8 @@ class WebPage implements Page /** * Add some Javascript to the header of the page + * + * @param string $s_script */ public function add_script($s_script) { @@ -254,6 +316,8 @@ class WebPage implements Page /** * Add some Javascript to the header of the page + * + * @param $s_script */ public function add_ready_script($s_script) { @@ -286,12 +350,18 @@ class WebPage implements Page $this->a_dict_entries_prefixes[] = $s_entriesPrefix; } + /** + * @return string + */ protected function get_dict_signature() { return str_replace('_', '', Dict::GetUserLanguage()).'-'.md5(implode(',', $this->a_dict_entries).'|'.implode(',', $this->a_dict_entries_prefixes)); } + /** + * @return string + */ protected function get_dict_file_content() { $aEntries = array(); @@ -311,6 +381,8 @@ class WebPage implements Page /** * Add some CSS definitions to the header of the page + * + * @param string $s_style */ public function add_style($s_style) { @@ -330,12 +402,20 @@ class WebPage implements Page /** * Add a CSS stylesheet (as an include, i.e. link) to the header of the page + * + * @param string $s_linked_stylesheet + * @param string $s_condition */ public function add_linked_stylesheet($s_linked_stylesheet, $s_condition = "") { $this->a_linked_stylesheets[] = array('link' => $s_linked_stylesheet, 'condition' => $s_condition); } + /** + * @param string $sSaasRelPath + * + * @throws \Exception + */ public function add_saas($sSaasRelPath) { $sCssRelPath = utils::GetCSSFromSASS($sSaasRelPath); @@ -351,6 +431,8 @@ class WebPage implements Page /** * Add some custom header to the page + * + * @param string $s_header */ public function add_header($s_header) { @@ -368,6 +450,8 @@ class WebPage implements Page /** * Build a special kind of TABLE useful for displaying the details of an object from a hash array of data + * + * @param array $aFields */ public function details($aFields) { @@ -413,6 +497,10 @@ class WebPage implements Page /** * Build a special kind of TABLE useful for displaying the details of an object from a hash array of data + * + * @param array $aFields + * + * @return string */ public function GetDetails($aFields) { @@ -457,7 +545,7 @@ class WebPage implements Page /** * Build a set of radio buttons suitable for editing a field/attribute of an object (including its validation) * - * @param $aAllowedValues hash Array of value => display_value + * @param $aAllowedValues array Array of value => display_value * @param $value mixed Current value for the field/attribute * @param $iId mixed Unique Id for the input control in the page * @param $sFieldName string The name of the field, attr_<$sFieldName> will hold the value for the field @@ -477,13 +565,13 @@ class WebPage implements Page if ((count($aAllowedValues) == 1) && ($bMandatory == 'true')) { // When there is only once choice, select it by default - $sSelected = ' checked'; + $sSelected = 'checked'; } else { - $sSelected = ($value == $key) ? ' checked' : ''; + $sSelected = ($value == $key) ? 'checked' : ''; } - $sHTMLValue .= " "; + $sHTMLValue .= " "; if ($bVertical) { if ($idx == 0) @@ -522,6 +610,8 @@ class WebPage implements Page * Possible improvement: I've noticed that several output buffers are stacked, * if they are not empty, the output will be corrupted. The solution would * consist in unstacking all of them (and concatenate the contents). + * + * @throws \Exception */ protected function ob_get_clean_safe() { @@ -559,7 +649,8 @@ class WebPage implements Page } /** - * Outputs (via some echo) the complete HTML page by assembling all its elements + * @inheritDoc + * @throws \Exception */ public function output() { @@ -659,6 +750,9 @@ class WebPage implements Page /** * Build a series of hidden field[s] from an array + * + * @param string $sLabel + * @param array $aData */ public function add_input_hidden($sLabel, $aData) { @@ -837,6 +931,12 @@ class WebPage implements Page } } + /** + * @param array $aActions + * @param array $aFavoriteActions + * + * @return string + */ public function RenderPopupMenuItems($aActions, $aFavoriteActions = array()) { $sPrevUrl = ''; @@ -845,10 +945,10 @@ class WebPage implements Page { foreach ($aActions as $aAction) { - $sClass = isset($aAction['css_classes']) ? ' class="'.implode(' ', $aAction['css_classes']).'"' : ''; - $sOnClick = isset($aAction['onclick']) ? ' onclick="'.htmlspecialchars($aAction['onclick'], ENT_QUOTES, + $sClass = isset($aAction['css_classes']) ? 'class="'.implode(' ', $aAction['css_classes']).'"' : ''; + $sOnClick = isset($aAction['onclick']) ? 'onclick="'.htmlspecialchars($aAction['onclick'], ENT_QUOTES, "UTF-8").'"' : ''; - $sTarget = isset($aAction['target']) ? " target=\"{$aAction['target']}\"" : ""; + $sTarget = isset($aAction['target']) ? "target=\"{$aAction['target']}\"" : ""; if (empty($aAction['url'])) { if ($sPrevUrl != '') // Don't output consecutively two separators... @@ -859,7 +959,7 @@ class WebPage implements Page } else { - $sHtml .= "
  • {$aAction['label']}
    • "; + $sHtml .= "
  • {$aAction['label']}
    • "; $sPrevUrl = $aAction['url']; } } @@ -874,6 +974,11 @@ class WebPage implements Page return $sHtml; } + /** + * @param bool $bReturnOutput + * + * @throws \Exception + */ protected function output_dict_entries($bReturnOutput = false) { if ((count($this->a_dict_entries) > 0) || (count($this->a_dict_entries_prefixes) > 0)) @@ -927,11 +1032,27 @@ $("#LnkCollapse_"+iSectionId).click(function(e) { EOD ); } + + /** + * @param string $sSectionLabel + * @param bool $bOpenedByDefault + * @param string $sSectionStateStorageBusinessKey + * + * @throws \Exception + */ public function StartCollapsibleSection($sSectionLabel, $bOpenedByDefault = false, $sSectionStateStorageBusinessKey = '') { $this->add($this->GetStartCollapsibleSection($sSectionLabel, $bOpenedByDefault, $sSectionStateStorageBusinessKey)); } + /** + * @param string $sSectionLabel + * @param bool $bOpenedByDefault + * @param string $sSectionStateStorageBusinessKey + * + * @return string + * @throws \Exception + */ public function GetStartCollapsibleSection($sSectionLabel, $bOpenedByDefault = false, $sSectionStateStorageBusinessKey = '') { $this->bHasCollapsibleSection = true; @@ -956,6 +1077,9 @@ EOD $this->add($this->GetEndCollapsibleSection()); } + /** + * @return string + */ public function GetEndCollapsibleSection() { return "
    "; @@ -966,12 +1090,35 @@ EOD interface iTabbedPage { + /** + * @param string $sTabContainer + * @param string $sPrefix + * + * @return mixed + */ public function AddTabContainer($sTabContainer, $sPrefix = ''); + /** + * @param string $sTabContainer + * @param string $sTabLabel + * @param string $sHtml + * + * @return mixed + */ public function AddToTab($sTabContainer, $sTabLabel, $sHtml); + /** + * @param string $sTabContainer + * + * @return mixed + */ public function SetCurrentTabContainer($sTabContainer = ''); + /** + * @param string $sTabLabel + * + * @return mixed + */ public function SetCurrentTab($sTabLabel = ''); /** @@ -992,11 +1139,20 @@ interface iTabbedPage public function GetCurrentTab(); + /** + * @param string$sTabLabel + * @param string|null $sTabContainer + * + * @return mixed + */ public function RemoveTab($sTabLabel, $sTabContainer = null); /** * Finds the tab whose title matches a given pattern * + * @param string $sPattern + * @param string|null $sTabContainer + * * @return mixed The name of the tab as a string or false if not found */ public function FindTab($sPattern, $sTabContainer = null); @@ -1018,6 +1174,12 @@ class TabManager $this->m_sCurrentTab = ''; } + /** + * @param string $sTabContainer + * @param string $sPrefix + * + * @return string + */ public function AddTabContainer($sTabContainer, $sPrefix = '') { $this->m_aTabs[$sTabContainer] = array('prefix' => $sPrefix, 'tabs' => array()); @@ -1025,11 +1187,21 @@ class TabManager return "\$Tabs:$sTabContainer\$"; } + /** + * @param string $sHtml + * + * @throws \Exception + */ public function AddToCurrentTab($sHtml) { $this->AddToTab($this->m_sCurrentTabContainer, $this->m_sCurrentTab, $sHtml); } + /** + * @param string $sHtml + * + * @return int + */ public function GetCurrentTabLength($sHtml) { $iLength = isset($this->m_aTabs[$this->m_sCurrentTabContainer]['tabs'][$this->m_sCurrentTab]['html']) ? strlen($this->m_aTabs[$this->m_sCurrentTabContainer]['tabs'][$this->m_sCurrentTab]['html']) : 0; @@ -1056,16 +1228,33 @@ class TabManager return $sResult; } + /** + * @param string $sTabContainer + * @param string $sTab + * + * @return bool + */ public function TabExists($sTabContainer, $sTab) { return isset($this->m_aTabs[$sTabContainer]['tabs'][$sTab]); } + /** + * @return int + */ public function TabsContainerCount() { return count($this->m_aTabs); } + /** + * @param string $sTabContainer + * @param string $sTabLabel + * @param string $sHtml + * + * @return string + * @throws \Exception + */ public function AddToTab($sTabContainer, $sTabLabel, $sHtml) { if (!isset($this->m_aTabs[$sTabContainer]['tabs'][$sTabLabel])) @@ -1089,6 +1278,11 @@ class TabManager return ''; // Nothing to add to the page for now } + /** + * @param string $sTabContainer + * + * @return string + */ public function SetCurrentTabContainer($sTabContainer = '') { $sPreviousTabContainer = $this->m_sCurrentTabContainer; @@ -1097,6 +1291,11 @@ class TabManager return $sPreviousTabContainer; } + /** + * @param string $sTabLabel + * + * @return string + */ public function SetCurrentTab($sTabLabel = '') { $sPreviousTab = $this->m_sCurrentTab; @@ -1133,17 +1332,26 @@ class TabManager return ''; // Nothing to add to the page for now } - + /** + * @return string + */ public function GetCurrentTabContainer() { return $this->m_sCurrentTabContainer; } + /** + * @return string + */ public function GetCurrentTab() { return $this->m_sCurrentTab; } + /** + * @param string $sTabLabel + * @param string|null $sTabContainer + */ public function RemoveTab($sTabLabel, $sTabContainer = null) { if ($sTabContainer == null) @@ -1166,6 +1374,9 @@ class TabManager /** * Finds the tab whose title matches a given pattern * + * @param string $sPattern + * @param string|null $sTabContainer + * * @return mixed The actual name of the tab (as a string) or false if not found */ public function FindTab($sPattern, $sTabContainer = null) @@ -1192,6 +1403,11 @@ class TabManager * DOES NOT WORK: apparently in the *old* version of jquery * that we are using this is not supported... TO DO upgrade * the whole jquery bundle... + * + * @param string $sTabContainer + * @param string $sTabLabel + * + * @return string */ public function SelectTab($sTabContainer, $sTabLabel) { @@ -1218,6 +1434,12 @@ class TabManager return "window.setTimeout(\"$('$sSelector').tabs('select', $tab_index);\", 100);"; // Let the time to the tabs widget to initialize } + /** + * @param string $sContent + * @param \WebPage $oPage + * + * @return mixed + */ public function RenderIntoContent($sContent, WebPage $oPage) { // Render the tabs in the page (if any)