CRM/Core/Component/Info.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   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 abstract class CRM_Core_Component_Info {
  38
  39   /**
  40    * Name of the class (minus component namespace path)
  41    * of the component invocation class'es name.
  42    */
  43   const COMPONENT_INVOKE_CLASS = 'Invoke';
  44
  45   /**
  46    * Name of the class (minus component namespace path)
  47    * of the component configuration class'es name.
  48    */
  49   const COMPONENT_CONFIG_CLASS = 'Config';
  50
  51   /**
  52    * Name of the class (minus component namespace path)
  53    * of the component BAO Query class'es name.
  54    */
  55   const COMPONENT_BAO_QUERY_CLASS = 'BAO_Query';
  56
  57   /**
  58    * Name of the class (minus component namespace path)
  59    * of the component user dashboard plugin.
  60    */
  61   const COMPONENT_USERDASHBOARD_CLASS = 'Page_UserDashboard';
  62
  63   /**
  64    * Name of the class (minus component namespace path)
  65    * of the component tab offered to contact record view.
  66    */
  67   const COMPONENT_TAB_CLASS = 'Page_Tab';
  68
  69   /**
  70    * Name of the class (minus component namespace path)
  71    * of the component tab offered to contact record view.
  72    */
  73   const COMPONENT_ADVSEARCHPANE_CLASS = 'Form_Search_AdvancedSearchPane';
  74
  75   /**
  76    * Name of the directory (assumed in component directory)
  77    * where xml resources used by this component live.
  78    */
  79   const COMPONENT_XML_RESOURCES = 'xml';
  80
  81   /**
  82    * Name of the directory (assumed in xml resources path)
  83    * containing component menu definition XML file names.
  84    */
  85   const COMPONENT_MENU_XML = 'Menu';
  86
  87   /**
  88    * Stores component information.
  89    * @var array component settings as key/value pairs
  90    */
  91   public $info;
  92
  93   /**
  94    * Stores component keyword
  95    * @var string name of component keyword
  96    */
  97   protected $keyword;
  98
  99   /**
 100    * @param string $name
 101    *   Name of the component.
 102    * @param string $namespace
 103    *   Namespace prefix for component's files.
 104    * @param int $componentID
 105    */
 106   public function __construct($name, $namespace, $componentID) {
 107     $this->name = $name;
 108     $this->namespace = $namespace;
 109     $this->componentID = $componentID;
 110     $this->info = $this->getInfo();
 111     $this->info['url'] = $this->getKeyword();
 112   }
 113
 114   /**
 115    * EXPERIMENTAL: Get a list of AngularJS modules
 116    *
 117    * @return array
 118    *   list of modules; same format as CRM_Utils_Hook::angularModules(&$angularModules)
 119    * @see CRM_Utils_Hook::angularModules
 120    */
 121   public function getAngularModules() {
 122     return array();
 123   }
 124
 125   /**
 126    * Provides base information about the component.
 127    * Needs to be implemented in component's information
 128    * class.
 129    *
 130    * @return array
 131    *   collection of required component settings
 132    */
 133   abstract public function getInfo();
 134
 135   /**
 136    * Get a list of entities to register via API
 137    *
 138    * @return array
 139    *   list of entities; same format as CRM_Utils_Hook::managedEntities(&$entities)
 140    * @see CRM_Utils_Hook::managedEntities
 141    */
 142   public function getManagedEntities() {
 143     return array();
 144   }
 145
 146   /**
 147    * Provides permissions that are unwise for Anonymous Roles to have
 148    *
 149    * @return array
 150    *   list of permissions
 151    * @see CRM_Component_Info::getPermissions
 152    */
 153   public function getAnonymousPermissionWarnings() {
 154     return array();
 155   }
 156
 157   /**
 158    * Provides permissions that are used by component.
 159    * Needs to be implemented in component's information
 160    * class.
 161    *
 162    * NOTE: if using conditionally permission return,
 163    * implementation of $getAllUnconditionally is required.
 164    *
 165    * @param bool $getAllUnconditionally
 166    *
 167    * @return array|null
 168    *   collection of permissions, null if none
 169    */
 170   abstract public function getPermissions($getAllUnconditionally = FALSE);
 171
 172   /**
 173    * Determine how many other records refer to a given record
 174    *
 175    * @param CRM_Core_DAO $dao
 176    *   The item for which we want a reference count.
 177    * @return array
 178    *   each item in the array is an array with keys:
 179    *   - name: string, eg "sql:civicrm_email:contact_id"
 180    *   - type: string, eg "sql"
 181    *   - count: int, eg "5" if there are 5 email addresses that refer to $dao
 182    */
 183   public function getReferenceCounts($dao) {
 184     return array();
 185   }
 186
 187   /**
 188    * Provides information about user dashboard element.
 189    * offered by this component.
 190    *
 191    * @return array|null
 192    *   collection of required dashboard settings,
 193    *                    null if no element offered
 194    */
 195   abstract public function getUserDashboardElement();
 196
 197   /**
 198    * Provides information about user dashboard element.
 199    * offered by this component.
 200    *
 201    * @return array|null
 202    *   collection of required dashboard settings,
 203    *                    null if no element offered
 204    */
 205   abstract public function registerTab();
 206
 207   /**
 208    * Provides information about advanced search pane
 209    * offered by this component.
 210    *
 211    * @return array|null
 212    *   collection of required pane settings,
 213    *                    null if no element offered
 214    */
 215   abstract public function registerAdvancedSearchPane();
 216
 217   /**
 218    * Provides potential activity types that this
 219    * component might want to register in activity history.
 220    * Needs to be implemented in component's information
 221    * class.
 222    *
 223    * @return array|null
 224    *   collection of activity types
 225    */
 226   abstract public function getActivityTypes();
 227
 228   /**
 229    * Provides information whether given component is currently
 230    * marked as enabled in configuration.
 231    *
 232    * @return bool
 233    *   true if component is enabled, false if not
 234    */
 235   public function isEnabled() {
 236     $config = CRM_Core_Config::singleton();
 237     if (in_array($this->info['name'], $config->enableComponents)) {
 238       return TRUE;
 239     }
 240     return FALSE;
 241   }
 242
 243   /**
 244    * Provides component's configuration object.
 245    *
 246    * @return mixed
 247    *   component's configuration object
 248    */
 249   public function getConfigObject() {
 250     return $this->_instantiate(self::COMPONENT_CONFIG_CLASS);
 251   }
 252
 253   /**
 254    * Provides component's menu definition object.
 255    *
 256    * @return mixed
 257    *   component's menu definition object
 258    */
 259   public function getMenuObject() {
 260     return $this->_instantiate(self::COMPONENT_MENU_CLASS);
 261   }
 262
 263   /**
 264    * Provides component's invocation object.
 265    *
 266    * @return mixed
 267    *   component's invocation object
 268    */
 269   public function getInvokeObject() {
 270     return $this->_instantiate(self::COMPONENT_INVOKE_CLASS);
 271   }
 272
 273   /**
 274    * Provides component's BAO Query object.
 275    *
 276    * @return mixed
 277    *   component's BAO Query object
 278    */
 279   public function getBAOQueryObject() {
 280     return $this->_instantiate(self::COMPONENT_BAO_QUERY_CLASS);
 281   }
 282
 283   /**
 284    * Builds advanced search form's component specific pane.
 285    */
 286   public function buildAdvancedSearchPaneForm(&$form) {
 287     $bao = $this->getBAOQueryObject();
 288     $bao->buildSearchForm($form);
 289   }
 290
 291   /**
 292    * Provides component's user dashboard page object.
 293    *
 294    * @return mixed
 295    *   component's User Dashboard applet object
 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
 305    *   component's contact record tab object
 306    */
 307   public function getTabObject() {
 308     return $this->_instantiate(self::COMPONENT_TAB_CLASS);
 309   }
 310
 311   /**
 312    * Provides component's advanced search pane's template path.
 313    *
 314    * @return string
 315    *   component's advanced search pane's template path
 316    */
 317   public function getAdvancedSearchPaneTemplatePath() {
 318     $fullpath = $this->namespace . '_' . self::COMPONENT_ADVSEARCHPANE_CLASS;
 319     return str_replace('_', DIRECTORY_SEPARATOR, $fullpath . '.tpl');
 320   }
 321
 322   /**
 323    * Provides information whether given component uses system wide search.
 324    *
 325    * @return bool
 326    *   true if component needs search integration
 327    */
 328   public function usesSearch() {
 329     return $this->info['search'] ? TRUE : FALSE;
 330   }
 331
 332   /**
 333    * Provides the xml menu files
 334    *
 335    * @return array
 336    *   array of menu files
 337    */
 338   public function menuFiles() {
 339     return CRM_Utils_File::getFilesByExtension($this->_getMenuXMLPath(), 'xml');
 340   }
 341
 342   /**
 343    * Simple "keyword" getter.
 344    * FIXME: It should be protected so the keyword is not
 345    * FIXME: accessed from beyond component infrastructure.
 346    *
 347    * @return string
 348    *   component keyword
 349    */
 350   public function getKeyword() {
 351     return $this->keyword;
 352   }
 353
 354   /**
 355    * Helper for figuring out menu XML file location.
 356    *
 357    * @return mixed
 358    *   component's element as class instance
 359    */
 360   private function _getMenuXMLPath() {
 361     global $civicrm_root;
 362     $fullpath = $this->namespace . '_' . self::COMPONENT_XML_RESOURCES . '_' . self::COMPONENT_MENU_XML;
 363     return CRM_Utils_File::addTrailingSlash($civicrm_root . DIRECTORY_SEPARATOR . str_replace('_', DIRECTORY_SEPARATOR, $fullpath));
 364   }
 365
 366   /**
 367    * Helper for instantiating component's elements.
 368    *
 369    * @param $cl
 370    *
 371    * @return mixed
 372    *   component's element as class instance
 373    */
 374   private function _instantiate($cl) {
 375     $className = $this->namespace . '_' . $cl;
 376     require_once str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
 377     return new $className();
 378   }
 379
 380 }