N°3526 - Clean up pass on UIBlocks

- Move UIBlock::ENUM_BLOCK_FILES_TYPE_XXX to iUIBlock
- Add PHPDoc
- Remove Object return type hint on overloadable methods
- Add scalar return type hint
- Add type hint on parameters

sources/application/UI/Base/Component/Alert/Alert.php

@@ -123,11 +123,11 @@ class Alert extends UIContentBlock
 	}
 
 	/**
-	 * @param $sSectionStateStorageKey
+	 * @param string $sSectionStateStorageKey
 	 *
 	 * @return self
 	 */
-	public function EnableSaveCollapsibleState($sSectionStateStorageKey)
+	public function EnableSaveCollapsibleState(string $sSectionStateStorageKey)
 	{
 		$this->bIsSaveCollapsibleStateEnabled = true;
 		$this->sSectionStateStorageKey = 'UI-Collapsible__'.$sSectionStateStorageKey;
@@ -138,7 +138,7 @@ class Alert extends UIContentBlock
 	/**
 	 * @return string
 	 */
-	public function GetTitle()
+	public function GetTitle(): string
 	{
 		return $this->sTitle;
 	}
@@ -160,7 +160,7 @@ class Alert extends UIContentBlock
 	 *
 	 * @return string
 	 */
-	public function GetContent()
+	public function GetContent(): string
 	{
 		return $this->sContent;
 	}
@@ -274,11 +274,19 @@ class Alert extends UIContentBlock
 		return $this;
 	}
 
+	/**
+	 * @return bool
+	 * @see static::$bIsSaveCollapsibleStateEnabled
+	 */
 	public function IsSaveCollapsibleStateEnabled(): bool
 	{
 		return $this->bIsSaveCollapsibleStateEnabled;
 	}
 
+	/**
+	 * @return string
+	 * @see static::$sSectionStateStorageKey
+	 */
 	public function GetSessionCollapsibleStateStorageKey(): string
 	{
 		return $this->sSectionStateStorageKey;

sources/application/UI/Base/Component/Breadcrumbs/Breadcrumbs.php

@@ -74,7 +74,7 @@ class Breadcrumbs extends UIBlock
 	/**
 	 * @return array|null
 	 */
-	public function GetNewEntry()
+	public function GetNewEntry(): ?array
 	{
 		return $this->aNewEntry;
 	}
@@ -85,7 +85,7 @@ class Breadcrumbs extends UIBlock
 	 * @throws \CoreException
 	 * @throws \Exception
 	 */
-	public function GetJsWidgetOptions()
+	public function GetJsWidgetOptions(): array
 	{
 		$aJsWidgetOptions = [];
 

sources/application/UI/Base/Component/Button/Button.php

@@ -110,7 +110,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetLabel()
+	public function GetLabel(): string
 	{
 		return $this->sLabel;
 	}
@@ -129,7 +129,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetTooltip()
+	public function GetTooltip(): string
 	{
 		return $this->sTooltip;
 	}
@@ -148,7 +148,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetIconClass()
+	public function GetIconClass(): string
 	{
 		return $this->sIconClass;
 	}
@@ -167,7 +167,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetActionType()
+	public function GetActionType(): string
 	{
 		return $this->sActionType;
 	}
@@ -187,7 +187,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetColor()
+	public function GetColor(): string
 	{
 		return $this->sColor;
 	}
@@ -206,7 +206,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetOnClickJsCode()
+	public function GetOnClickJsCode(): string
 	{
 		return $this->sOnClickJsCode;
 	}
@@ -226,7 +226,7 @@ class Button extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetJsCode()
+	public function GetJsCode(): string
 	{
 		return $this->sJsCode;
 	}
@@ -246,7 +246,7 @@ class Button extends UIBlock
 	/**
 	 * @return bool
 	 */
-	public function IsDisabled()
+	public function IsDisabled(): bool
 	{
 		return $this->bIsDisabled;
 	}

sources/application/UI/Base/Component/Button/ButtonJS.php

@@ -42,11 +42,11 @@ class ButtonJS extends Button
 	/** @var string DEFAULT_TYPE */
 	public const DEFAULT_TYPE = self::ENUM_TYPE_BUTTON;
 
-	/** @var string $sType The HTML type of the button (eg. 'submit', 'button', ...) */
+	/** @var string The HTML type of the button (eg. 'submit', 'button', ...) */
 	protected $sType;
-	/** @var string $sName The HTML name of the button, used by forms */
+	/** @var string The HTML name of the button, used by forms */
 	protected $sName;
-	/** @var string $sValue The HTML value of the button, used by forms */
+	/** @var string The HTML value of the button, used by forms */
 	protected $sValue;
 
 	/**
@@ -81,7 +81,7 @@ class ButtonJS extends Button
 	/**
 	 * @return string
 	 */
-	public function GetType()
+	public function GetType(): string
 	{
 		return $this->sType;
 	}
@@ -100,7 +100,7 @@ class ButtonJS extends Button
 	/**
 	 * @return string
 	 */
-	public function GetName()
+	public function GetName(): string
 	{
 		return $this->sName;
 	}
@@ -119,7 +119,7 @@ class ButtonJS extends Button
 	/**
 	 * @return string
 	 */
-	public function GetValue()
+	public function GetValue(): string
 	{
 		return $this->sValue;
 	}

sources/application/UI/Base/Component/Button/ButtonURL.php

@@ -45,9 +45,9 @@ class ButtonURL extends Button
 	public const DEFAULT_TARGET = self::ENUM_TARGET_SELF;
 
 
-	/** @var string $sURL */
+	/** @var string */
 	protected $sURL;
-	/** @var string $sTarget */
+	/** @var string */
 	protected $sTarget;
 
 	/**

sources/application/UI/Base/Component/ButtonGroup/ButtonGroup.php

@@ -71,7 +71,7 @@ class ButtonGroup extends UIBlock
 	 * @return \Combodo\iTop\Application\UI\Base\Component\Button\Button[]
 	 * @use static::$aButtons
 	 */
-	public function GetButtons()
+	public function GetButtons(): array
 	{
 		return $this->aButtons;
 	}

sources/application/UI/Base/Component/CollapsibleSection/CollapsibleSection.php

@@ -68,7 +68,7 @@ class CollapsibleSection extends UIContentBlock
 		return $this;
 	}
 
-	public function IsOpenedByDefault()
+	public function IsOpenedByDefault(): bool
 	{
 		return $this->bIsOpenedByDefault;
 	}
@@ -85,7 +85,7 @@ class CollapsibleSection extends UIContentBlock
 		return $this;
 	}
 
-	public function GetTitle()
+	public function GetTitle(): string
 	{
 		return $this->sTitle;
 	}

sources/application/UI/Base/Component/Dashlet/DashletBadge.php

@@ -78,7 +78,7 @@ class DashletBadge extends DashletContainer
 	 *
 	 * @return DashletBadge
 	 */
-	public function SetCreateActionUrl(?string $sCreateActionUrl): DashletBadge
+	public function SetCreateActionUrl(?string $sCreateActionUrl)
 	{
 		$this->sCreateActionUrl = $sCreateActionUrl;
 
@@ -98,7 +98,7 @@ class DashletBadge extends DashletContainer
 	 *
 	 * @return DashletBadge
 	 */
-	public function SetCreateActionLabel(?string $sCreateActionLabel): DashletBadge
+	public function SetCreateActionLabel(?string $sCreateActionLabel)
 	{
 		$this->sCreateActionLabel = $sCreateActionLabel;
 
@@ -118,7 +118,7 @@ class DashletBadge extends DashletContainer
 	 *
 	 * @return DashletBadge
 	 */
-	public function SetClassIconUrl(string $sClassIconUrl): DashletBadge
+	public function SetClassIconUrl(string $sClassIconUrl)
 	{
 		$this->sClassIconUrl = $sClassIconUrl;
 
@@ -138,7 +138,7 @@ class DashletBadge extends DashletContainer
 	 *
 	 * @return DashletBadge
 	 */
-	public function SetHyperlink(string $sHyperlink): DashletBadge
+	public function SetHyperlink(string $sHyperlink)
 	{
 		$this->sHyperlink = $sHyperlink;
 
@@ -158,7 +158,7 @@ class DashletBadge extends DashletContainer
 	 *
 	 * @return DashletBadge
 	 */
-	public function SetCount(string $iCount): DashletBadge
+	public function SetCount(string $iCount)
 	{
 		$this->iCount = $iCount;
 
@@ -178,7 +178,7 @@ class DashletBadge extends DashletContainer
 	 *
 	 * @return DashletBadge
 	 */
-	public function SetClassLabel(string $sClassLabel): DashletBadge
+	public function SetClassLabel(string $sClassLabel)
 	{
 		$this->sClassLabel = $sClassLabel;
 

sources/application/UI/Base/Component/DataTable/DataTable.php

@@ -76,8 +76,10 @@ class DataTable extends UIContentBlock
 
 	/**
 	 * @param mixed $sAjaxUrl
+	 *
+	 * @return $this
 	 */
-	public function SetAjaxUrl(string $sAjaxUrl): void
+	public function SetAjaxUrl(string $sAjaxUrl)
 	{
 		if (strlen($sAjaxUrl) > 0)
 		{
@@ -92,6 +94,8 @@ class DataTable extends UIContentBlock
 		{
 			$this->sAjaxUrl = $sAjaxUrl;
 		}
+
+		return $this;
 	}
 
 	/**

sources/application/UI/Base/Component/DataTable/DataTableConfig/DataTableConfig.php

@@ -25,7 +25,7 @@ class DataTableConfig extends UIContentBlock
 	/**
 	 * @return \Combodo\iTop\Application\UI\Base\Component\DataTable\DataTable
 	 */
-	private function GetDataTable(): DataTable
+	private function GetDataTable()
 	{
 		return $this->oDataTable;
 	}

sources/application/UI/Base/Component/DataTable/StaticTable/FormTable/FormTable.php

@@ -49,9 +49,11 @@ class FormTable extends StaticTable
 	/**
 	 * @param string $sRef
 	 */
-	public function SetRef(string $sRef): void
+	public function SetRef(string $sRef)
 	{
 		$this->sRef = $sRef;
+
+		return $this;
 	}
 
 	public function GetRows(): array
@@ -59,7 +61,7 @@ class FormTable extends StaticTable
 		return $this->aRows;
 	}
 
-	public function AddRow(FormTableRow $oRow): self
+	public function AddRow(FormTableRow $oRow)
 	{
 		$this->aRows[] = $oRow;
 		return $this;

sources/application/UI/Base/Component/DataTable/StaticTable/FormTableRow/FormTableRow.php

@@ -67,10 +67,14 @@ class FormTableRow extends UIBlock
 
 	/**
 	 * @param string $sRef
+	 *
+	 * @return $this
 	 */
-	public function SetRef(string $sRef): void
+	public function SetRef(string $sRef)
 	{
 		$this->sRef = $sRef;
+
+		return $this;
 	}
 
 	/**
@@ -83,10 +87,14 @@ class FormTableRow extends UIBlock
 
 	/**
 	 * @param array $aColumns
+	 *
+	 * @return $this
 	 */
-	public function SetColumns(array $aColumns): void
+	public function SetColumns(array $aColumns)
 	{
 		$this->aColumns = $aColumns;
+
+		return $this;
 	}
 
 	/**
@@ -99,10 +107,14 @@ class FormTableRow extends UIBlock
 
 	/**
 	 * @param array $aData
+	 *
+	 * @return $this
 	 */
-	public function SetData(array $aData): void
+	public function SetData(array $aData)
 	{
 		$this->aData = $aData;
+
+		return $this;
 	}
 
 	/**
@@ -115,9 +127,13 @@ class FormTableRow extends UIBlock
 
 	/**
 	 * @param int $iRowId
+	 *
+	 * @return $this
 	 */
-	public function SetRowId(int $iRowId): void
+	public function SetRowId(int $iRowId)
 	{
 		$this->iRowId = $iRowId;
+
+		return $this;
 	}
 }

sources/application/UI/Base/Component/DataTable/StaticTable/StaticTable.php

@@ -82,10 +82,14 @@ class StaticTable extends UIContentBlock
 
 	/**
 	 * @param array $aColumns
+	 *
+	 * @return $this
 	 */
-	public function SetColumns(array $aColumns): void
+	public function SetColumns(array $aColumns)
 	{
 		$this->aColumns = $aColumns;
+
+		return $this;
 	}
 
 	/**
@@ -98,18 +102,26 @@ class StaticTable extends UIContentBlock
 
 	/**
 	 * @param array $aData
+	 *
+	 * @return $this
 	 */
-	public function SetData(array $aData): void
+	public function SetData(array $aData)
 	{
 		$this->aData = $aData;
+
+		return $this;
 	}
 
 	/**
 	 * @param string $sFilter
+	 *
+	 * @return $this
 	 */
-	public function SetFilter($sFilter): void
+	public function SetFilter($sFilter)
 	{
 		$this->sFilter = $sFilter;
+
+		return $this;
 	}
 
 	public function GetJSRefresh(): string

sources/application/UI/Base/Component/Field/Field.php

@@ -72,7 +72,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sLayout
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetLayout(string $sLayout)
 	{
@@ -92,9 +92,9 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sAttCode
 	 *
-	 * @return Field
+	 * @return $this
 	 */
-	public function SetAttCode(string $sAttCode): Field
+	public function SetAttCode(string $sAttCode)
 	{
 		$this->sAttCode = $sAttCode;
 
@@ -112,9 +112,9 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sAttType
 	 *
-	 * @return Field
+	 * @return $this
 	 */
-	public function SetAttType(string $sAttType): Field
+	public function SetAttType(string $sAttType)
 	{
 		$this->sAttType = $sAttType;
 
@@ -132,9 +132,9 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sAttLabel
 	 *
-	 * @return Field
+	 * @return $this
 	 */
-	public function SetAttLabel(string $sAttLabel): Field
+	public function SetAttLabel(string $sAttLabel)
 	{
 		$this->sAttLabel = $sAttLabel;
 
@@ -152,7 +152,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param bool $bIsReadOnly
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetIsReadOnly(bool $bIsReadOnly)
 	{
@@ -172,7 +172,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param bool $bIsMandatory
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetIsMandatory(bool $bIsMandatory)
 	{
@@ -192,7 +192,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param bool $bIsMustChange
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetMustChange(bool $bIsMustChange)
 	{
@@ -212,7 +212,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param bool $bIsMustPrompt
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetMustPrompt(bool $bIsMustPrompt)
 	{
@@ -232,7 +232,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param bool $bIsSlave
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetIsSlave(bool $bIsSlave)
 	{
@@ -252,7 +252,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sValueRaw
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetValueRaw(string $sValueRaw)
 	{
@@ -272,7 +272,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sLabel
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetLabel(string $sLabel)
 	{
@@ -292,7 +292,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param \Combodo\iTop\Application\UI\Base\UIBlock $oValue
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetValue(UIBlock $oValue)
 	{
@@ -312,7 +312,7 @@ class Field extends UIContentBlock
 	/**
 	 * @param string $sComments
 	 *
-	 * @return Field
+	 * @return $this
 	 */
 	public function SetComments(string $sComments)
 	{
@@ -344,10 +344,14 @@ class Field extends UIContentBlock
 	public function SetInputId(string $sInputId)
 	{
 		$this->AddDataAttribute('input-id', $sInputId);
+
+		return $this;
 	}
 
 	public function SetInputType(string $sInputType)
 	{
 		$this->AddDataAttribute('input-type', $sInputType);
+
+		return $this;
 	}
 }

sources/application/UI/Base/Component/Form/Form.php

@@ -32,7 +32,7 @@ class Form extends UIContentBlock
 		$this->sAction = null;
 	}
 
-	public function SetOnSubmitJsCode(string $sJsCode): Form
+	public function SetOnSubmitJsCode(string $sJsCode)
 	{
 		$this->sOnSubmitJsCode = $sJsCode;
 		return $this;
@@ -59,7 +59,7 @@ class Form extends UIContentBlock
 	 *
 	 * @return Form
 	 */
-	public function SetAction(string $sAction): Form
+	public function SetAction(string $sAction)
 	{
 		$this->sAction = $sAction;
 		return $this;

sources/application/UI/Base/Component/GlobalSearch/GlobalSearch.php

@@ -97,7 +97,7 @@ class GlobalSearch extends UIBlock implements iKeyboardShortcut
 	 * @return string
 	 * @throws \Exception
 	 */
-	public function GetEndpoint()
+	public function GetEndpoint(): string
 	{
 		return $this->sEndpoint;
 	}
@@ -151,7 +151,7 @@ class GlobalSearch extends UIBlock implements iKeyboardShortcut
 	 *
 	 * @return array
 	 */
-	public function GetLastQueries()
+	public function GetLastQueries(): array
 	{
 		return $this->aLastQueries;
 	}

sources/application/UI/Base/Component/Html/Html.php

@@ -55,7 +55,7 @@ class Html extends UIBlock
 	 *
 	 * @return string
 	 */
-	public function GetHtml()
+	public function GetHtml(): string
 	{
 		return $this->sHtml;
 	}

sources/application/UI/Base/Component/Input/FileSelect/FileSelect.php

@@ -39,7 +39,7 @@ class FileSelect extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetFileName()
+	public function GetFileName(): string
 	{
 		return $this->sFileName;
 	}

sources/application/UI/Base/Component/Input/Input.php

@@ -61,7 +61,7 @@ class Input extends AbstractInput
 	/**
 	 * @return bool
 	 */
-	public function IsChecked()
+	public function IsChecked(): bool
 	{
 		return $this->bIsChecked;
 	}
@@ -69,7 +69,7 @@ class Input extends AbstractInput
 	/**
 	 * @return bool
 	 */
-	public function IsDisabled()
+	public function IsDisabled(): bool
 	{
 		return $this->bIsDisabled;
 	}
@@ -88,7 +88,7 @@ class Input extends AbstractInput
 	/**
 	 * @return bool
 	 */
-	public function IsReadonly()
+	public function IsReadonly(): bool
 	{
 		return $this->bIsReadonly;
 	}
@@ -107,7 +107,7 @@ class Input extends AbstractInput
 	/**
 	 * @return string|null
 	 */
-	public function GetLabel()
+	public function GetLabel(): ?string
 	{
 		return $this->sLabel;
 	}
@@ -124,7 +124,7 @@ class Input extends AbstractInput
 		return $this;
 	}
 
-	public function HasLabel()
+	public function HasLabel(): bool
 	{
 		return !is_null($this->sLabel);
 	}

sources/application/UI/Base/Component/Input/InputWithLabel.php

@@ -97,7 +97,7 @@ class InputWithLabel extends UIBlock
 	 *
 	 * @return InputWithLabel
 	 */
-	public function SetLabel(string $sLabel): InputWithLabel
+	public function SetLabel(string $sLabel)
 	{
 		$this->sLabel = $sLabel;
 		return $this;

sources/application/UI/Base/Component/Input/Select/Select.php

@@ -89,8 +89,10 @@ class Select extends UIContentBlock
 	/**
 	 * @param bool $bIsMultiple {@see Select::$bIsMultiple}
 	 */
-	public function SetIsMultiple(bool $bIsMultiple): void
+	public function SetIsMultiple(bool $bIsMultiple)
 	{
 		$this->bIsMultiple = $bIsMultiple;
+
+		return $this;
 	}
 }

sources/application/UI/Base/Component/Input/Select/SelectOption.php

@@ -38,7 +38,7 @@ class SelectOption extends UIBlock
 	 *
 	 * @return SelectOption
 	 */
-	public function SetValue(string $sValue): SelectOption
+	public function SetValue(string $sValue)
 	{
 		$this->sValue = $sValue;
 		return $this;
@@ -57,7 +57,7 @@ class SelectOption extends UIBlock
 	 *
 	 * @return SelectOption
 	 */
-	public function SetLabel(string $sLabel): SelectOption
+	public function SetLabel(string $sLabel)
 	{
 		$this->sLabel = $sLabel;
 		return $this;
@@ -76,7 +76,7 @@ class SelectOption extends UIBlock
 	 *
 	 * @return SelectOption
 	 */
-	public function SetSelected(bool $bSelected): SelectOption
+	public function SetSelected(bool $bSelected)
 	{
 		$this->bSelected = $bSelected;
 		return $this;

sources/application/UI/Base/Component/Input/TextArea.php

@@ -78,10 +78,14 @@ class TextArea extends AbstractInput
 
 	/**
 	 * @param bool $bIsDisabled
+	 *
+	 * @return $this
 	 */
-	public function SetIsDisabled(bool $bIsDisabled): void
+	public function SetIsDisabled(bool $bIsDisabled)
 	{
 		$this->bIsDisabled = $bIsDisabled;
+
+		return $this;
 	}
 
 

sources/application/UI/Base/Component/MedallionIcon/MedallionIcon.php

@@ -32,9 +32,9 @@ class MedallionIcon extends UIBlock
 	 *
 	 * @param string $sImageUrl
 	 * @param string $sIconClass
-	 * @param null $sId
+	 * @param string|null $sId
 	 */
-	public function __construct($sImageUrl = '', $sIconClass = '', $sId = null)
+	public function __construct(string $sImageUrl = '', string $sIconClass = '', ?string $sId = null)
 	{
 		parent::__construct($sId);
 		$this->sImageUrl = $sImageUrl;
@@ -44,7 +44,7 @@ class MedallionIcon extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetImageUrl()
+	public function GetImageUrl(): string
 	{
 		return $this->sImageUrl;
 	}
@@ -63,7 +63,7 @@ class MedallionIcon extends UIBlock
 	/**
 	 * @return string
 	 */
-	public function GetIconClass()
+	public function GetIconClass(): string
 	{
 		return $this->sIconClass;
 	}

sources/application/UI/Base/Component/Panel/Panel.php

@@ -390,7 +390,7 @@ class Panel extends UIContentBlock
 	 * @see static::$sCSSColorClass
 	 * @return string
 	 */
-	public function GetCSSColorClass()
+	public function GetCSSColorClass(): string
 	{
 		return $this->sCSSColorClass;
 	}

sources/application/UI/Base/Component/PopoverMenu/NewsroomMenu/NewsroomMenu.php

@@ -61,7 +61,7 @@ class NewsroomMenu extends PopoverMenu
 	 *
 	 * @return false|string
 	 */
-	public function GetParamsAsJson()
+	public function GetParamsAsJson(): string
 	{
 		return json_encode($this->aParams);
 	}

sources/application/UI/Base/Component/PopoverMenu/PopoverMenu.php

@@ -372,7 +372,7 @@ class PopoverMenu extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasSection(string $sId)
+	public function HasSection(string $sId): bool
 	{
 		return array_key_exists($sId, $this->aSections);
 	}
@@ -402,7 +402,7 @@ class PopoverMenu extends UIBlock
 	 *
 	 * @return array
 	 */
-	public function GetSections()
+	public function GetSections(): array
 	{
 		return $this->aSections;
 	}
@@ -520,7 +520,7 @@ class PopoverMenu extends UIBlock
 	/**
 	 * @inheritDoc
 	 */
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		$aSubBlocks = [];
 

sources/application/UI/Base/Component/PopoverMenu/PopoverMenuItem/JsPopoverMenuItem.php

@@ -57,7 +57,7 @@ class JsPopoverMenuItem extends PopoverMenuItem
 	 * @inheritDoc
 	 * @throws \Exception
 	 */
-	public function GetJsFilesUrlRecursively(bool $bAbsoluteUrl = false)
+	public function GetJsFilesUrlRecursively(bool $bAbsoluteUrl = false): array
 	{
 		$aJsFiles = array_merge(parent::GetJsFilesUrlRecursively($bAbsoluteUrl), $this->oPopupMenuItem->GetLinkedScripts());
 

sources/application/UI/Base/Component/PopoverMenu/PopoverMenuItem/PopoverMenuItem.php

@@ -55,7 +55,7 @@ class PopoverMenuItem extends UIBlock
 	/**
 	 * @inheritDoc
 	 */
-	protected function GenerateId()
+	protected function GenerateId(): string
 	{
 		return parent::GenerateId().'--'.utils::GetSafeId($this->oPopupMenuItem->GetUID());
 	}

sources/application/UI/Base/Component/QuickCreate/QuickCreate.php

@@ -107,7 +107,7 @@ class QuickCreate extends UIBlock implements iKeyboardShortcut
 	 * @return string
 	 * @throws \Exception
 	 */
-	public function GetEndpoint()
+	public function GetEndpoint(): string
 	{
 		return $this->sEndpoint;
 	}
@@ -117,7 +117,7 @@ class QuickCreate extends UIBlock implements iKeyboardShortcut
 	 *
 	 * @return array
 	 */
-	public function GetAvailableClasses()
+	public function GetAvailableClasses(): array
 	{
 		return $this->aAvailableClasses;
 	}
@@ -171,7 +171,7 @@ class QuickCreate extends UIBlock implements iKeyboardShortcut
 	 *
 	 * @return array
 	 */
-	public function GetLastClasses()
+	public function GetLastClasses(): array
 	{
 		return $this->aLastClasses;
 	}

sources/application/UI/Base/Layout/ActivityPanel/ActivityEntry/ActivityEntry.php

@@ -115,7 +115,7 @@ class ActivityEntry extends UIBlock
 	 *
 	 * @return string
 	 */
-	public function GetType()
+	public function GetType(): string
 	{
 		return $this->sType;
 	}
@@ -139,7 +139,7 @@ class ActivityEntry extends UIBlock
 	 *
 	 * @return string
 	 */
-	public function GetDecorationClasses()
+	public function GetDecorationClasses(): string
 	{
 		return $this->sDecorationClasses;
 	}
@@ -163,7 +163,7 @@ class ActivityEntry extends UIBlock
 	 *
 	 * @return string
 	 */
-	public function GetContent()
+	public function GetContent(): string
 	{
 		return $this->sContent;
 	}
@@ -183,7 +183,7 @@ class ActivityEntry extends UIBlock
 	 * Return the date time without formatting, as per the mysql format
 	 * @return string
 	 */
-	public function GetRawDateTime()
+	public function GetRawDateTime(): string
 	{
 		return $this->oDateTime->format(AttributeDateTime::GetInternalFormat());
 	}
@@ -194,7 +194,7 @@ class ActivityEntry extends UIBlock
 	 * @return string
 	 * @throws \Exception
 	 */
-	public function GetFormattedDateTime()
+	public function GetFormattedDateTime(): string
 	{
 		$oDateTimeFormat = AttributeDateTime::GetFormat();
 		return $oDateTimeFormat->Format($this->oDateTime);
@@ -277,7 +277,7 @@ class ActivityEntry extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function IsFromCurrentUser()
+	public function IsFromCurrentUser(): bool
 	{
 		return $this->bIsFromCurrentUser;
 	}
@@ -301,7 +301,7 @@ class ActivityEntry extends UIBlock
 	 *
 	 * @return string
 	 */
-	public function GetOrigin()
+	public function GetOrigin(): string
 	{
 		return $this->sOrigin;
 	}

sources/application/UI/Base/Layout/ActivityPanel/ActivityEntry/CaseLogEntry.php

@@ -46,7 +46,7 @@ class CaseLogEntry extends ActivityEntry
 	/** @var string $sAttCode Code of the corresponding case log attribute */
 	protected $sAttCode;
 	/** @var int $iCaseLogRank Rank of its case log in the host panel, can be used for highlight purposes for example */
-	protected $iCaseLogRank;	
+	protected $iCaseLogRank;
 	/** @var string $sAuthorName Fallback name used if $sAuthorLogin is empty */
 	protected $sAuthorName;
 
@@ -104,7 +104,7 @@ class CaseLogEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetAttCode()
+	public function GetAttCode(): string
 	{
 		return $this->sAttCode;
 	}
@@ -128,7 +128,7 @@ class CaseLogEntry extends ActivityEntry
 	 *
 	 * @return int
 	 */
-	public function GetCaseLogRank()
+	public function GetCaseLogRank(): int
 	{
 		return $this->iCaseLogRank;
 	}

sources/application/UI/Base/Layout/ActivityPanel/ActivityEntry/EditsEntry.php

@@ -70,7 +70,7 @@ class EditsEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetObjectClass()
+	public function GetObjectClass(): string
 	{
 		return $this->sObjectClass;
 	}
@@ -94,7 +94,7 @@ class EditsEntry extends ActivityEntry
 	 *
 	 * @return array
 	 */
-	public function GetAttributes()
+	public function GetAttributes(): array
 	{
 		return $this->aAttributes;
 	}
@@ -175,7 +175,7 @@ class EditsEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetShortDescriptionAsHtml()
+	public function GetShortDescriptionAsHtml(): string
 	{
 		// We need the array to be indexed by numbers instead of being associative
 		$aAttributesData = array_values($this->GetAttributes());

sources/application/UI/Base/Layout/ActivityPanel/ActivityEntry/TransitionEntry.php

@@ -94,7 +94,7 @@ class TransitionEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetOriginalStateCode()
+	public function GetOriginalStateCode(): string
 	{
 		return $this->sOriginStateCode;
 	}
@@ -104,7 +104,7 @@ class TransitionEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetOriginalStateLabel()
+	public function GetOriginalStateLabel(): string
 	{
 		return $this->sOriginStateLabel;
 	}
@@ -131,7 +131,7 @@ class TransitionEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetTargetStateCode()
+	public function GetTargetStateCode(): string
 	{
 		return $this->sTargetStateCode;
 	}
@@ -141,7 +141,7 @@ class TransitionEntry extends ActivityEntry
 	 *
 	 * @return string
 	 */
-	public function GetTargetStateLabel()
+	public function GetTargetStateLabel(): string
 	{
 		return $this->sTargetStateLabel;
 	}

sources/application/UI/Base/Layout/ActivityPanel/ActivityPanel.php

@@ -295,7 +295,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return ActivityEntry[]
 	 */
-	public function GetEntries()
+	public function GetEntries(): array
 	{
 		if ($this->bAreEntriesSorted === false)
 		{
@@ -311,7 +311,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return array
 	 */
-	public function GetGroupedEntries()
+	public function GetGroupedEntries(): array
 	{
 		$aGroupedEntries = [];
 
@@ -462,7 +462,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasEntries()
+	public function HasEntries(): bool
 	{
 		return !empty($this->aEntries);
 	}
@@ -518,7 +518,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return array
 	 */
-	public function GetCaseLogTabs()
+	public function GetCaseLogTabs(): array
 	{
 		return $this->aCaseLogs;
 	}
@@ -611,7 +611,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasCaseLogTab(string $sAttCode)
+	public function HasCaseLogTab(string $sAttCode): bool
 	{
 		return isset($this->aCaseLogs[$sAttCode]);
 	}
@@ -621,7 +621,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasCaseLogTabs()
+	public function HasCaseLogTabs(): bool
 	{
 		return !empty($this->aCaseLogs);
 	}
@@ -811,7 +811,7 @@ class ActivityPanel extends UIBlock
 	 *
 	 * @return string
 	 */
-	public function GetDateTimeFormatForJSWidget()
+	public function GetDateTimeFormatForJSWidget(): string
 	{
 		$oDateTimeFormat = AttributeDateTime::GetFormat();
 
@@ -848,7 +848,7 @@ class ActivityPanel extends UIBlock
 	/**
 	 * @inheritdoc
 	 */
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		$aSubBlocks = array();
 

sources/application/UI/Base/Layout/ActivityPanel/CaseLogEntryForm/CaseLogEntryForm.php

@@ -252,7 +252,7 @@ class CaseLogEntryForm extends UIContentBlock
 	/**
 	 * @return \Combodo\iTop\Application\UI\Base\UIBlock[]
 	 */
-	public function GetExtraActionButtons()
+	public function GetExtraActionButtons(): array
 	{
 		return $this->aExtraActionButtons;
 	}

sources/application/UI/Base/Layout/Dashboard/DashboardColumn.php

@@ -42,7 +42,7 @@ class DashboardColumn extends UIBlock
 	 *
 	 * @param UIBlock $oUIBlock
 	 *
-	 * @return DashboardColumn
+	 * @return $this
 	 */
 	public function AddUIBlock(UIBlock $oUIBlock): DashboardColumn
 	{
@@ -50,7 +50,7 @@ class DashboardColumn extends UIBlock
 		return $this;
 	}
 
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		return $this->aUIBlocks;
 	}
@@ -66,9 +66,9 @@ class DashboardColumn extends UIBlock
 	/**
 	 * @param int $iColumnIndex
 	 *
-	 * @return DashboardColumn
+	 * @return $this
 	 */
-	public function SetColumnIndex(int $iColumnIndex): DashboardColumn
+	public function SetColumnIndex(int $iColumnIndex)
 	{
 		$this->iColumnIndex = $iColumnIndex;
 		return $this;
@@ -85,9 +85,9 @@ class DashboardColumn extends UIBlock
 	/**
 	 * @param bool $bEditMode
 	 *
-	 * @return DashboardColumn
+	 * @return $this
 	 */
-	public function SetEditMode(bool $bEditMode): DashboardColumn
+	public function SetEditMode(bool $bEditMode)
 	{
 		$this->bEditMode = $bEditMode;
 		return $this;
@@ -104,9 +104,9 @@ class DashboardColumn extends UIBlock
 	/**
 	 * @param int $iCellIndex
 	 *
-	 * @return DashboardColumn
+	 * @return $this
 	 */
-	public function SetCellIndex(int $iCellIndex): DashboardColumn
+	public function SetCellIndex(int $iCellIndex)
 	{
 		$this->iCellIndex = $iCellIndex;
 		return $this;
@@ -123,9 +123,9 @@ class DashboardColumn extends UIBlock
 	/**
 	 * @param bool $bLastRow
 	 *
-	 * @return DashboardColumn
+	 * @return $this
 	 */
-	public function SetLastRow(bool $bLastRow): DashboardColumn
+	public function SetLastRow(bool $bLastRow)
 	{
 		$this->bLastRow = $bLastRow;
 		return $this;

sources/application/UI/Base/Layout/Dashboard/DashboardLayout.php

@@ -48,7 +48,7 @@ class DashboardLayout extends UIBlock
 		return $this;
 	}
 
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		return array_merge($this->aDashboardRows, [$this->oToolbar]);
 	}

sources/application/UI/Base/Layout/Dashboard/DashboardRow.php

@@ -35,9 +35,9 @@ class DashboardRow extends UIBlock
 	 *
 	 * @param \Combodo\iTop\Application\UI\Base\Layout\Dashboard\DashboardColumn $oDashboardColumn
 	 *
-	 * @return DashboardRow
+	 * @return $this
 	 */
-	public function AddDashboardColumn(DashboardColumn $oDashboardColumn): DashboardRow
+	public function AddDashboardColumn(DashboardColumn $oDashboardColumn)
 	{
 		$oDashboardColumn->SetColumnIndex($this->iCols);
 		$this->aDashboardColumns[] = $oDashboardColumn;
@@ -45,7 +45,7 @@ class DashboardRow extends UIBlock
 		return $this;
 	}
 
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		return $this->aDashboardColumns;
 	}
@@ -61,9 +61,9 @@ class DashboardRow extends UIBlock
 	/**
 	 * @param int $iRowIndex
 	 *
-	 * @return DashboardRow
+	 * @return $this
 	 */
-	public function SetRowIndex(int $iRowIndex): DashboardRow
+	public function SetRowIndex(int $iRowIndex)
 	{
 		$this->iRowIndex = $iRowIndex;
 		return $this;

sources/application/UI/Base/Layout/NavigationMenu/NavigationMenu.php

@@ -125,7 +125,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	/**
 	 * @return string
 	 */
-	public function GetAppRevisionNumber()
+	public function GetAppRevisionNumber(): string
 	{
 		return $this->sAppRevisionNumber;
 	}
@@ -134,7 +134,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	 * @uses $sAppSquareIconUrl
 	 * @return string
 	 */
-	public function GetAppSquareIconUrl()
+	public function GetAppSquareIconUrl(): string
 	{
 		return $this->sAppSquareIconUrl;
 	}
@@ -143,7 +143,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	 * @uses $sAppFullIconUrl
 	 * @return string
 	 */
-	public function GetAppFullIconUrl()
+	public function GetAppFullIconUrl(): string
 	{
 		return $this->sAppFullIconUrl;
 	}
@@ -152,7 +152,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	 * @uses $sAppIconLink
 	 * @return string
 	 */
-	public function GetAppIconLink()
+	public function GetAppIconLink(): string
 	{
 		return $this->sAppIconLink;
 	}
@@ -200,7 +200,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	/**
 	 * @return array
 	 */
-	public function GetMenuGroups()
+	public function GetMenuGroups(): array
 	{
 		return $this->aMenuGroups;
 	}
@@ -208,7 +208,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	/**
 	 * @return array
 	 */
-	public function GetUserData()
+	public function GetUserData(): array
 	{
 		return $this->aUserData;
 	}
@@ -234,7 +234,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	 *
 	 * @return bool
 	 */
-	public function IsExpanded()
+	public function IsExpanded(): bool
 	{
 		return $this->bIsExpanded;
 	}
@@ -251,7 +251,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	/**
 	 * @inheritDoc
 	 */
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		return [$this->oUserMenu->GetId() => $this->oUserMenu, $this->GetNewsroomMenu()->GetId() => $this->GetNewsroomMenu()];
 	}
@@ -259,7 +259,7 @@ class NavigationMenu extends UIBlock implements iKeyboardShortcut
 	/**
 	 * @return boolean
 	 */
-	public function IsNewsroomEnabled()
+	public function IsNewsroomEnabled(): bool
 	{
 		return MetaModel::GetConfig()->Get('newsroom_enabled');
 	}

sources/application/UI/Base/Layout/PageContent/PageContentWithSideContent.php

@@ -70,7 +70,7 @@ class PageContentWithSideContent extends PageContent {
 	 * @return \Combodo\iTop\Application\UI\Base\iUIBlock[]
 	 * @throws \Exception
 	 */
-	public function GetSideBlocks() {
+	public function GetSideBlocks(): array {
 		return $this->GetContentAreaBlocks(static::ENUM_CONTENT_AREA_SIDE);
 	}
 

sources/application/UI/Base/Layout/TabContainer/TabContainer.php

@@ -145,7 +145,7 @@ class TabContainer extends UIContentBlock
 		return $oTab;
 	}
 
-	public function RemoveTab(string $sTabCode): self
+	public function RemoveTab(string $sTabCode)
 	{
 		$this->RemoveSubBlock($sTabCode);
 		return $this;

sources/application/UI/Base/Layout/TopBar/TopBar.php

@@ -95,7 +95,7 @@ class TopBar extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasQuickCreate()
+	public function HasQuickCreate(): bool
 	{
 		return ($this->oQuickCreate !== null);
 	}
@@ -128,7 +128,7 @@ class TopBar extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasGlobalSearch()
+	public function HasGlobalSearch(): bool
 	{
 		return ($this->oGlobalSearch !== null);
 	}
@@ -161,7 +161,7 @@ class TopBar extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasBreadcrumbs()
+	public function HasBreadcrumbs(): bool
 	{
 		return ($this->oBreadcrumbs !== null);
 	}
@@ -179,7 +179,7 @@ class TopBar extends UIBlock
 	 *
 	 * @return TopBar
 	 */
-	public function SetToolbar(?Toolbar $oToolbar): TopBar
+	public function SetToolbar(?Toolbar $oToolbar)
 	{
 		$this->oToolbar = $oToolbar;
 		return $this;
@@ -190,7 +190,7 @@ class TopBar extends UIBlock
 	 *
 	 * @return bool
 	 */
-	public function HasToolbar()
+	public function HasToolbar(): bool
 	{
 		return ($this->oToolbar !== null);
 	}
@@ -198,7 +198,7 @@ class TopBar extends UIBlock
 	/**
 	 * @inheritDoc
 	 */
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		$aSubBlocks = [];
 

sources/application/UI/Base/UIBlock.php

@@ -32,10 +32,9 @@ use utils;
  */
 abstract class UIBlock implements iUIBlock
 {
-	/** @var string BLOCK_CODE The block code to use to generate the identifier, the CSS/JS prefixes, ...
-	 *
-	 * Should start "ibo-" for the iTop backoffice blocks, followed by the name of the block in lower case (eg. for a MyCustomBlock class,
-	 * should be "ibo-my-custom-clock")
+	/**
+	 * @var string The block code to use to generate the identifier, the CSS/JS prefixes, ...
+	 * Should start "ibo-" for the iTop backoffice blocks, followed by the name of the block in lower case (eg. for a MyCustomBlock class, should be "ibo-my-custom-block")
 	 */
 	public const BLOCK_CODE = 'ibo-block';
 	/**
@@ -49,59 +48,100 @@ abstract class UIBlock implements iUIBlock
 	 */
 	public const REQUIRES_ANCESTORS_DEFAULT_CSS_FILES = false;
 
-	/** @var string|null */
+	/**
+	 * @var string|null
+	 * @see static::$GetGlobalTemplateRelPath
+	 */
 	public const DEFAULT_GLOBAL_TEMPLATE_REL_PATH = null;
-	/** @var string|null */
+	/**
+	 * @var string|null
+	 * @see static::$sHtmlTemplateRelPath
+	 */
 	public const DEFAULT_HTML_TEMPLATE_REL_PATH = null;
 	/**
-	 * @var array list of external JS file paths to include in the page. Paths are relative to APPROOT
-	 *    **Warning** : if you need to call a JS var defined in one of this file, then this calling code MUST be in {@see DEFAULT_JS_ON_READY_TEMPLATE_REL_PATH}
-	 *         and not in {@see DEFAULT_JS_TEMPLATE_REL_PATH} ! Indeed the later is output before external files loading.
+	 * @var array
+	 * @see static::$aJsFilesRelPath
 	 */
 	public const DEFAULT_JS_FILES_REL_PATH = [
 		'js/ui-block.js',
 	];
-	/** @var string|null */
+	/**
+	 * @var string|null Relative path (from <ITOP>/templates/) to the "on init" JS template
+	 * @see static::$aJsTemplatesRelPath
+	 * @see iUIBlock::ENUM_JS_TYPE_ON_INIT
+	 */
 	public const DEFAULT_JS_TEMPLATE_REL_PATH = null;
-	/** @var string|null Relative path (from <ITOP>/templates/) to the JS template not deferred */
+	/**
+	 * @var string|null Relative path (from <ITOP>/templates/) to the JS template not deferred
+	 * @see static::$aJsTemplatesRelPath
+	 * @see iUIBlock::ENUM_JS_TYPE_LIVE
+	 */
 	public const DEFAULT_JS_LIVE_TEMPLATE_REL_PATH = null;
-	/** @var string|null Relative path (from <ITOP>/templates/) to the JS template after DEFAULT_JS_TEMPLATE_REL_PATH */
+	/**
+	 * @var string|null Relative path (from <ITOP>/templates/) to the JS template after DEFAULT_JS_TEMPLATE_REL_PATH
+	 * @see static::$aJsTemplatesRelPath
+	 * @see iUIBlock::ENUM_JS_TYPE_ON_READY
+	 */
 	public const DEFAULT_JS_ON_READY_TEMPLATE_REL_PATH = null;
-	/** @var array */
+	/**
+	 * @var array
+	 * @see static::$aCssFilesRelPath
+	 */
 	public const DEFAULT_CSS_FILES_REL_PATH = [];
-	/** @var string|null */
+	/**
+	 * @var string|null
+	 * @see static::$sCssTemplateRelPath
+	 */
 	public const DEFAULT_CSS_TEMPLATE_REL_PATH = null;
-	/** @var bool */
+	/**
+	 * @var bool
+	 * @see static::$bIsHidden
+	 */
 	public const DEFAULT_IS_HIDDEN = false;
-	/** @var array */
+	/**
+	 * @var array
+	 * @see static::$aAdditionalCSSClasses
+	 */
 	public const DEFAULT_ADDITIONAL_CSS_CLASSES = [];
 
-	/** @var string ENUM_BLOCK_FILES_TYPE_JS */
-	public const ENUM_BLOCK_FILES_TYPE_JS = 'js';
-	/** @var string ENUM_BLOCK_FILES_TYPE_CSS */
-	public const ENUM_BLOCK_FILES_TYPE_CSS = 'css';
-	/** @var string ENUM_BLOCK_FILES_TYPE_FILE */
-	public const ENUM_BLOCK_FILES_TYPE_FILES = 'files';
-	/** @var string ENUM_BLOCK_FILES_TYPE_TEMPLATE */
-	public const ENUM_BLOCK_FILES_TYPE_TEMPLATE = 'template';
-
 	/** @var array Cache for the CSS classes of a block inheritance. Key is the block class, value is an array of CSS classes */
 	private static $aBlocksInheritanceCSSClassesCache = [];
 
 	/** @var string $sId */
 	protected $sId;
 
-	/** @var string Relative path (from <ITOP>/templates/) to the "global" TWIG template which contains HTML, JS inline, JS files, CSS inline, CSS files. Should not be used too often as JS/CSS files would be duplicated making browser parsing time way longer. */
+	/**
+	 * @var string|null
+	 * @see iUIBlock::GetGlobalTemplateRelPath()
+	 */
 	protected $sGlobalTemplateRelPath;
-	/** @var string Relative path (from <ITOP>/templates/) to the HTML template */
+	/**
+	 * @var string|null
+	 * @see iUIBlock::GetHtmlTemplateRelPath()
+	 */
 	protected $sHtmlTemplateRelPath;
-	/** @var array Relative paths (from <ITOP>/templates/) to the JS templates (Live, on init., on ready) */
+	/**
+	 * @var array Relative paths (from <ITOP>/templates/) to the JS templates (Live, on init., on ready)
+	 * Key is the JS type ({@see iUIBlock::ENUM_JS_TYPE_LIVE}, ...), value is the relative path to the template
+	 * @see iUIBlock::GetJsTemplatesRelPath()
+	 */
 	protected $aJsTemplatesRelPath;
-	/** @var string Relative path (from <ITOP>/templates/) to the CSS template */
+	/**
+	 * @var string|null
+	 * @see iUIBlock::GetCssTemplateRelPath()
+	 */
 	protected $sCssTemplateRelPath;
-	/** @var array Relative paths (from <ITOP>/) to the JS files */
+	/**
+	 * @var array Relative paths (from <ITOP>/) to the external JS files to include in the page.
+	 *
+	 * **Warning**: If you need to call a JS var defined in one of this file, then this calling code MUST be in {@see static::DEFAULT_JS_ON_READY_TEMPLATE_REL_PATH}
+	 * and not in {@see static::DEFAULT_JS_TEMPLATE_REL_PATH} ! Indeed the later is output before external files loading.
+	 */
 	protected $aJsFilesRelPath = [];
-	/** @var array Relative paths (from <ITOP>/) to the CSS files */
+	/**
+	 * @var array
+	 * @see iUIBlock::GetCssFilesRelPaths()
+	 */
 	protected $aCssFilesRelPath = [];
 	/** @var array Array <KEY> => <VALUE> which will be output as HTML data-xxx attributes (eg. data-<KEY>="<VALUE>") */
 	protected $aDataAttributes = [];
@@ -179,7 +219,7 @@ abstract class UIBlock implements iUIBlock
 	/**
 	 * @inheritDoc
 	 */
-	public function GetGlobalTemplateRelPath()
+	public function GetGlobalTemplateRelPath(): ?string
 	{
 		return $this->sGlobalTemplateRelPath;
 	}
@@ -187,14 +227,16 @@ abstract class UIBlock implements iUIBlock
 	/**
 	 * @inheritDoc
 	 */
-	public function GetHtmlTemplateRelPath() {
+	public function GetHtmlTemplateRelPath(): ?string
+	{
 		return $this->sHtmlTemplateRelPath;
 	}
 
 	/**
 	 * @inheritDoc
 	 */
-	public function GetJsTemplatesRelPath(string $sType) {
+	public function GetJsTemplatesRelPath(string $sType): ?string
+	{
 		if (!in_array($sType, [self::ENUM_JS_TYPE_LIVE, self::ENUM_JS_TYPE_ON_INIT, self::ENUM_JS_TYPE_ON_READY])) {
 			throw new UIException($this, "Type of javascript $sType not supported");
 		}
@@ -206,14 +248,15 @@ abstract class UIBlock implements iUIBlock
 	 * @inheritDoc
 	 * @used-by \Combodo\iTop\Application\UI\Base\UIBlock::GetFilesUrlRecursively
 	 */
-	public function GetJsFilesRelPaths() {
+	public function GetJsFilesRelPaths(): array
+	{
 		return $this->aJsFilesRelPath;
 	}
 
 	/**
 	 * @inheritDoc
 	 */
-	public function GetCssTemplateRelPath()
+	public function GetCssTemplateRelPath(): ?string
 	{
 		return $this->sCssTemplateRelPath;
 	}
@@ -222,7 +265,7 @@ abstract class UIBlock implements iUIBlock
 	 * @inheritDoc
 	 * @used-by \Combodo\iTop\Application\UI\Base\UIBlock::GetFilesUrlRecursively
 	 */
-	public function GetCssFilesRelPaths()
+	public function GetCssFilesRelPaths(): array
 	{
 		return $this->aCssFilesRelPath;
 	}
@@ -233,7 +276,7 @@ abstract class UIBlock implements iUIBlock
 	 * @return string
 	 * @see static::BLOCK_CODE
 	 */
-	public function GetBlockCode()
+	public function GetBlockCode(): string
 	{
 		return static::BLOCK_CODE;
 	}
@@ -241,7 +284,7 @@ abstract class UIBlock implements iUIBlock
 	/**
 	 * @inheritDoc
 	 */
-	public function GetId()
+	public function GetId(): string
 	{
 		return $this->sId;
 	}
@@ -250,7 +293,7 @@ abstract class UIBlock implements iUIBlock
 	 * @inheritDoc
 	 * @return \Combodo\iTop\Application\UI\Base\iUIBlock[]
 	 */
-	public function GetSubBlocks()
+	public function GetSubBlocks(): array
 	{
 		return [];
 	}
@@ -268,7 +311,7 @@ abstract class UIBlock implements iUIBlock
 	 * @inheritDoc
 	 * @throws \Exception
 	 */
-	public function GetJsFilesUrlRecursively(bool $bAbsoluteUrl = false)
+	public function GetJsFilesUrlRecursively(bool $bAbsoluteUrl = false): array
 	{
 		return $this->GetFilesUrlRecursively(static::ENUM_BLOCK_FILES_TYPE_JS, $bAbsoluteUrl);
 	}
@@ -277,16 +320,22 @@ abstract class UIBlock implements iUIBlock
 	 * @inheritDoc
 	 * @throws \Exception
 	 */
-	public function GetCssFilesUrlRecursively(bool $bAbsoluteUrl = false)
+	public function GetCssFilesUrlRecursively(bool $bAbsoluteUrl = false): array
 	{
 		return $this->GetFilesUrlRecursively(static::ENUM_BLOCK_FILES_TYPE_CSS, $bAbsoluteUrl);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function AddHtml(string $sHTML) {
 		// By default this does nothing
 		return $this;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function GetParameters(): array {
 		return [];
 	}
@@ -344,7 +393,7 @@ abstract class UIBlock implements iUIBlock
 	 *
 	 * @return string a unique ID for the block
 	 */
-	protected function GenerateId()
+	protected function GenerateId(): string
 	{
 		$sUniqId = uniqid(static::BLOCK_CODE.'-', true);
 		$sUniqId = utils::Sanitize($sUniqId, '', utils::ENUM_SANITIZATION_FILTER_ELEMENT_IDENTIFIER);
@@ -353,7 +402,7 @@ abstract class UIBlock implements iUIBlock
 	}
 
 	/**
-	 * Return an array of the URL of the block $sFilesType and its sub blocks.
+	 * Return an array of the URL of the block's $sFilesType and its sub blocks.
 	 * URL is relative unless the $bAbsoluteUrl is set to true.
 	 *
 	 * @param string $sFileType (see static::ENUM_BLOCK_FILES_TYPE_JS, static::ENUM_BLOCK_FILES_TYPE_CSS)
@@ -362,7 +411,8 @@ abstract class UIBlock implements iUIBlock
 	 * @return array
 	 * @throws \Exception
 	 */
-	protected function GetFilesUrlRecursively(string $sFileType, bool $bAbsoluteUrl = false) {
+	protected function GetFilesUrlRecursively(string $sFileType, bool $bAbsoluteUrl = false): array
+	{
 		$aFiles = [];
 		$sFilesRelPathMethodName = 'Get'.ucfirst($sFileType).'FilesRelPaths';
 
@@ -390,7 +440,7 @@ abstract class UIBlock implements iUIBlock
 	 *
 	 * @return $this
 	 *
-	 * @uses $aAdditionalCSSClasses
+	 * @see static::$aAdditionalCSSClasses
 	 */
 	public function AddCSSClass(string $sCSSClass)
 	{
@@ -410,7 +460,7 @@ abstract class UIBlock implements iUIBlock
 	 *
 	 * @return $this
 	 *
-	 * @uses $aAdditionalCSSClasses
+	 * @see static::$aAdditionalCSSClasses
 	 */
 	public function RemoveCSSClass(string $sCSSClass)
 	{
@@ -426,7 +476,7 @@ abstract class UIBlock implements iUIBlock
 	 *
 	 * @return $this
 	 *
-	 * @uses $aAdditionalCSSClasses
+	 * @see static::$aAdditionalCSSClasses
 	 */
 	public function AddCSSClasses(array $aCSSClasses)
 	{
@@ -446,7 +496,7 @@ abstract class UIBlock implements iUIBlock
 	 *
 	 * @return $this
 	 *
-	 * @uses $aAdditionalCSSClasses
+	 * @see static::$aAdditionalCSSClasses
 	 */
 	public function SetCSSClasses(array $aCSSClasses)
 	{
@@ -459,7 +509,7 @@ abstract class UIBlock implements iUIBlock
 	/**
 	 * @return array
 	 *
-	 * @uses $aAdditionalCSSClasses
+	 * @see static::$aAdditionalCSSClasses
 	 * @see static::GetAdditionalCSSClassesAsString() for a simpler usage in the views
 	 */
 	public function GetAdditionalCSSClasses(): array
@@ -470,7 +520,7 @@ abstract class UIBlock implements iUIBlock
 	/**
 	 * @return string All additional CSS classes as a spec-separated string
 	 *
-	 * @uses static::GetAdditionalCSSClasses()
+	 * @see static::GetAdditionalCSSClasses()
 	 */
 	public function GetAdditionalCSSClassesAsString(): string
 	{
@@ -515,6 +565,7 @@ abstract class UIBlock implements iUIBlock
 
 	/**
 	 * @return array
+	 * @see static::$aDataAttributes
 	 */
 	public function GetDataAttributes(): array
 	{
@@ -525,6 +576,7 @@ abstract class UIBlock implements iUIBlock
 	 * @param array $aDataAttributes Array of data attributes in the format ['name' => 'value']
 	 *
 	 * @return $this
+	 * @see static::$aDataAttributes
 	 */
 	public function SetDataAttributes(array $aDataAttributes)
 	{
@@ -538,6 +590,7 @@ abstract class UIBlock implements iUIBlock
 	 * @param string $sValue
 	 *
 	 * @return $this
+	 * @see static::$aDataAttributes
 	 */
 	public function AddDataAttribute(string $sName, string $sValue)
 	{
@@ -548,7 +601,7 @@ abstract class UIBlock implements iUIBlock
 
 	/**
 	 * @return bool
-	 * @uses static::$aDataAttributes
+	 * @see static::$aDataAttributes
 	 */
 	public function HasDataAttributes(): bool
 	{
@@ -557,6 +610,7 @@ abstract class UIBlock implements iUIBlock
 
 	/**
 	 * @return bool
+	 * @see static::$bIsHidden
 	 */
 	public function IsHidden(): bool
 	{
@@ -564,9 +618,10 @@ abstract class UIBlock implements iUIBlock
 	}
 
 	/**
-	 * @param bool $bIsHidden Indicates if the block is hidden by default
+	 * @param bool $bIsHidden
 	 *
 	 * @return $this
+	 * @see static::$bIsHidden
 	 */
 	public function SetIsHidden(bool $bIsHidden)
 	{

sources/application/UI/Base/iUIBlock.php

@@ -23,102 +23,93 @@ namespace Combodo\iTop\Application\UI\Base;
 /**
  * Interface iUIBlock
  *
+ * UIBlocks are the foundation of the new UI system. They aim at providing reusable components with better maintenability and segreagtion.
+ * Used only in the backoffice for now.
+ *
  * @package Combodo\iTop\Application\UI
  * @author Guillaume Lajarige <guillaume.lajarige@combodo.com>
  * @internal
  * @since   3.0.0
  */
 interface iUIBlock {
-	public const ENUM_JS_TYPE_ON_INIT = "js";
+	/** @var string "Live" or "inline" JS is to be executed immediately when the code is parsed */
 	public const ENUM_JS_TYPE_LIVE = "live.js";
+	/** @var string "On init" JS is to be executed immediately when the DOM is ready */
+	public const ENUM_JS_TYPE_ON_INIT = "js";
+	/** @var string "On ready" JS is to be executed slightly after the "on init" JSs when the DOM is ready */
 	public const ENUM_JS_TYPE_ON_READY = "ready.js";
-	/**
-	 * Return the relative path (from <ITOP>/templates/) of the global template (HTML, JS, CSS) to use or null if it's not provided. Should not be used to often as JS/CSS files would be duplicated making the browser parsing time way longer.
-	 *
-	 * @return string|null
-	 */
-	public function GetGlobalTemplateRelPath();
+
+	/** @var string */
+	public const ENUM_BLOCK_FILES_TYPE_JS = 'js';
+	/** @var string */
+	public const ENUM_BLOCK_FILES_TYPE_CSS = 'css';
+	/** @var string */
+	public const ENUM_BLOCK_FILES_TYPE_FILES = 'files';
+	/** @var string */
+	public const ENUM_BLOCK_FILES_TYPE_TEMPLATE = 'template';
 
 	/**
-	 * Return the relative path (from <ITOP>/templates/) of the HTML template to use or null if no HTML to render
+	 * Should not be used too often as JS/CSS files would be duplicated making the browser parsing time way longer.
 	 *
-	 * @return string|null
+	 * @return string|null The relative path (from <ITOP>/templates/) of the "global" template (which contains HTML, JS inline, JS files, CSS inline, CSS files) to use or null if it's not provided.
 	 */
-	public function GetHtmlTemplateRelPath();
+	public function GetGlobalTemplateRelPath(): ?string;
 
 	/**
-	 * Return the relative path (from <ITOP>/templates/) of the JS template to use or null if there is no inline JS to render
-	 *
-	 * @param string $sType javascript type only ENUM_JS_TYPE_ON_INIT / ENUM_JS_TYPE_ON_READY / ENUM_JS_TYPE_LIVE
-	 *
-	 * @return string|null
+	 * @return string|null The relative path (from <ITOP>/templates/) of the HTML template to use or null if no HTML to render
 	 */
-	public function GetJsTemplatesRelPath(string $sType) ;
+	public function GetHtmlTemplateRelPath(): ?string;
 
 	/**
-	 * Return an array of the relative paths (from <ITOP>/) of the JS files to use for the block itself
+	 * @param string $sType Javascript type {@see static::ENUM_JS_TYPE_LIVE and others}
 	 *
-	 * @return array
+	 * @return string|null The relative path (from <ITOP>/templates/) of the JS template (for $sType) to use or null if there is no inline JS (for $sType) to render
 	 */
-	public function GetJsFilesRelPaths();
+	public function GetJsTemplatesRelPath(string $sType): ?string;
 
 	/**
-	 * Return the relative path (from <ITOP>/templates/) of the CSS template to use or null if there is no inline CSS to render
-	 *
-	 * @return string|null
+	 * @return array Array of the relative paths (from <ITOP>/) of the JS files to use for the block itself
 	 */
-	public function GetCssTemplateRelPath();
+	public function GetJsFilesRelPaths(): array;
 
 	/**
-	 * Return an array of the relative paths (from <ITOP>/) of the CSS files to use for the block itself
-	 *
-	 * @return array
+	 * @return string|null The relative path (from <ITOP>/templates/) of the CSS template to use or null if there is no inline CSS to render
 	 */
-	public function GetCssFilesRelPaths();
+	public function GetCssTemplateRelPath(): ?string;
 
 	/**
-	 * Return the ID of the block
-	 *
-	 * @return string
+	 * @return array Array of the relative paths (from <ITOP>/) of the CSS files to use for the block itself
 	 */
-	public function GetId();
+	public function GetCssFilesRelPaths(): array;
 
 	/**
-	 * Return an array iUIBlock embedded in this iUIBlock
-	 * Must be an associative array (<BLOCK_ID> => <BLOCK_INSTANCE>)
-	 *
-	 * @return \Combodo\iTop\Application\UI\Base\iUIBlock[]
+	 * @return string ID of the block
 	 */
-	public function GetSubBlocks();
+	public function GetId(): string;
 
 	/**
-	 * Return an array of iUIBlock to add at the end of the page
-	 * Must be an associative array (<BLOCK_ID> => <BLOCK_INSTANCE>)
-	 *
-	 * @return \Combodo\iTop\Application\UI\Base\iUIBlock[]
+	 * @return \Combodo\iTop\Application\UI\Base\iUIBlock[] Array iUIBlock embedded in this iUIBlock. Must be an associative array (<BLOCK_ID> => <BLOCK_INSTANCE>)
+	 */
+	public function GetSubBlocks(): array;
+
+	/**
+	 * @return \Combodo\iTop\Application\UI\Base\iUIBlock[] Array of iUIBlock to add at the end of the page. Must be an associative array (<BLOCK_ID> => <BLOCK_INSTANCE>)
 	 */
 	public function GetDeferredBlocks(): array;
 
 	/**
-	 * Return an array of the JS files URL necessary for the block and all its sub blocks.
-	 * URLs are relative unless the $bAbsolutePath is set to true.
+	 * @param bool $bAbsoluteUrl If set to true, URLs will be absolute, otherwise they will be relative to the app. root
 	 *
-	 * @param bool $bAbsoluteUrl
-	 *
-	 * @return string[]
+	 * @return string[] Array of the JS files URL necessary for the block and all its sub blocks.
 	 */
-	public function GetJsFilesUrlRecursively(bool $bAbsoluteUrl = false);
+	public function GetJsFilesUrlRecursively(bool $bAbsoluteUrl = false): array;
 
 	/**
-	 * Return an array of the CSS files URL necessary for the block and all its sub blocks.
-	 * URLs are relative unless the $bAbsolutePath is set to true.
+	 * @param bool $bAbsoluteUrl If set to true, URLs will be absolute, otherwise they will be relative to the app. root
 	 *
-	 * @param bool $bAbsoluteUrl
-	 *
-	 * @return string[]
-	 * @throws \Exception
+	 * @return string[] Array of the CSS files URL necessary for the block and all its sub blocks.
 	 */
-	public function GetCssFilesUrlRecursively(bool $bAbsoluteUrl = false);
+	public function GetCssFilesUrlRecursively(bool $bAbsoluteUrl = false): array;
 
 	/**
 	 * Add HTML code to the current block
@@ -130,9 +121,7 @@ interface iUIBlock {
 	public function AddHtml(string $sHTML);
 
 	/**
-	 * Return block specific parameters
-	 *
-	 * @return array
+	 * @return array Block's specific parameters
 	 */
 	public function GetParameters(): array;