CRM/Core/Component/Info.php

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