CRM/Core/Component/Info.php

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