From b37e74b407c9baf76b6ae30014b132272ae8fdb2 Mon Sep 17 00:00:00 2001 From: Eric Espie Date: Wed, 28 Dec 2022 09:51:46 +0100 Subject: [PATCH 1/3] :memo: Change packages for auto-documentation --- application/applicationextension.inc.php | 40 ++++++++++++------------ core/restservices.class.inc.php | 4 +-- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/application/applicationextension.inc.php b/application/applicationextension.inc.php index e3f929c21..912485191 100644 --- a/application/applicationextension.inc.php +++ b/application/applicationextension.inc.php @@ -227,7 +227,7 @@ interface iLoginUIExtension extends iLoginExtension /** * @api - * @package Extensibility + * @package PreferencesExtensibilityAPI * @since 2.7.0 */ interface iPreferencesExtension @@ -251,7 +251,7 @@ interface iPreferencesExtension * Extend this class instead of implementing iPreferencesExtension if you don't need to overload all methods * * @api - * @package Extensibility + * @package PreferencesExtensibilityAPI * @since 2.7.0 */ abstract class AbstractPreferencesExtension implements iPreferencesExtension @@ -297,7 +297,7 @@ abstract class AbstractPreferencesExtension implements iPreferencesExtension * A recommended pattern is to cache data by the mean of static members. * * @api - * @package Extensibility + * @package UIExtensibilityAPI */ interface iApplicationUIExtension { @@ -438,7 +438,7 @@ interface iApplicationUIExtension * Extend this class instead of implementing iApplicationUIExtension if you don't need to overload * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.7.0 */ abstract class AbstractApplicationUIExtension implements iApplicationUIExtension @@ -512,7 +512,7 @@ abstract class AbstractApplicationUIExtension implements iApplicationUIExtension * or through the GUI. * * @api - * @package Extensibility + * @package ORMExtensibilityAPI */ interface iApplicationObjectExtension { @@ -606,7 +606,7 @@ interface iApplicationObjectExtension * Extend this class instead of iApplicationObjectExtension if you don't need to overload all methods * * @api - * @package Extensibility + * @package ORMExtensibilityAPI * @since 2.7.0 */ abstract class AbstractApplicationObjectExtension implements iApplicationObjectExtension @@ -666,7 +666,7 @@ abstract class AbstractApplicationObjectExtension implements iApplicationObjectE * by the application, as long as the class definition is included somewhere in the code * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ interface iPopupMenuExtension @@ -765,7 +765,7 @@ interface iPopupMenuExtension * Base class for the various types of custom menus * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ abstract class ApplicationPopupMenuItem @@ -862,7 +862,7 @@ abstract class ApplicationPopupMenuItem * Class for adding an item into a popup menu that browses to the given URL * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ class URLPopupMenuItem extends ApplicationPopupMenuItem @@ -898,7 +898,7 @@ class URLPopupMenuItem extends ApplicationPopupMenuItem * Class for adding an item into a popup menu that triggers some Javascript code * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ class JSPopupMenuItem extends ApplicationPopupMenuItem @@ -950,7 +950,7 @@ class JSPopupMenuItem extends ApplicationPopupMenuItem * will automatically reduce several consecutive separators to just one * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ class SeparatorPopupMenuItem extends ApplicationPopupMenuItem @@ -976,7 +976,7 @@ class SeparatorPopupMenuItem extends ApplicationPopupMenuItem * Class for adding an item as a button that browses to the given URL * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ class URLButtonItem extends URLPopupMenuItem @@ -988,7 +988,7 @@ class URLButtonItem extends URLPopupMenuItem * Class for adding an item as a button that runs some JS code * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ class JSButtonItem extends JSPopupMenuItem @@ -1012,7 +1012,7 @@ class JSButtonItem extends JSPopupMenuItem * the specified place and can use the passed iTopWebPage object to add javascript or CSS definitions * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.0 */ interface iPageUIExtension @@ -1049,7 +1049,7 @@ interface iPageUIExtension * Extend this class instead of iPageUIExtension if you don't need to overload all methods * * @api - * @package Extensibility + * @package UIExtensibilityAPI * @since 2.7.0 */ abstract class AbstractPageUIExtension implements iPageUIExtension @@ -1084,7 +1084,7 @@ abstract class AbstractPageUIExtension implements iPageUIExtension * Implement this interface to add content to any enhanced portal page * * @api - * @package Extensibility + * @package PortalExtensibilityAPI * * @since 2.4.0 interface creation * @since 2.7.0 change method signatures due to Silex to Symfony migration @@ -1163,7 +1163,7 @@ interface iPortalUIExtension * Extend this class instead of iPortalUIExtension if you don't need to overload all methods * * @api - * @package Extensibility + * @package PortalExtensibilityAPI * @since 2.4.0 */ abstract class AbstractPortalUIExtension implements iPortalUIExtension @@ -1229,7 +1229,7 @@ abstract class AbstractPortalUIExtension implements iPortalUIExtension * Implement this interface to add new operations to the REST/JSON web service * * @api - * @package Extensibility + * @package RESTExtensibilityAPI * @since 2.0.1 */ interface iRestServiceProvider @@ -1259,7 +1259,7 @@ interface iRestServiceProvider * Minimal REST response structure. Derive this structure to add response data and error codes. * * @api - * @package Extensibility + * @package RESTExtensibilityAPI * @since 2.0.1 */ class RestResult @@ -1329,7 +1329,7 @@ class RestResult * Helpers for implementing REST services * * @api - * @package Extensibility + * @package RESTExtensibilityAPI */ class RestUtils { diff --git a/core/restservices.class.inc.php b/core/restservices.class.inc.php index bf9608af4..dbcc29e6e 100644 --- a/core/restservices.class.inc.php +++ b/core/restservices.class.inc.php @@ -129,7 +129,7 @@ class ObjectResult /** * REST response for services managing objects. Derive this structure to add information and/or constants * - * @package Extensibility + * @package RESTExtensibilityAPI * @package REST Services * @api */ @@ -206,7 +206,7 @@ class RestResultWithRelations extends RestResultWithObjects /** * Deletion result codes for a target object (either deleted or updated) * - * @package Extensibility + * @package RESTExtensibilityAPI * @api * @since 2.0.1 */ From 92a36dcfddd1d7122856cdb40cbc02d5bf6404fc Mon Sep 17 00:00:00 2001 From: Eric Espie Date: Thu, 29 Dec 2022 12:24:56 +0100 Subject: [PATCH 2/3] :memo: Change packages for auto-documentation --- application/applicationextension.inc.php | 86 +++++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/application/applicationextension.inc.php b/application/applicationextension.inc.php index 912485191..833ecb6e0 100644 --- a/application/applicationextension.inc.php +++ b/application/applicationextension.inc.php @@ -29,9 +29,9 @@ require_once(APPROOT.'application/newsroomprovider.class.inc.php'); * You may implement such interfaces in a module file (e.g. main.mymodule.php) * * @api + * @package LoginExtensibilityAPI * @copyright Copyright (C) 2010-2012 Combodo SARL * @license http://opensource.org/licenses/AGPL-3.0 - * @package Extensibility * @since 2.7.0 */ interface iLoginExtension @@ -39,12 +39,16 @@ interface iLoginExtension /** * Return the list of supported login modes for this plugin * + * @api + * * @return array of supported login modes */ public function ListSupportedLoginModes(); } /** + * @api + * @package LoginExtensibilityAPI * @since 2.7.0 */ interface iLoginFSMExtension extends iLoginExtension @@ -56,6 +60,7 @@ interface iLoginFSMExtension extends iLoginExtension * if LoginWebPage::LOGIN_FSM_RETURN_OK is returned then the login is OK and terminated * if LoginWebPage::LOGIN_FSM_RETURN_IGNORE is returned then the FSM will proceed to next plugin or state * + * @api * @param string $sLoginState (see LoginWebPage::LOGIN_STATE_...) * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * @@ -65,6 +70,8 @@ interface iLoginFSMExtension extends iLoginExtension } /** + * @api + * @package LoginExtensibilityAPI * @since 2.7.0 */ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension @@ -111,6 +118,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension /** * Initialization * + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -124,6 +132,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension * Detect login mode explicitly without respecting configured order (legacy mode) * In most case do nothing here * + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -140,6 +149,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension * 1 - display login form * 2 - read the values posted by the user * + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -153,6 +163,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension * Control the validity of the data provided by the user * Automatic user provisioning can be done here * + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -163,6 +174,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension } /** + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -173,6 +185,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension } /** + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -183,6 +196,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension } /** + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -193,6 +207,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension } /** + * @api * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...) * * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE @@ -204,22 +219,28 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension } /** + * @api + * @package LoginExtensibilityAPI * @since 2.7.0 */ interface iLogoutExtension extends iLoginExtension { /** * Execute all actions to log out properly + * @api */ public function LogoutAction(); } /** + * @api + * @package UIExtensibilityAPI * @since 2.7.0 */ interface iLoginUIExtension extends iLoginExtension { /** + * @api * @return LoginTwigContext */ public function GetTwigContext(); @@ -233,12 +254,14 @@ interface iLoginUIExtension extends iLoginExtension interface iPreferencesExtension { /** + * @api * @param \WebPage $oPage * */ public function DisplayPreferences(WebPage $oPage); /** + * @api * @param \WebPage $oPage * @param string $sOperation * @@ -319,6 +342,7 @@ interface iApplicationUIExtension * } * * + * @api * @param DBObject $oObject The object being displayed * @param WebPage $oPage The output context * @param boolean $bEditMode True if the edition form is being displayed @@ -332,6 +356,7 @@ interface iApplicationUIExtension * * The method is called rigth after all the tabs have been displayed * + * @api * @param DBObject $oObject The object being displayed * @param WebPage $oPage The output context * @param boolean $bEditMode True if the edition form is being displayed @@ -346,6 +371,7 @@ interface iApplicationUIExtension * The method is called after the changes from the standard form have been * taken into account, and before saving the changes into the database. * + * @api * @param DBObject $oObject The object being edited * @param string $sFormPrefix Prefix given to the HTML form inputs * @@ -360,6 +386,7 @@ interface iApplicationUIExtension * javascript into the edition form, and if that code requires to store temporary data * (this is the case when a file must be uploaded). * + * @api * @param string $sTempId Unique temporary identifier made of session_id and transaction_id. It identifies the object in a unique way. * * @return void @@ -371,6 +398,7 @@ interface iApplicationUIExtension * * Sorry, the verb has been reserved. You must implement it, but it is not called as of now. * + * @api * @param DBObject $oObject The object being displayed * * @return string[] desc @@ -382,6 +410,7 @@ interface iApplicationUIExtension * * Sorry, the verb has been reserved. You must implement it, but it is not called as of now. * + * @api * @param DBObject $oObject The object being displayed * * @return string Path of the icon, relative to the modules directory. @@ -401,6 +430,7 @@ interface iApplicationUIExtension * * HILIGHT_CLASS_OK * * HILIGHT_CLASS_NONE * + * @api * @param DBObject $oObject The object being displayed * * @return integer The value representing the mood of the object @@ -427,6 +457,7 @@ interface iApplicationUIExtension * * See also iPopupMenuExtension for greater flexibility * + * @api * @param DBObjectSet $oSet A set of persistent objects (DBObject) * * @return string[string] @@ -525,6 +556,7 @@ interface iApplicationObjectExtension * If the extension returns false, then the framework will perform the usual evaluation. * Otherwise, the answer is definitively "yes, the object has changed". * + * @api * @param \cmdbAbstractObject $oObject The target object * * @return boolean True if something has changed for the target object @@ -537,6 +569,7 @@ interface iApplicationObjectExtension * The GUI calls this verb and reports any issue. * Anyhow, this API can be called in other contexts such as the CSV import tool. * + * @api * @param \cmdbAbstractObject $oObject The target object * * @return string[] A list of errors message. An error message is made of one line and it can be displayed to the end-user. @@ -550,6 +583,7 @@ interface iApplicationObjectExtension * * Please not that it is not possible to cascade deletion by this mean: only stopper issues can be handled. * + * @api * @param \cmdbAbstractObject $oObject The target object * * @return string[] A list of errors message. An error message is made of one line and it can be displayed to the end-user. @@ -565,6 +599,7 @@ interface iApplicationObjectExtension * * {@see DBObject::ListPreviousValuesForUpdatedAttributes()} : list of changed attributes and their values before the change * * {@see DBObject::Get()} : for a given attribute the new value that was persisted * + * @api * @param \cmdbAbstractObject $oObject The target object * @param CMDBChange|null $oChange A change context. Since 2.0 it is fine to ignore it, as the framework does maintain this information * once for all the changes made within the current page @@ -580,6 +615,7 @@ interface iApplicationObjectExtension * * The method is called right after the object has been written to the database. * + * @api * @param \cmdbAbstractObject $oObject The target object * @param CMDBChange|null $oChange A change context. Since 2.0 it is fine to ignore it, as the framework does maintain this information * once for all the changes made within the current page @@ -593,6 +629,7 @@ interface iApplicationObjectExtension * * The method is called right before the object will be deleted from the database. * + * @api * @param \cmdbAbstractObject $oObject The target object * @param CMDBChange|null $oChange A change context. Since 2.0 it is fine to ignore it, as the framework does maintain this information * once for all the changes made within the current page @@ -675,18 +712,21 @@ interface iPopupMenuExtension * Insert an item into the Actions menu of a list * * $param is a DBObjectSet containing the list of objects + * @api */ const MENU_OBJLIST_ACTIONS = 1; /** * Insert an item into the Toolkit menu of a list * * $param is a DBObjectSet containing the list of objects + * @api */ const MENU_OBJLIST_TOOLKIT = 2; /** * Insert an item into the Actions menu on an object details page * * $param is a DBObject instance: the object currently displayed + * @api */ const MENU_OBJDETAILS_ACTIONS = 3; /** @@ -696,12 +736,14 @@ interface iPopupMenuExtension * is being displayed. * * $param is a Dashboard instance: the dashboard currently displayed + * @api */ const MENU_DASHBOARD_ACTIONS = 4; /** * Insert an item into the User menu (upper right corner) * * $param is null + * @api */ const MENU_USER_ACTIONS = 5; /** @@ -709,6 +751,7 @@ interface iPopupMenuExtension * * $param is an array('portal_id' => $sPortalId, 'object' => $oObject) containing the portal id and a DBObject instance (the object on * the current line) + * @api */ const PORTAL_OBJLISTITEM_ACTIONS = 7; /** @@ -716,6 +759,7 @@ interface iPopupMenuExtension * * $param is an array('portal_id' => $sPortalId, 'object' => $oObject) containing the portal id and a DBObject instance (the object * currently displayed) + * @api */ const PORTAL_OBJDETAILS_ACTIONS = 8; @@ -753,6 +797,7 @@ interface iPopupMenuExtension * This method is called by the framework for each menu. * The items will be inserted in the menu in the order of the returned array. * + * @api * @param int $iMenuId The identifier of the type of menu, as listed by the constants MENU_xxx * @param mixed $param Depends on $iMenuId, see the constants defined above * @@ -826,6 +871,7 @@ abstract class ApplicationPopupMenuItem } /** + * @api * @param $aCssClasses */ public function SetCssClasses($aCssClasses) @@ -836,6 +882,7 @@ abstract class ApplicationPopupMenuItem /** * Adds a CSS class to the CSS classes that will be put on the menu item * + * @api * @param $sCssClass */ public function AddCssClass($sCssClass) @@ -875,6 +922,7 @@ class URLPopupMenuItem extends ApplicationPopupMenuItem /** * Constructor * + * @api * @param string $sUID The unique identifier of this menu in iTop... make sure you pass something unique enough * @param string $sLabel The display label of the menu (must be localized) * @param string $sURL If the menu is an hyperlink, provide the absolute hyperlink here @@ -959,6 +1007,7 @@ class SeparatorPopupMenuItem extends ApplicationPopupMenuItem /** * Constructor + * @api */ public function __construct() { @@ -1020,6 +1069,7 @@ interface iPageUIExtension /** * Add content to the North pane * + * @api * @param iTopWebPage $oPage The page to insert stuff into. * * @return string The HTML content to add into the page @@ -1029,6 +1079,7 @@ interface iPageUIExtension /** * Add content to the South pane * + * @api * @param iTopWebPage $oPage The page to insert stuff into. * * @return string The HTML content to add into the page @@ -1038,6 +1089,7 @@ interface iPageUIExtension /** * Add content to the "admin banner" * + * @api * @param iTopWebPage $oPage The page to insert stuff into. * * @return string The HTML content to add into the page @@ -1098,6 +1150,7 @@ interface iPortalUIExtension /** * Returns an array of CSS file urls * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return array @@ -1107,6 +1160,7 @@ interface iPortalUIExtension /** * Returns inline (raw) CSS * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return string @@ -1116,6 +1170,7 @@ interface iPortalUIExtension /** * Returns an array of JS file urls * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return array @@ -1125,6 +1180,7 @@ interface iPortalUIExtension /** * Returns raw JS code * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return string @@ -1134,6 +1190,7 @@ interface iPortalUIExtension /** * Returns raw HTML code to put at the end of the tag * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return string @@ -1143,6 +1200,7 @@ interface iPortalUIExtension /** * Returns raw HTML code to put at the end of the #main-wrapper element * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return string @@ -1152,6 +1210,7 @@ interface iPortalUIExtension /** * Returns raw HTML code to put at the end of the #topbar and #sidebar elements * + * @api * @param \Symfony\Component\DependencyInjection\Container $oContainer * * @return string @@ -1237,6 +1296,7 @@ interface iRestServiceProvider /** * Enumerate services delivered by this class * + * @api * @param string $sVersion The version (e.g. 1.0) supported by the services * * @return array An array of hash 'verb' => verb, 'description' => description @@ -1246,6 +1306,7 @@ interface iRestServiceProvider /** * Enumerate services delivered by this class * + * @api * @param string $sVersion The version (e.g. 1.0) supported by the services * @param string $sVerb * @param array $aParams @@ -1266,62 +1327,83 @@ class RestResult { /** * Result: no issue has been encountered + * @api */ const OK = 0; /** * Result: missing/wrong credentials or the user does not have enough rights to perform the requested operation + * @api */ const UNAUTHORIZED = 1; /** * Result: the parameter 'version' is missing + * @api */ const MISSING_VERSION = 2; /** * Result: the parameter 'json_data' is missing + * @api */ const MISSING_JSON = 3; /** * Result: the input structure is not a valid JSON string + * @api */ const INVALID_JSON = 4; /** * Result: the parameter 'auth_user' is missing, authentication aborted + * @api */ const MISSING_AUTH_USER = 5; /** * Result: the parameter 'auth_pwd' is missing, authentication aborted + * @api */ const MISSING_AUTH_PWD = 6; /** * Result: no operation is available for the specified version + * @api */ const UNSUPPORTED_VERSION = 10; /** * Result: the requested operation is not valid for the specified version + * @api */ const UNKNOWN_OPERATION = 11; /** * Result: the requested operation cannot be performed because it can cause data (integrity) loss + * @api */ const UNSAFE = 12; /** * Result: the request page number is not valid. It must be an integer greater than 0 + * @api */ const INVALID_PAGE = 13; /** * Result: the operation could not be performed, see the message for troubleshooting + * @api */ const INTERNAL_ERROR = 100; /** * Default constructor - ok! + * @api */ public function __construct() { $this->code = RestResult::OK; } + /** + * @var int + * @api + */ public $code; + /** + * @var string + * @api + */ public $message; } @@ -1478,6 +1560,7 @@ class RestUtils /** * Read and interpret object search criteria from a Rest/Json structure * + * @api * @param string $sClass Name of the class * @param StdClass $oCriteria Hash of attribute code => value (can be a substructure or a scalar, depending on the nature of the * attriute) @@ -1587,6 +1670,7 @@ class RestUtils /** * Search objects from a polymorph search specification (Rest/Json) * + * @api * @param string $sClass Name of the class * @param mixed $key Either search criteria (substructure), or an object or an OQL string. * @param int $iLimit The limit of results to return From 88d9a29599c6f69a73cd272cbbc523f8fcf70a08 Mon Sep 17 00:00:00 2001 From: Eric Espie Date: Thu, 29 Dec 2022 12:38:31 +0100 Subject: [PATCH 3/3] :memo: Change packages for auto-documentation --- core/restservices.class.inc.php | 88 ++++++++++++++++--- .../UI/Base/AbstractUIBlockFactory.php | 4 +- .../Component/Alert/AlertUIBlockFactory.php | 10 ++- .../Component/Button/ButtonUIBlockFactory.php | 5 +- .../ButtonGroup/ButtonGroupUIBlockFactory.php | 5 +- .../CollapsibleSectionUIBlockFactory.php | 5 +- .../DataTable/DataTableUIBlockFactory.php | 14 ++- .../Component/Field/FieldUIBlockFactory.php | 39 +++++++- .../FieldBadge/FieldBadgeUIBlockFactory.php | 2 +- .../FieldSet/FieldSetUIBlockFactory.php | 5 +- .../Component/Form/FormUIBlockFactory.php | 3 +- .../FileSelect/FileSelectUIBlockFactory.php | 5 +- .../Component/Input/InputUIBlockFactory.php | 31 ++++++- .../Select/SelectOptionUIBlockFactory.php | 13 ++- .../Input/Select/SelectUIBlockFactory.php | 6 +- .../Component/Panel/PanelUIBlockFactory.php | 13 ++- .../Spinner/SpinnerUIBlockFactory.php | 10 ++- .../Component/Title/TitleUIBlockFactory.php | 37 +++++++- .../ToolbarSeparatorUIBlockFactory.php | 5 +- .../ToolbarSpacerUIBlockFactory.php | 5 +- .../Toolbar/ToolbarUIBlockFactory.php | 24 ++++- .../Column/ColumnUIBlockFactory.php | 15 +++- .../MultiColumn/MultiColumnUIBlockFactory.php | 8 +- .../Layout/UIContentBlockUIBlockFactory.php | 6 +- 24 files changed, 305 insertions(+), 53 deletions(-) diff --git a/core/restservices.class.inc.php b/core/restservices.class.inc.php index 92b25e75e..046ccdd4a 100644 --- a/core/restservices.class.inc.php +++ b/core/restservices.class.inc.php @@ -30,18 +30,40 @@ /** * Element of the response formed by RestResultWithObjects * - * @package REST Services + * @package RESTExtensibilityAPI + * @api */ class ObjectResult { + /** + * @var int + * @api + */ public $code; + /** + * @var string + * @api + */ public $message; + /** + * @var mixed|null + * @api + */ public $class; + /** + * @var mixed|null + * @api + */ public $key; + /** + * @var array + * @api + */ public $fields; /** * Default constructor + * @api */ public function __construct($sClass = null, $iId = null) { @@ -54,11 +76,17 @@ class ObjectResult /** * Helper to make an output value for a given attribute - * + * + * @api * @param DBObject $oObject The object being reported * @param string $sAttCode The attribute code (must be valid) * @param boolean $bExtendedOutput Output all of the link set attributes ? + * * @return string A scalar representation of the value + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MySQLException */ protected function MakeResultValue(DBObject $oObject, $sAttCode, $bExtendedOutput = false) { @@ -112,11 +140,17 @@ class ObjectResult /** * Report the value for the given object attribute - * + * + * @api * @param DBObject $oObject The object being reported * @param string $sAttCode The attribute code (must be valid) * @param boolean $bExtendedOutput Output all of the link set attributes ? + * * @return void + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MySQLException */ public function AddField(DBObject $oObject, $sAttCode, $bExtendedOutput = false) { @@ -129,8 +163,7 @@ class ObjectResult /** * REST response for services managing objects. Derive this structure to add information and/or constants * - * @package RESTExtensibilityAPI - * @package REST Services + * @package RESTExtensibilityAPI * @api */ class RestResultWithObjects extends RestResult @@ -139,13 +172,19 @@ class RestResultWithObjects extends RestResult /** * Report the given object - * - * @param int An error code (RestResult::OK is no issue has been found) + * + * @api + * @param $iCode * @param string $sMessage Description of the error if any, an empty string otherwise * @param DBObject $oObject The object being reported - * @param array $aFieldSpec An array of class => attribute codes (Cf. RestUtils::GetFieldList). List of the attributes to be reported. + * @param null $aFieldSpec An array of class => attribute codes (Cf. RestUtils::GetFieldList). List of the attributes to be reported. * @param boolean $bExtendedOutput Output all of the link set attributes ? + * * @return void + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MySQLException */ public function AddObject($iCode, $sMessage, $oObject, $aFieldSpec = null, $bExtendedOutput = false) { @@ -183,16 +222,30 @@ class RestResultWithObjects extends RestResult } } +/** + * @package RESTExtensibilityAPI + * @api + */ class RestResultWithRelations extends RestResultWithObjects { public $relations; - + + /** + * @api + */ public function __construct() { parent::__construct(); $this->relations = array(); } - + + /** + * @param $sSrcKey + * @param $sDestKey + * + * @return void + * @api + */ public function AddRelation($sSrcKey, $sDestKey) { if (!array_key_exists($sSrcKey, $this->relations)) @@ -214,30 +267,37 @@ class RestDelete { /** * Result: Object deleted as per the initial request + * @api */ const OK = 0; /** - * Result: general issue (user rights or ... ?) + * Result: general issue (user rights or ... ?) + * @api */ const ISSUE = 1; /** - * Result: Must be deleted to preserve database integrity + * Result: Must be deleted to preserve database integrity + * @api */ const AUTO_DELETE = 2; /** - * Result: Must be deleted to preserve database integrity, but that is NOT possible + * Result: Must be deleted to preserve database integrity, but that is NOT possible + * @api */ const AUTO_DELETE_ISSUE = 3; /** - * Result: Must be deleted to preserve database integrity, but this must be requested explicitely + * Result: Must be deleted to preserve database integrity, but this must be requested explicitly + * @api */ const REQUEST_EXPLICITELY = 4; /** * Result: Must be updated to preserve database integrity + * @api */ const AUTO_UPDATE = 5; /** * Result: Must be updated to preserve database integrity, but that is NOT possible + * @api */ const AUTO_UPDATE_ISSUE = 6; } diff --git a/sources/application/UI/Base/AbstractUIBlockFactory.php b/sources/application/UI/Base/AbstractUIBlockFactory.php index 3f7462896..4d5ecaa1c 100644 --- a/sources/application/UI/Base/AbstractUIBlockFactory.php +++ b/sources/application/UI/Base/AbstractUIBlockFactory.php @@ -11,7 +11,7 @@ namespace Combodo\iTop\Application\UI\Base; /** * Class AbstractUIBlockFactory * - * @package Combodo\iTop\Application\UI\Base + * @package UIBlockExtensibilityAPI * @author Eric Espie * @since 3.0.0 * @api @@ -19,11 +19,13 @@ namespace Combodo\iTop\Application\UI\Base; abstract class AbstractUIBlockFactory implements iUIBlockFactory { /** + * @api * @var string * @see static::GetTwigTagName() */ public const TWIG_TAG_NAME = 'UIBlock'; /** + * @api * @var string * @see static::GetUIBlockClassName() */ diff --git a/sources/application/UI/Base/Component/Alert/AlertUIBlockFactory.php b/sources/application/UI/Base/Component/Alert/AlertUIBlockFactory.php index 8fd953c51..20060bf9a 100644 --- a/sources/application/UI/Base/Component/Alert/AlertUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Alert/AlertUIBlockFactory.php @@ -25,7 +25,7 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class AlertUIBlockFactory * * @author Guillaume Lajarige - * @package Combodo\iTop\Application\UI\Base\Component\Alert + * @package UIBlockExtensibilityAPI * @since 3.0.0 * @api * @@ -41,6 +41,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make a basis Alert component * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block @@ -55,6 +56,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component for informational messages * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block @@ -70,6 +72,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component for successful messages * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId @@ -84,6 +87,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component for warning messages * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block @@ -98,6 +102,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component for danger messages * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block @@ -112,6 +117,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component for failure messages * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block @@ -126,6 +132,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component with primary color scheme * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block @@ -140,6 +147,7 @@ class AlertUIBlockFactory extends AbstractUIBlockFactory /** * Make an Alert component with secondary color scheme * + * @api * @param string $sTitle Title of the alert * @param string $sContent The raw HTML content, must be already sanitized * @param string|null $sId id of the html block diff --git a/sources/application/UI/Base/Component/Button/ButtonUIBlockFactory.php b/sources/application/UI/Base/Component/Button/ButtonUIBlockFactory.php index 0b9d5b875..5b4979395 100644 --- a/sources/application/UI/Base/Component/Button/ButtonUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Button/ButtonUIBlockFactory.php @@ -27,9 +27,9 @@ use utils; * Class ButtonUIBlockFactory * * @author Guillaume Lajarige - * @package Combodo\iTop\Application\UI\Base\Component\Button - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 * * @link /test/VisualTest/Backoffice/RenderAllUiBlocks.php#title-buttons to see live examples */ @@ -47,6 +47,7 @@ class ButtonUIBlockFactory extends AbstractUIBlockFactory /** * Make a basis Button component for any purpose * + * @api * @param string $sLabel * @param string|null $sName See {@link Button::$sName} * @param string|null $sId diff --git a/sources/application/UI/Base/Component/ButtonGroup/ButtonGroupUIBlockFactory.php b/sources/application/UI/Base/Component/ButtonGroup/ButtonGroupUIBlockFactory.php index f9b6c7786..3de2e60e9 100644 --- a/sources/application/UI/Base/Component/ButtonGroup/ButtonGroupUIBlockFactory.php +++ b/sources/application/UI/Base/Component/ButtonGroup/ButtonGroupUIBlockFactory.php @@ -15,9 +15,9 @@ use Combodo\iTop\Application\UI\Base\Component\PopoverMenu\PopoverMenu; * Class ButtonGroupUIBlockFactory * * @author Guillaume Lajarige - * @package Combodo\iTop\Application\UI\Base\Component\Button - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 */ class ButtonGroupUIBlockFactory extends AbstractUIBlockFactory { @@ -29,6 +29,7 @@ class ButtonGroupUIBlockFactory extends AbstractUIBlockFactory /** * Make a button that has a primary action ($oButton) but also an options menu ($oMenu) on the side * + * @api * @param \Combodo\iTop\Application\UI\Base\Component\Button\Button $oButton * @param \Combodo\iTop\Application\UI\Base\Component\PopoverMenu\PopoverMenu $oMenu * diff --git a/sources/application/UI/Base/Component/CollapsibleSection/CollapsibleSectionUIBlockFactory.php b/sources/application/UI/Base/Component/CollapsibleSection/CollapsibleSectionUIBlockFactory.php index 6ff9172a9..154830464 100644 --- a/sources/application/UI/Base/Component/CollapsibleSection/CollapsibleSectionUIBlockFactory.php +++ b/sources/application/UI/Base/Component/CollapsibleSection/CollapsibleSectionUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class CollapsibleSectionUIBlockFactory * * @author Pierre Goiffon - * @package Combodo\iTop\Application\UI\Base\Component\CollapsibleSection - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 */ class CollapsibleSectionUIBlockFactory extends AbstractUIBlockFactory { @@ -26,6 +26,7 @@ class CollapsibleSectionUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = CollapsibleSection::class; /** + * @api * @param string $sTitle * @param string|null $sId * diff --git a/sources/application/UI/Base/Component/DataTable/DataTableUIBlockFactory.php b/sources/application/UI/Base/Component/DataTable/DataTableUIBlockFactory.php index 8b728366b..8e815ac86 100644 --- a/sources/application/UI/Base/Component/DataTable/DataTableUIBlockFactory.php +++ b/sources/application/UI/Base/Component/DataTable/DataTableUIBlockFactory.php @@ -6,8 +6,8 @@ namespace Combodo\iTop\Application\UI\Base\Component\DataTable; -use ApplicationException; use ApplicationContext; +use ApplicationException; use appUserPreferences; use AttributeLinkedSet; use cmdbAbstractObject; @@ -35,9 +35,9 @@ use WebPage; * Class DataTableUIBlockFactory * * @author Anne-Catherine Cognet - * @package Combodo\iTop\Application\UI\Base\Component\DataTable - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 */ class DataTableUIBlockFactory extends AbstractUIBlockFactory { @@ -47,6 +47,7 @@ class DataTableUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = DataTable::class; /** + * @api * @param \WebPage $oPage * @param string $sListId * @param \DBObjectSet $oSet @@ -71,6 +72,7 @@ class DataTableUIBlockFactory extends AbstractUIBlockFactory } /** + * @api * @param \WebPage $oPage * @param string $sListId * @param DBObjectSet $oSet @@ -183,6 +185,7 @@ class DataTableUIBlockFactory extends AbstractUIBlockFactory /** * Make a basis Panel component * + * @api * @param string $sListId * @param \DBObjectSet $oSet * @param array $aExtraParams @@ -479,6 +482,7 @@ class DataTableUIBlockFactory extends AbstractUIBlockFactory } /** + * @api * @param string $sListId * @param DBObjectSet $oSet * @param array $aExtraParams @@ -721,7 +725,9 @@ class DataTableUIBlockFactory extends AbstractUIBlockFactory * @param string $sSelectMode * @param string $sFilter * @param int $iLength + * @param array $aClassAliases * @param array $aExtraParams + * @param string $sTableId * * @return array * @throws \Exception @@ -901,6 +907,7 @@ JS; } /** + * @api * @param string $sTitle * @param array $aColumns * @param array $aData @@ -936,6 +943,7 @@ JS; } /** + * @api * @param string $sRef * @param array $aColumns * @param array $aData diff --git a/sources/application/UI/Base/Component/Field/FieldUIBlockFactory.php b/sources/application/UI/Base/Component/Field/FieldUIBlockFactory.php index d45703168..e9bcdc9ab 100644 --- a/sources/application/UI/Base/Component/Field/FieldUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Field/FieldUIBlockFactory.php @@ -16,9 +16,10 @@ use Combodo\iTop\Application\UI\Base\UIBlock; * * Use it to make a "field" which is composed of a label and a value (which can be read-only or editable) * + * @api + * @package UIBlockExtensibilityAPI * @author Pierre Goiffon * @since 3.0.0 - * @internal */ class FieldUIBlockFactory extends AbstractUIBlockFactory { @@ -27,6 +28,12 @@ class FieldUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = Field::class; + /** + * @api + * @param $aParams + * + * @return \Combodo\iTop\Application\UI\Base\Component\Field\Field + */ public static function MakeFromParams($aParams) { $oValue = new Html($aParams['value']); @@ -75,6 +82,14 @@ class FieldUIBlockFactory extends AbstractUIBlockFactory $oField->$sMethodName((($iParamsFlags & $iConstant) === $iConstant)); } + /** + * @api + * @param string $sLabel + * @param \Combodo\iTop\Application\UI\Base\UIBlock $oInput + * @param string|null $sLayout + * + * @return \Combodo\iTop\Application\UI\Base\Component\Field\Field + */ public static function MakeFromObject(string $sLabel, UIBlock $oInput, ?string $sLayout = null) { $oField = new Field($sLabel, $oInput); @@ -86,6 +101,13 @@ class FieldUIBlockFactory extends AbstractUIBlockFactory return $oField; } + /** + * @api + * @param string $sLabel + * @param string $sValueHtml + * + * @return \Combodo\iTop\Application\UI\Base\Component\Field\Field + */ public static function MakeLarge(string $sLabel, string $sValueHtml = '') { $oField = new Field($sLabel, new Html($sValueHtml)); @@ -93,6 +115,13 @@ class FieldUIBlockFactory extends AbstractUIBlockFactory return $oField; } + /** + * @api + * @param string $sLabel + * @param string $sValueHtml + * + * @return \Combodo\iTop\Application\UI\Base\Component\Field\Field + */ public static function MakeSmall(string $sLabel, string $sValueHtml = '') { $oField = new Field($sLabel, new Html($sValueHtml)); @@ -100,6 +129,14 @@ class FieldUIBlockFactory extends AbstractUIBlockFactory return $oField; } + /** + * @api + * @param string $sLabel + * @param string $sLayout + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Field\Field + */ public static function MakeStandard(string $sLabel = '', string $sLayout = Field::ENUM_FIELD_LAYOUT_SMALL, ?string $sId = null) { $oField = new Field($sLabel, null, $sId); diff --git a/sources/application/UI/Base/Component/FieldBadge/FieldBadgeUIBlockFactory.php b/sources/application/UI/Base/Component/FieldBadge/FieldBadgeUIBlockFactory.php index e8cd1c94e..0f3eec2ea 100644 --- a/sources/application/UI/Base/Component/FieldBadge/FieldBadgeUIBlockFactory.php +++ b/sources/application/UI/Base/Component/FieldBadge/FieldBadgeUIBlockFactory.php @@ -16,7 +16,7 @@ use utils; * Class FieldBadgeUIBlockFactory * * @author Eric espie - * @package Combodo\iTop\Application\UI\Base\Component\FieldBadge + * @package UIBlockExtensibilityAPI * @since 3.0.0 * @internal */ diff --git a/sources/application/UI/Base/Component/FieldSet/FieldSetUIBlockFactory.php b/sources/application/UI/Base/Component/FieldSet/FieldSetUIBlockFactory.php index ff6feb8a1..06ec076dc 100644 --- a/sources/application/UI/Base/Component/FieldSet/FieldSetUIBlockFactory.php +++ b/sources/application/UI/Base/Component/FieldSet/FieldSetUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class FieldSetUIBlockFactory * * @author eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\FieldSet - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 */ class FieldSetUIBlockFactory extends AbstractUIBlockFactory { @@ -26,6 +26,7 @@ class FieldSetUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = FieldSet::class; /** + * @api * @param string $sLegend * @param string|null $sId * diff --git a/sources/application/UI/Base/Component/Form/FormUIBlockFactory.php b/sources/application/UI/Base/Component/Form/FormUIBlockFactory.php index 521699a50..263e73dd4 100644 --- a/sources/application/UI/Base/Component/Form/FormUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Form/FormUIBlockFactory.php @@ -14,7 +14,7 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class FormUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Form + * @package UUIBlockExtensibilityAPI * @since 3.0.0 * @api */ @@ -26,6 +26,7 @@ class FormUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = Form::class; /** + * @api * @param string|null $sId * * @return \Combodo\iTop\Application\UI\Base\Component\Form\Form An HTML form in which you can add UIBlocks diff --git a/sources/application/UI/Base/Component/Input/FileSelect/FileSelectUIBlockFactory.php b/sources/application/UI/Base/Component/Input/FileSelect/FileSelectUIBlockFactory.php index 1eaf4d96a..061311325 100644 --- a/sources/application/UI/Base/Component/Input/FileSelect/FileSelectUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Input/FileSelect/FileSelectUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class FileSelectUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Input\FileSelect - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 */ class FileSelectUIBlockFactory extends AbstractUIBlockFactory { @@ -26,6 +26,7 @@ class FileSelectUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = FileSelect::class; /** + * @api * @param string $sName * @param string|null $sId * diff --git a/sources/application/UI/Base/Component/Input/InputUIBlockFactory.php b/sources/application/UI/Base/Component/Input/InputUIBlockFactory.php index 73f57157f..322ddfd29 100644 --- a/sources/application/UI/Base/Component/Input/InputUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Input/InputUIBlockFactory.php @@ -15,9 +15,9 @@ use Combodo\iTop\Application\UI\Base\Component\Field\Field; * Class InputUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Input + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class InputUIBlockFactory extends AbstractUIBlockFactory { @@ -26,6 +26,14 @@ class InputUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = Input::class; + /** + * @api + * @param string $sName + * @param string $sValue + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Input\Input + */ public static function MakeForHidden(string $sName, string $sValue, ?string $sId = null) { $oInput = new Input($sId); @@ -37,6 +45,15 @@ class InputUIBlockFactory extends AbstractUIBlockFactory return $oInput; } + /** + * @api + * @param string $sType + * @param string $sName + * @param string $sValue + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Input\Input + */ public static function MakeStandard(string $sType, string $sName, string $sValue, ?string $sId = null) { $oInput = new Input($sId); @@ -49,6 +66,7 @@ class InputUIBlockFactory extends AbstractUIBlockFactory } /** + * @api * @see Field component that is better adapter when dealing with a standard iTop form * * @param string $sLabel @@ -71,6 +89,15 @@ class InputUIBlockFactory extends AbstractUIBlockFactory return static::MakeInputWithLabel($sInputName, $sLabel, $oInput, $sInputId); } + /** + * @api + * @param string $sName + * @param string $sLabel + * @param \Combodo\iTop\Application\UI\Base\Component\Input\Input $oInput + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Input\InputWithLabel + */ private static function MakeInputWithLabel(string $sName, string $sLabel, Input $oInput, ?string $sId = null) { $oInput->SetName($sName); diff --git a/sources/application/UI/Base/Component/Input/Select/SelectOptionUIBlockFactory.php b/sources/application/UI/Base/Component/Input/Select/SelectOptionUIBlockFactory.php index 91f1ec236..8c84fa606 100644 --- a/sources/application/UI/Base/Component/Input/Select/SelectOptionUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Input/Select/SelectOptionUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class SelectOptionUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Input\Select + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class SelectOptionUIBlockFactory extends AbstractUIBlockFactory { @@ -25,6 +25,15 @@ class SelectOptionUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = SelectOption::class; + /** + * @api + * @param string $sValue + * @param string $sLabel + * @param bool $bSelected + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Input\Select\SelectOption + */ public static function MakeForSelectOption(string $sValue, string $sLabel, bool $bSelected, ?string $sId = null) { $oInput = new SelectOption($sId); diff --git a/sources/application/UI/Base/Component/Input/Select/SelectUIBlockFactory.php b/sources/application/UI/Base/Component/Input/Select/SelectUIBlockFactory.php index 43c1c5e66..b87a5009d 100644 --- a/sources/application/UI/Base/Component/Input/Select/SelectUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Input/Select/SelectUIBlockFactory.php @@ -15,9 +15,9 @@ use Combodo\iTop\Application\UI\Base\Component\Input\Select\Select; * Class SelectUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Input + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class SelectUIBlockFactory extends AbstractUIBlockFactory { @@ -29,6 +29,7 @@ class SelectUIBlockFactory extends AbstractUIBlockFactory /** * Create a default Select input * + * @api * @param string $sName {@see Select::$sName} * @param string|null $sId {@see UIBlock::$sId} * @@ -47,6 +48,7 @@ class SelectUIBlockFactory extends AbstractUIBlockFactory * * If you need to have a real field with a label, you might use a {@link Field} component instead * + * @api * @param string $sName {@see Select::$sName} * @param string $sLabel {@see Select::$sLabel} * @param string|null $sId {@see UIBlock::$sId} diff --git a/sources/application/UI/Base/Component/Panel/PanelUIBlockFactory.php b/sources/application/UI/Base/Component/Panel/PanelUIBlockFactory.php index e1d047262..d6c9abe31 100644 --- a/sources/application/UI/Base/Component/Panel/PanelUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Panel/PanelUIBlockFactory.php @@ -25,9 +25,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class PanelUIBlockFactory * * @author Guillaume Lajarige - * @package Combodo\iTop\Application\UI\Base\Component\Panel - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 * * @link /test/VisualTest/Backoffice/RenderAllUiBlocks.php#title-panels to see live examples */ @@ -41,6 +41,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a basis Panel component * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -60,6 +61,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component for informational messages * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -79,6 +81,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component for successful messages * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -98,6 +101,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component for warning messages * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -117,6 +121,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component for danger messages * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -136,6 +141,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component for failure messages * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -155,6 +161,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component with primary color scheme * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -174,6 +181,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component with secondary color scheme * + * @api * @param string $sTitle * @param string|null $sSubTitle * @@ -193,6 +201,7 @@ class PanelUIBlockFactory extends AbstractUIBlockFactory /** * Make a Panel component with the specific $sClass color scheme * + * @api * @param string $sClass Class of the object the panel is for * @param string $sTitle * @param string|null $sSubTitle diff --git a/sources/application/UI/Base/Component/Spinner/SpinnerUIBlockFactory.php b/sources/application/UI/Base/Component/Spinner/SpinnerUIBlockFactory.php index f665c5428..ba8dc7e80 100644 --- a/sources/application/UI/Base/Component/Spinner/SpinnerUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Spinner/SpinnerUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class SpinnerUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Spinner + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class SpinnerUIBlockFactory extends AbstractUIBlockFactory { @@ -25,6 +25,12 @@ class SpinnerUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = Spinner::class; + /** + * @api + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Spinner\Spinner + */ public static function MakeStandard(?string $sId = null) { return new Spinner($sId); diff --git a/sources/application/UI/Base/Component/Title/TitleUIBlockFactory.php b/sources/application/UI/Base/Component/Title/TitleUIBlockFactory.php index 7057dcbb1..b10a7e6e2 100644 --- a/sources/application/UI/Base/Component/Title/TitleUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Title/TitleUIBlockFactory.php @@ -16,9 +16,9 @@ use Combodo\iTop\Application\UI\Base\UIBlock; * Class TitleUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Title + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class TitleUIBlockFactory extends AbstractUIBlockFactory { @@ -27,11 +27,28 @@ class TitleUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = Title::class; + /** + * @api + * @param string $sTitle + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Title\Title + */ public static function MakeForPage(string $sTitle, ?string $sId = null) { return new Title(new Text($sTitle), 1, $sId); } + /** + * @api + * @param string $sTitle + * @param string $sIconUrl + * @param string $sIconCoverMethod + * @param bool $bIsMedallion + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Title\Title + */ public static function MakeForPageWithIcon( string $sTitle, string $sIconUrl, string $sIconCoverMethod = Title::DEFAULT_ICON_COVER_METHOD, bool $bIsMedallion = true, ?string $sId = null @@ -43,11 +60,27 @@ class TitleUIBlockFactory extends AbstractUIBlockFactory return $oTitle; } + /** + * @api + * @param string $sTitle + * @param int $iLevel + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Title\Title + */ public static function MakeNeutral(string $sTitle, int $iLevel = 1, ?string $sId = null) { return new Title(new Text($sTitle), $iLevel, $sId); } + /** + * @api + * @param \Combodo\iTop\Application\UI\Base\UIBlock $oTitle + * @param int $iLevel + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Title\Title + */ public static function MakeStandard(UIBlock $oTitle, int $iLevel = 1, ?string $sId = null) { return new Title($oTitle, $iLevel, $sId); diff --git a/sources/application/UI/Base/Component/Toolbar/Separator/ToolbarSeparatorUIBlockFactory.php b/sources/application/UI/Base/Component/Toolbar/Separator/ToolbarSeparatorUIBlockFactory.php index 6c342abb9..92dbd466e 100644 --- a/sources/application/UI/Base/Component/Toolbar/Separator/ToolbarSeparatorUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Toolbar/Separator/ToolbarSeparatorUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class ToolbarSeparatorUIBlockFactory * * @author Guillaume Lajarige - * @package Combodo\iTop\Application\UI\Base\Component\Toolbar\Separator - * @since 3.0.0 + * @package UIBlockExtensibilityAPI * @api + * @since 3.0.0 */ class ToolbarSeparatorUIBlockFactory extends AbstractUIBlockFactory { @@ -26,6 +26,7 @@ class ToolbarSeparatorUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = Toolbar::class; /** + * @api * @param string|null $sId * * @return \Combodo\iTop\Application\UI\Base\Component\Toolbar\Separator\VerticalSeparator diff --git a/sources/application/UI/Base/Component/Toolbar/ToolbarSpacer/ToolbarSpacerUIBlockFactory.php b/sources/application/UI/Base/Component/Toolbar/ToolbarSpacer/ToolbarSpacerUIBlockFactory.php index 7362a5259..098b5e050 100644 --- a/sources/application/UI/Base/Component/Toolbar/ToolbarSpacer/ToolbarSpacerUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Toolbar/ToolbarSpacer/ToolbarSpacerUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class ToolbarSpacerUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Toolbar\ToolbarSpacer + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class ToolbarSpacerUIBlockFactory extends AbstractUIBlockFactory { @@ -26,6 +26,7 @@ class ToolbarSpacerUIBlockFactory extends AbstractUIBlockFactory public const UI_BLOCK_CLASS_NAME = ToolbarSpacer::class; /** + * @api * @param string|null $sId * * @return \Combodo\iTop\Application\UI\Base\Component\Toolbar\ToolbarSpacer\ToolbarSpacer diff --git a/sources/application/UI/Base/Component/Toolbar/ToolbarUIBlockFactory.php b/sources/application/UI/Base/Component/Toolbar/ToolbarUIBlockFactory.php index 577c1908f..9cd80036f 100644 --- a/sources/application/UI/Base/Component/Toolbar/ToolbarUIBlockFactory.php +++ b/sources/application/UI/Base/Component/Toolbar/ToolbarUIBlockFactory.php @@ -14,9 +14,9 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class ToolbarUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Component\Toolbar + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 - * @internal */ class ToolbarUIBlockFactory extends AbstractUIBlockFactory { @@ -25,16 +25,36 @@ class ToolbarUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = Toolbar::class; + /** + * @api + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Component\Toolbar\Toolbar + */ public static function MakeForAction(string $sId = null) { return new Toolbar($sId, ['ibo-toolbar--action']); } + /** + * @api + * @param string|null $sId + * @param array $aContainerClasses + * + * @return \Combodo\iTop\Application\UI\Base\Component\Toolbar\Toolbar + */ public static function MakeStandard(string $sId = null, array $aContainerClasses = []) { return new Toolbar($sId, $aContainerClasses); } + /** + * @api + * @param string|null $sId + * @param array $aContainerClasses + * + * @return \Combodo\iTop\Application\UI\Base\Component\Toolbar\Toolbar + */ public static function MakeForButton(string $sId = null, array $aContainerClasses = []) { return new Toolbar($sId, array_merge($aContainerClasses, ['ibo-toolbar--button'])); diff --git a/sources/application/UI/Base/Layout/MultiColumn/Column/ColumnUIBlockFactory.php b/sources/application/UI/Base/Layout/MultiColumn/Column/ColumnUIBlockFactory.php index de8687773..d11f39ce7 100644 --- a/sources/application/UI/Base/Layout/MultiColumn/Column/ColumnUIBlockFactory.php +++ b/sources/application/UI/Base/Layout/MultiColumn/Column/ColumnUIBlockFactory.php @@ -15,7 +15,7 @@ use Combodo\iTop\Application\UI\Base\UIBlock; * Class ColumnUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Layout\MultiColumn\Column + * @package UIBlockExtensibilityAPI * @since 3.0.0 * @api */ @@ -26,6 +26,12 @@ class ColumnUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = Column::class; + /** + * @api + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Layout\MultiColumn\Column\Column + */ public static function MakeStandard(?string $sId = null) { $oInput = new Column($sId); @@ -33,6 +39,13 @@ class ColumnUIBlockFactory extends AbstractUIBlockFactory return $oInput; } + /** + * @api + * @param \Combodo\iTop\Application\UI\Base\UIBlock $oBlock + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Layout\MultiColumn\Column\Column + */ public static function MakeForBlock(UIBlock $oBlock, ?string $sId = null) { $oInput = new Column($sId); diff --git a/sources/application/UI/Base/Layout/MultiColumn/MultiColumnUIBlockFactory.php b/sources/application/UI/Base/Layout/MultiColumn/MultiColumnUIBlockFactory.php index 5d6d0b439..b90597619 100644 --- a/sources/application/UI/Base/Layout/MultiColumn/MultiColumnUIBlockFactory.php +++ b/sources/application/UI/Base/Layout/MultiColumn/MultiColumnUIBlockFactory.php @@ -13,7 +13,7 @@ use Combodo\iTop\Application\UI\Base\AbstractUIBlockFactory; * Class MultiColumnUIBlockFactory * * @author Eric Espie - * @package Combodo\iTop\Application\UI\Base\Layout\MultiColumn + * @package UIBlockExtensibilityAPI * @since 3.0.0 * @api */ @@ -24,6 +24,12 @@ class MultiColumnUIBlockFactory extends AbstractUIBlockFactory /** @inheritDoc */ public const UI_BLOCK_CLASS_NAME = MultiColumn::class; + /** + * @api + * @param string|null $sId + * + * @return \Combodo\iTop\Application\UI\Base\Layout\MultiColumn\MultiColumn + */ public static function MakeStandard(?string $sId = null) { $oInput = new MultiColumn($sId); diff --git a/sources/application/UI/Base/Layout/UIContentBlockUIBlockFactory.php b/sources/application/UI/Base/Layout/UIContentBlockUIBlockFactory.php index 8dd5fa0e5..f55eda536 100644 --- a/sources/application/UI/Base/Layout/UIContentBlockUIBlockFactory.php +++ b/sources/application/UI/Base/Layout/UIContentBlockUIBlockFactory.php @@ -15,7 +15,8 @@ use Combodo\iTop\Application\UI\Base\Component\Html\Html; * Class UIContentBlockUIBlockFactory * * @author Guillaume Lajarige - * @package Combodo\iTop\Application\UI\Base\Layout + * @package UIBlockExtensibilityAPI + * @api * @since 3.0.0 */ class UIContentBlockUIBlockFactory extends AbstractUIBlockFactory @@ -28,6 +29,7 @@ class UIContentBlockUIBlockFactory extends AbstractUIBlockFactory /** * Make an empty UIContentBlock which can be used to embed anything or to surround another block with specific CSS classes. * + * @api * @param string|null $sId * @param array $aContainerClasses * @@ -42,6 +44,7 @@ class UIContentBlockUIBlockFactory extends AbstractUIBlockFactory * Used to display a block of code like 
 but allows line break.
 	 * The \n are replaced by 

 	 *
+	 * @api
 	 * @param string $sCode
 	 * @param string|null $sId
 	 *
@@ -59,6 +62,7 @@ class UIContentBlockUIBlockFactory extends AbstractUIBlockFactory
 	/**
 	 * Used to display a block of preformatted text in a 
 tag.
 	 *
+	 * @api
 	 * @param string $sCode
 	 * @param string|null $sId
 	 *