CRM/Core/Component/Info.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  * This interface defines methods that need to be implemented
  30  * for a component to introduce itself to the system.
  31  *
  32  * @package CRM
  33  * @copyright CiviCRM LLC (c) 2004-2014
  34  * $Id$
  35  *
  36  */
  37
  38 abstract class CRM_Core_Component_Info {
  39
  40   /*
  41      * Name of the class (minus component namespace path)
  42      * of the component invocation class'es name.
  43      */
  44   CONST COMPONENT_INVOKE_CLASS = 'Invoke';
  45
  46   /*
  47      * Name of the class (minus component namespace path)
  48      * of the component configuration class'es name.
  49      */
  50   CONST COMPONENT_CONFIG_CLASS = 'Config';
  51
  52   /*
  53      * Name of the class (minus component namespace path)
  54      * of the component BAO Query class'es name.
  55      */
  56   CONST COMPONENT_BAO_QUERY_CLASS = 'BAO_Query';
  57
  58   /*
  59      * Name of the class (minus component namespace path)
  60      * of the component user dashboard plugin.
  61      */
  62   CONST COMPONENT_USERDASHBOARD_CLASS = 'Page_UserDashboard';
  63
  64   /*
  65      * Name of the class (minus component namespace path)
  66      * of the component tab offered to contact record view.
  67      */
  68   CONST COMPONENT_TAB_CLASS = 'Page_Tab';
  69
  70   /*
  71      * Name of the class (minus component namespace path)
  72      * of the component tab offered to contact record view.
  73      */
  74   CONST COMPONENT_ADVSEARCHPANE_CLASS = 'Form_Search_AdvancedSearchPane';
  75
  76   /*
  77      * Name of the directory (assumed in component directory)
  78      * where xml resources used by this component live.
  79      */
  80   CONST COMPONENT_XML_RESOURCES = 'xml';
  81
  82   /*
  83      * Name of the directory (assumed in xml resources path)
  84      * containing component menu definition XML file names.
  85      */
  86   CONST COMPONENT_MENU_XML = 'Menu';
  87
  88   /*
  89    * Stores component information.
  90    * @var array component settings as key/value pairs
  91    */
  92   public $info;
  93
  94   /*
  95    * Stores component keyword
  96    * @var string name of component keyword
  97    */
  98   protected $keyword;
  99
 100   /*
 101    * Class constructor, sets name and namespace (those are stored
 102    * in the component registry (database) and no need to duplicate
 103    * them here, as well as populates the info variable.
 104    *
 105    * @param string $name name of the component
 106    * @param string $namespace namespace prefix for component's files
 107    * @access public
 108    *
 109    */
 110   public function __construct($name, $namespace, $componentID) {
 111     $this->name        = $name;
 112     $this->namespace   = $namespace;
 113     $this->componentID = $componentID;
 114     $this->info        = $this->getInfo();
 115     $this->info['url'] = $this->getKeyword();
 116   }
 117
 118   /**
 119    * EXPERIMENTAL: Get a list of AngularJS modules
 120    *
 121    * @return array list of modules; same format as CRM_Utils_Hook::angularModules(&$angularModules)
 122    * @see CRM_Utils_Hook::angularModules
 123    */
 124   public function getAngularModules() {
 125     return array();
 126   }
 127
 128   /**
 129    * Provides base information about the component.
 130    * Needs to be implemented in component's information
 131    * class.
 132    *
 133    * @return array collection of required component settings
 134    * @access public
 135    *
 136    */
 137   abstract public function getInfo();
 138
 139   /**
 140    * Get a list of entities to register via API
 141    *
 142    * @return array list of entities; same format as CRM_Utils_Hook::managedEntities(&$entities)
 143    * @see CRM_Utils_Hook::managedEntities
 144    */
 145   public function getManagedEntities() {
 146     return array();
 147   }
 148
 149   /**
 150    * Provides permissions that are unwise for Anonymous Roles to have
 151    *
 152    * @return array list of permissions
 153    * @see CRM_Component_Info::getPermissions
 154    */
 155   public function getAnonymousPermissionWarnings() {
 156     return array();
 157   }
 158
 159   /**
 160    * Provides permissions that are used by component.
 161    * Needs to be implemented in component's information
 162    * class.
 163    *
 164    * NOTE: if using conditionally permission return,
 165    * implementation of $getAllUnconditionally is required.
 166    *
 167    * @param bool $getAllUnconditionally
 168    *
 169    * @return array|null collection of permissions, null if none
 170    * @access public
 171    */
 172   abstract public function getPermissions($getAllUnconditionally = FALSE);
 173
 174   /**
 175    * Provides information about user dashboard element
 176    * offered by this component.
 177    *
 178    * @return array|null collection of required dashboard settings,
 179    *                    null if no element offered
 180    * @access public
 181    *
 182    */
 183   abstract public function getUserDashboardElement();
 184
 185   /**
 186    * Provides information about user dashboard element
 187    * offered by this component.
 188    *
 189    * @return array|null collection of required dashboard settings,
 190    *                    null if no element offered
 191    * @access public
 192    *
 193    */
 194   abstract public function registerTab();
 195
 196   /**
 197    * Provides information about advanced search pane
 198    * offered by this component.
 199    *
 200    * @return array|null collection of required pane settings,
 201    *                    null if no element offered
 202    * @access public
 203    *
 204    */
 205   abstract public function registerAdvancedSearchPane();
 206
 207   /**
 208    * Provides potential activity types that this
 209    * component might want to register in activity history.
 210    * Needs to be implemented in component's information
 211    * class.
 212    *
 213    * @return array|null collection of activity types
 214    * @access public
 215    *
 216    */
 217   abstract public function getActivityTypes();
 218
 219   /**
 220    * Provides information whether given component is currently
 221    * marked as enabled in configuration.
 222    *
 223    * @return boolean true if component is enabled, false if not
 224    * @access public
 225    *
 226    */
 227   public function isEnabled() {
 228     $config = CRM_Core_Config::singleton();
 229     if (in_array($this->info['name'], $config->enableComponents)) {
 230       return TRUE;
 231     }
 232     return FALSE;
 233   }
 234
 235   /**
 236    * Provides component's configuration object.
 237    *
 238    * @return mixed component's configuration object
 239    * @access public
 240    *
 241    */
 242   public function getConfigObject() {
 243     return $this->_instantiate(self::COMPONENT_CONFIG_CLASS);
 244   }
 245
 246   /**
 247    * Provides component's menu definition object.
 248    *
 249    * @return mixed component's menu definition object
 250    * @access public
 251    *
 252    */
 253   public function getMenuObject() {
 254     return $this->_instantiate(self::COMPONENT_MENU_CLASS);
 255   }
 256
 257   /**
 258    * Provides component's invocation object.
 259    *
 260    * @return mixed component's invocation object
 261    * @access public
 262    *
 263    */
 264   public function getInvokeObject() {
 265     return $this->_instantiate(self::COMPONENT_INVOKE_CLASS);
 266   }
 267
 268   /**
 269    * Provides component's BAO Query object.
 270    *
 271    * @return mixed component's BAO Query object
 272    * @access public
 273    *
 274    */
 275   public function getBAOQueryObject() {
 276     return $this->_instantiate(self::COMPONENT_BAO_QUERY_CLASS);
 277   }
 278
 279   /**
 280    * Builds advanced search form's component specific pane.
 281    *
 282    * @access public
 283    *
 284    */
 285   public function buildAdvancedSearchPaneForm(&$form) {
 286     $bao = $this->getBAOQueryObject();
 287     $bao->buildSearchForm($form);
 288   }
 289
 290   /**
 291    * Provides component's user dashboard page object.
 292    *
 293    * @return mixed component's User Dashboard applet object
 294    * @access public
 295    *
 296    */
 297   public function getUserDashboardObject() {
 298     return $this->_instantiate(self::COMPONENT_USERDASHBOARD_CLASS);
 299   }
 300
 301   /**
 302    * Provides component's contact record tab object.
 303    *
 304    * @return mixed component's contact record tab object
 305    * @access public
 306    *
 307    */
 308   public function getTabObject() {
 309     return $this->_instantiate(self::COMPONENT_TAB_CLASS);
 310   }
 311
 312   /**
 313    * Provides component's advanced search pane's template path.
 314    *
 315    * @return string component's advanced search pane's template path
 316    * @access public
 317    *
 318    */
 319   public function getAdvancedSearchPaneTemplatePath() {
 320     $fullpath = $this->namespace . '_' . self::COMPONENT_ADVSEARCHPANE_CLASS;
 321     return str_replace('_', DIRECTORY_SEPARATOR, $fullpath . '.tpl');
 322   }
 323
 324   /**
 325    * Provides information whether given component uses system wide search.
 326    *
 327    * @return boolean true if component needs search integration
 328    * @access public
 329    *
 330    */
 331   public function usesSearch() {
 332     return $this->info['search'] ? TRUE : FALSE;
 333   }
 334
 335   /**
 336    * Provides the xml menu files
 337    *
 338    * @return array array of menu files
 339    * @access public
 340    *
 341    */
 342   public function menuFiles() {
 343     return CRM_Utils_File::getFilesByExtension($this->_getMenuXMLPath(), 'xml');
 344   }
 345
 346   /**
 347    * Simple "keyword" getter.
 348    * FIXME: It should be protected so the keyword is not
 349    * FIXME: accessed from beyond component infrastructure.
 350    *
 351    * @return string component keyword
 352    * @access public
 353    *
 354    */
 355   public function getKeyword() {
 356     return $this->keyword;
 357   }
 358
 359   /**
 360    * Helper for figuring out menu XML file location.
 361    *
 362    * @return mixed component's element as class instance
 363    * @access private
 364    *
 365    */
 366   private function _getMenuXMLPath() {
 367     global $civicrm_root;
 368     $fullpath = $this->namespace . '_' . self::COMPONENT_XML_RESOURCES . '_' . self::COMPONENT_MENU_XML;
 369     return CRM_Utils_File::addTrailingSlash($civicrm_root . DIRECTORY_SEPARATOR . str_replace('_', DIRECTORY_SEPARATOR, $fullpath));
 370   }
 371
 372   /**
 373    * Helper for instantiating component's elements.
 374    *
 375    * @param $cl
 376    *
 377    * @return mixed component's element as class instance
 378    * @access private
 379    */
 380   private function _instantiate($cl) {
 381     $className = $this->namespace . '_' . $cl;
 382     require_once (str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php');
 383     return new $className();
 384   }
 385 }
 386