Auto-documentation: first step => the extension APIs

git-svn-id: http://svn.code.sf.net/p/itop/code/trunk@2585 a333f486-631f-4898-b8df-5754b55c2be0

application/applicationextension.inc.php

@@ -17,34 +17,248 @@
 //   along with iTop. If not, see <http://www.gnu.org/licenses/>
 
 /**
- * Class iPlugin
- * Management of application plugin 
+ * Management of application plugins
+ * 
+ * Definition of interfaces that can be implemented to customize iTop.
+ * You may implement such interfaces in a module file (e.g. main.mymodule.php) 
  *
+ * @package     Extensibility
  * @copyright   Copyright (C) 2010-2012 Combodo SARL
  * @license     http://opensource.org/licenses/AGPL-3.0
+ * @api
  */
 
+/**
+ * Implement this interface to change the behavior of the GUI for some objects.
+ *
+ * All methods are invoked by iTop for a given object. There are basically two usages:
+ * 
+ * 1) To tweak the form of an object, you will have to implement a specific behavior within:
+ *  
+ * * OnDisplayProperties (bEditMode = true)
+ * * OnFormSubmit
+ * * OnFormCancel
+ * 
+ * 2) To tune the display of the object details, you can use:
+ *  
+ * * OnDisplayProperties
+ * * OnDisplayRelations
+ * * GetIcon
+ * * GetHilightClass
+ *   
+ * Please note that some of the APIs can be called several times for a single page displayed.
+ * Therefore it is not recommended to perform too many operations, such as querying the database.
+ * A recommended pattern is to cache data by the mean of static members. 
+ *
+ * @package     Extensibility
+ * @api
+ */
 interface iApplicationUIExtension
 {
+	/**
+	 *	Invoked when an object is being displayed (wiew or edit)
+	 *	
+	 * The method is called right after the main tab has been displayed.
+	 * You can add output to the page, either to change the display, or to add a form input
+	 * 
+	 * Example:
+	 * <code>
+	 * if ($bEditMode)
+	 * {
+	 * 	$oPage->p('Age of the captain: &lt;input type="text" name="captain_age"/&gt;');
+	 * }
+	 * else
+	 * {
+	 * 	$oPage->p('Age of the captain: '.$iCaptainAge);
+	 * }	 
+	 * </code>
+	 * 
+	 * @param DBObject $oObject The object being displayed
+	 * @param WebPage $oPage The output context
+	 * @param boolean $bEditMode True if the edition form is being displayed
+	 * @return void
+	 */	
 	public function OnDisplayProperties($oObject, WebPage $oPage, $bEditMode = false);
+
+	/**
+	 *	Invoked when an object is being displayed (wiew or edit)
+	 *	
+	 * The method is called rigth after all the tabs have been displayed 
+	 * 
+	 * @param DBObject $oObject The object being displayed
+	 * @param WebPage $oPage The output context
+	 * @param boolean $bEditMode True if the edition form is being displayed
+	 * @return void
+	 */	
 	public function OnDisplayRelations($oObject, WebPage $oPage, $bEditMode = false);
+
+	/**
+	 *	Invoked when the end-user clicks on Modify from the object edition form
+	 *	
+	 * The method is called after the changes from the standard form have been
+	 * taken into account, and before saving the changes into the database.	 
+	 * 
+	 * @param DBObject $oObject The object being edited
+	 * @param string $sFormPrefix Prefix given to the HTML form inputs
+	 * @return void
+	 */	
 	public function OnFormSubmit($oObject, $sFormPrefix = '');
-	public function OnFormCancel($sTempId); // temp id is made of session_id and transaction_id, it identifies the object in a unique way
 
+	/**
+	 *	Invoked when the end-user clicks on Cancel from the object edition form
+	 *	
+	 * Implement here any cleanup. This is necessary when you have injected some
+	 * javascript into the edition form, and if that code requires to store temporary data
+	 * (this is the case when a file must be uploaded).
+	 * 
+	 * @param string $sTempId Unique temporary identifier made of session_id and transaction_id. It identifies the object in a unique way.
+	 * @return void
+	 */	
+	public function OnFormCancel($sTempId);
+
+	/**
+	 *	Not yet called by the framework!
+	 *	
+	 * Sorry, the verb has been reserved. You must implement it, but it is not called as of now.
+	 * 
+	 * @param DBObject $oObject The object being displayed
+	 * @return type desc
+	 */	
 	public function EnumUsedAttributes($oObject); // Not yet implemented
+
+	/**
+	 *	Not yet called by the framework!
+	 *	
+	 * Sorry, the verb has been reserved. You must implement it, but it is not called as of now.
+	 * 
+	 * @param DBObject $oObject The object being displayed
+	 * @return string Path of the icon, relative to the modules directory.
+	 */	
 	public function GetIcon($oObject); // Not yet implemented
+
+	/**
+	 *	Invoked when the object is displayed alone or within a list
+	 *	
+	 * Returns a value influencing the appearance of the object depending on its
+	 * state.
+	 * 
+	 * Possible values are:
+	 *
+	 * * HILIGHT_CLASS_CRITICAL
+ 	 * * HILIGHT_CLASS_WARNING
+	 * * HILIGHT_CLASS_OK
+	 * * HILIGHT_CLASS_NONE	
+	 * 
+	 * @param DBObject $oObject The object being displayed
+	 * @return integer The value representing the mood of the object
+	 */	
 	public function GetHilightClass($oObject);
 
+	/**
+	 *	Called when building the Actions menu for a single object or a list of objects
+	 *
+	 * Use this to add items to the Actions menu. You will have to specify a label and an URL.
+	 *
+	 * Example:
+	 * <code>
+	 * $oObject = $oSet->fetch();	 
+	 * if ($oObject instanceof Sheep)
+	 * {	 
+	 * 	return array('View in my app' => 'http://myserver/view_sheeps?id='.$oObject->Get('name'));
+	 * }
+	 * else
+	 * {
+	 * 	return array();
+	 * }
+	 * </code>
+	 *
+	 * See also iPopupMenuExtension for greater flexibility
+	 * 
+	 * @param DBObjectSet $oSet A set of persistent objects (DBObject)
+	 * @return string[string]
+	 */	
 	public function EnumAllowedActions(DBObjectSet $oSet);
 }
 
+/**
+ * Implement this interface to perform specific things when objects are manipulated
+ *
+ * Note that those methods will be called when objects are manipulated, either in a programmatic way
+ * or through the GUI. 
+ *  
+ * @package     Extensibility
+ * @api
+ */ 
 interface iApplicationObjectExtension
 {
+	/**
+	 *	Invoked to determine wether an object has been modified in memory
+	 *
+	 *	The GUI calls this verb to determine the message that will be displayed to the end-user.
+	 *	Anyhow, this API can be called in other contexts such as the CSV import tool.
+	 *	
+	 * If the extension returns false, then the framework will perform the usual evaluation.
+	 * Otherwise, the answer is definitively "yes, the object has changed".	 	 	 
+	 *	 
+	 * @param DBObject $oObject The target object
+	 * @return boolean True if something has changed for the target object
+	 */	
 	public function OnIsModified($oObject);
+
+	/**
+	 *	Invoked to determine wether an object can be written to the database 
+	 *	
+	 *	The GUI calls this verb and reports any issue.
+	 *	Anyhow, this API can be called in other contexts such as the CSV import tool.
+	 * 
+	 * @param DBObject $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.
+	 */	
 	public function OnCheckToWrite($oObject);
+
+	/**
+	 *	Invoked to determine wether an object can be deleted from the database
+	 *	
+	 * The GUI calls this verb and stops the deletion process if any issue is reported.
+	 * 	 
+	 * Please not that it is not possible to cascade deletion by this mean: only stopper issues can be handled. 	 
+	 * 
+	 * @param DBObject $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.
+	 */	
 	public function OnCheckToDelete($oObject);
+
+	/**
+	 *	Invoked when an object is updated into the database
+	 *	
+	 * The method is called right <b>after</b> the object has been written to the database.
+	 * 
+	 * @param DBObject $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
+	 * @return void
+	 */	
 	public function OnDBUpdate($oObject, $oChange = null);
+
+	/**
+	 *	Invoked when an object is created into the database
+	 *	
+	 * The method is called right <b>after</b> the object has been written to the database.
+	 * 
+	 * @param DBObject $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
+	 * @return void
+	 */	
 	public function OnDBInsert($oObject, $oChange = null);
+
+	/**
+	 *	Invoked when an object is deleted from the database
+	 *	
+	 * The method is called right <b>before</b> the object will be deleted from the database.
+	 * 
+	 * @param DBObject $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
+	 * @return void
+	 */	
 	public function OnDBDelete($oObject, $oChange = null);
 }
 
@@ -54,46 +268,102 @@ interface iApplicationObjectExtension
  * 
  * To add some menus into iTop, declare a class that implements this interface, it will be called automatically
  * by the application, as long as the class definition is included somewhere in the code
+ * 
+ * @package     Extensibility
+ * @api
+ * @since 2.0  
  */
 interface iPopupMenuExtension
 {
-	// Possible types of menu into which new items can be added
-	const MENU_OBJLIST_ACTIONS = 1; 	// $param is a DBObjectSet containing the list of objects
-	const MENU_OBJLIST_TOOLKIT = 2;		// $param is a DBObjectSet containing the list of objects
-	const MENU_OBJDETAILS_ACTIONS = 3;	// $param is a DBObject instance: the object currently displayed
-	const MENU_DASHBOARD_ACTIONS = 4;	// $param is a Dashboard instance: the dashboard currently displayed
-	const MENU_USER_ACTIONS = 5;		// $param is a null ??
+	/**
+	 * Insert an item into the Actions menu of a list
+	 *
+	 * $param is a DBObjectSet containing the list of objects	
+	 */	
+	const MENU_OBJLIST_ACTIONS = 1;
+	/**
+	 * Insert an item into the Toolkit menu of a list
+	 *
+	 * $param is a DBObjectSet containing the list of objects
+	 */	
+	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
+	 */	
+	const MENU_OBJDETAILS_ACTIONS = 3;
+	/**
+	 * Insert an item into the Dashboard menu
+	 *
+	 * The dashboad menu is shown on the top right corner when a dashboard
+	 * is being displayed.
+	 * 
+	 * $param is a Dashboard instance: the dashboard currently displayed
+	 */	
+	const MENU_DASHBOARD_ACTIONS = 4;
+	/**
+	 * Insert an item into the User menu (upper right corner)
+	 *
+	 * $param is null
+	 */
+	const MENU_USER_ACTIONS = 5;
 
 	/**
-	 * Get the list of items to be added to a menu. The items will be inserted in the menu in the order of the returned array
-	 * @param int $iMenuId The identifier of the type of menu, as listed by the constants MENU_xxx above
+	 * Get the list of items to be added to a menu.
+	 *
+	 * 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.
+	 * @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
-	 * @return Array An array of ApplicationPopupMenuItem or an empty array if no action is to be added to the menu
+	 * @return object[] An array of ApplicationPopupMenuItem or an empty array if no action is to be added to the menu
 	 */
 	public static function EnumItems($iMenuId, $param);
 }
 
 /**
- * Each menu items is defined by an instance of an object derived from the class
- * ApplicationPopupMenu below
- *
+ * Base class for the various types of custom menus
+ * 
+ * @package     Extensibility
+ * @internal
+ * @since 2.0
  */
 abstract class ApplicationPopupMenuItem
 {
+	/** @ignore */
 	protected $sUID;
+	/** @ignore */
 	protected $sLabel;
 	
+	/**
+	 *	Constructor
+	 *	
+	 * @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)
+	 */	
 	public function __construct($sUID, $sLabel)
 	{
 		$this->sUID = $sUID;
 		$this->sLabel = $sLabel;
 	}
 	
+	/**
+	 *	Get the UID
+	 *	
+	 * @return string The unique identifier	 
+	 * @ignore	 	 
+	 */	
 	public function GetUID()
 	{
 		return $this->sUID;
 	}
 	
+	/**
+	 *	Get the label
+	 *	
+	 * @return string The label
+	 * @ignore	 	 
+	 */	
 	public function GetLabel()
 	{
 		return $this->sLabel;
@@ -102,9 +372,11 @@ abstract class ApplicationPopupMenuItem
 	/**
 	 * Returns the components to create a popup menu item in HTML
 	 * @return Hash A hash array: array('label' => , 'url' => , 'target' => , 'onclick' => )
+	 * @ignore	 	 
 	 */
 	abstract public function GetMenuItem();
 
+	/** @ignore */
 	public function GetLinkedScripts()
 	{
 		return array();
@@ -113,14 +385,21 @@ abstract class ApplicationPopupMenuItem
 
 /**
  * Class for adding an item into a popup menu that browses to the given URL
+ *  
+ * @package     Extensibility
+ * @api
+ * @since 2.0  
  */
 class URLPopupMenuItem extends ApplicationPopupMenuItem
 {
+	/** @ignore */
 	protected $sURL;
+	/** @ignore */
 	protected $sTarget;
 	
 	/**
-	 * Class for adding an item that browses to the given URL
+	 * Constructor
+	 * 	 
 	 * @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
@@ -133,6 +412,7 @@ class URLPopupMenuItem extends ApplicationPopupMenuItem
 		$this->sTarget = $sTarget;
 	}
 	
+	/** @ignore */
 	public function GetMenuItem()
 	{
 		return array ('label' => $this->GetLabel(), 'url' => $this->sURL, 'target' => $this->sTarget);	
@@ -141,10 +421,16 @@ class URLPopupMenuItem extends ApplicationPopupMenuItem
 
 /**
  * Class for adding an item into a popup menu that triggers some Javascript code
+ * 
+ * @package     Extensibility
+ * @api
+ * @since 2.0  
  */
 class JSPopupMenuItem extends ApplicationPopupMenuItem
 {
+	/** @ignore */
 	protected $sJSCode;
+	/** @ignore */
 	protected $aIncludeJSFiles;
 	
 	/**
@@ -161,11 +447,13 @@ class JSPopupMenuItem extends ApplicationPopupMenuItem
 		$this->aIncludeJSFiles = $aIncludeJSFiles;
 	}
 	
+	/** @ignore */
 	public function GetMenuItem()
 	{
 		return array ('label' => $this->GetLabel(), 'onclick' => $this->sJSCode, 'url' => '#');
 	}
 	
+	/** @ignore */
 	public function GetLinkedScripts()
 	{
 		return $this->aIncludeJSFiles;
@@ -175,17 +463,22 @@ class JSPopupMenuItem extends ApplicationPopupMenuItem
 /**
  * Class for adding a separator (horizontal line, not selectable) the output
  * will automatically reduce several consecutive separators to just one
+ * 
+ * @package     Extensibility
+ * @api
+ * @since 2.0  
  */
 class SeparatorPopupMenuItem extends ApplicationPopupMenuItem
 {
 	/**
-	 * Class for inserting a separator into a popup menu
+	 * Constructor	
 	 */
 	public function __construct()
 	{
 		parent::__construct('', '');
 	}
 	
+	/** @ignore */
 	public function GetMenuItem()
 	{
 		return array ('label' => '<hr class="menu-separator">', 'url' => '');
@@ -194,34 +487,40 @@ class SeparatorPopupMenuItem extends ApplicationPopupMenuItem
 
 /**
  * Implement this interface to add content to any iTopWebPage
+ * 
  * There are 3 places where content can be added:
- * - The north pane: (normaly empty/hidden) at the top of the page, spanning the whole
+ * 
+ * * The north pane: (normaly empty/hidden) at the top of the page, spanning the whole
  *   width of the page
- * - The south pane: (normaly empty/hidden) at the bottom of the page, spanning the whole
+ * * The south pane: (normaly empty/hidden) at the bottom of the page, spanning the whole
  *   width of the page
- * - The admin banner (two tones gray background) at the left of the global search.
+ * * The admin banner (two tones gray background) at the left of the global search.
  *   Limited space, use it for short messages
+ * 
  * Each of the methods of this interface is supposed to return the HTML to be inserted at
  * the specified place and can use the passed iTopWebPage object to add javascript or CSS definitions
  *
+ * @package     Extensibility
+ * @api
+ * @since 2.0  
  */
 interface iPageUIExtension
 {
 	/**
 	 * Add content to the North pane
-	 * @param WebPage $oPage The page to insert stuff into.
+	 * @param iTopWebPage $oPage The page to insert stuff into.
 	 * @return string The HTML content to add into the page
 	 */
 	public function GetNorthPaneHtml(iTopWebPage $oPage);
 	/**
 	 * Add content to the South pane
-	 * @param WebPage $oPage The page to insert stuff into.
+	 * @param iTopWebPage $oPage The page to insert stuff into.
 	 * @return string The HTML content to add into the page
 	 */
 	public function GetSouthPaneHtml(iTopWebPage $oPage);
 	/**
 	 * Add content to the "admin banner"
-	 * @param WebPage $oPage The page to insert stuff into.
+	 * @param iTopWebPage $oPage The page to insert stuff into.
 	 * @return string The HTML content to add into the page
 	 */
 	public function GetBannerHtml(iTopWebPage $oPage);

phpdoc.dist.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdoc>
+  <title><![CDATA[iTop extensions]]></title>
+  <parser>
+    <target>/var/www/doc-extensions</target>
+  </parser>
+  <transformer>
+    <target>/var/www/doc-extensions</target>
+  </transformer>
+  <files>
+    <file>/home/romain/itop-trunk/application/applicationextension.inc.php</file>
+  </files>
+</phpdoc>