Commit | Line | Data |
---|---|---|
6a488035 TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
fee14197 | 4 | | CiviCRM version 5 | |
6a488035 | 5 | +--------------------------------------------------------------------+ |
6b83d5bd | 6 | | Copyright CiviCRM LLC (c) 2004-2019 | |
6a488035 TO |
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 | +--------------------------------------------------------------------+ | |
d25dd0ee | 26 | */ |
6a488035 TO |
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 | |
6b83d5bd | 33 | * @copyright CiviCRM LLC (c) 2004-2019 |
6a488035 | 34 | */ |
6a488035 TO |
35 | abstract class CRM_Core_Component_Info { |
36 | ||
c490a46a CW |
37 | /** |
38 | * Name of the class (minus component namespace path) | |
39 | * of the component invocation class'es name. | |
40 | */ | |
7da04cde | 41 | const COMPONENT_INVOKE_CLASS = 'Invoke'; |
6a488035 | 42 | |
c490a46a CW |
43 | /** |
44 | * Name of the class (minus component namespace path) | |
45 | * of the component BAO Query class'es name. | |
46 | */ | |
7da04cde | 47 | const COMPONENT_BAO_QUERY_CLASS = 'BAO_Query'; |
6a488035 | 48 | |
c490a46a CW |
49 | /** |
50 | * Name of the class (minus component namespace path) | |
51 | * of the component user dashboard plugin. | |
52 | */ | |
7da04cde | 53 | const COMPONENT_USERDASHBOARD_CLASS = 'Page_UserDashboard'; |
6a488035 | 54 | |
c490a46a CW |
55 | /** |
56 | * Name of the class (minus component namespace path) | |
57 | * of the component tab offered to contact record view. | |
58 | */ | |
7da04cde | 59 | const COMPONENT_TAB_CLASS = 'Page_Tab'; |
6a488035 | 60 | |
c490a46a CW |
61 | /** |
62 | * Name of the class (minus component namespace path) | |
63 | * of the component tab offered to contact record view. | |
64 | */ | |
7da04cde | 65 | const COMPONENT_ADVSEARCHPANE_CLASS = 'Form_Search_AdvancedSearchPane'; |
6a488035 | 66 | |
c490a46a CW |
67 | /** |
68 | * Name of the directory (assumed in component directory) | |
69 | * where xml resources used by this component live. | |
70 | */ | |
7da04cde | 71 | const COMPONENT_XML_RESOURCES = 'xml'; |
6a488035 | 72 | |
c490a46a CW |
73 | /** |
74 | * Name of the directory (assumed in xml resources path) | |
75 | * containing component menu definition XML file names. | |
76 | */ | |
7da04cde | 77 | const COMPONENT_MENU_XML = 'Menu'; |
6a488035 | 78 | |
c490a46a | 79 | /** |
cc101011 | 80 | * Component settings as key/value pairs. |
81 | * | |
82 | * @var array | |
6a488035 TO |
83 | */ |
84 | public $info; | |
85 | ||
d424ffde | 86 | /** |
cc101011 | 87 | * Component keyword. |
88 | * | |
89 | * @var string | |
6a488035 TO |
90 | */ |
91 | protected $keyword; | |
92 | ||
c490a46a | 93 | /** |
6a0b768e TO |
94 | * @param string $name |
95 | * Name of the component. | |
96 | * @param string $namespace | |
97 | * Namespace prefix for component's files. | |
c490a46a | 98 | * @param int $componentID |
a0ee3941 | 99 | */ |
6a488035 | 100 | public function __construct($name, $namespace, $componentID) { |
353ffa53 TO |
101 | $this->name = $name; |
102 | $this->namespace = $namespace; | |
6a488035 | 103 | $this->componentID = $componentID; |
353ffa53 | 104 | $this->info = $this->getInfo(); |
6a488035 TO |
105 | $this->info['url'] = $this->getKeyword(); |
106 | } | |
107 | ||
e7ff7042 TO |
108 | /** |
109 | * EXPERIMENTAL: Get a list of AngularJS modules | |
110 | * | |
a6c01b45 CW |
111 | * @return array |
112 | * list of modules; same format as CRM_Utils_Hook::angularModules(&$angularModules) | |
e7ff7042 TO |
113 | * @see CRM_Utils_Hook::angularModules |
114 | */ | |
115 | public function getAngularModules() { | |
be2fb01f | 116 | return []; |
e7ff7042 TO |
117 | } |
118 | ||
6a488035 TO |
119 | /** |
120 | * Provides base information about the component. | |
121 | * Needs to be implemented in component's information | |
122 | * class. | |
123 | * | |
a6c01b45 CW |
124 | * @return array |
125 | * collection of required component settings | |
6a488035 TO |
126 | */ |
127 | abstract public function getInfo(); | |
128 | ||
3bd831aa | 129 | /** |
fe482240 | 130 | * Get a list of entities to register via API. |
3bd831aa | 131 | * |
a6c01b45 CW |
132 | * @return array |
133 | * list of entities; same format as CRM_Utils_Hook::managedEntities(&$entities) | |
3bd831aa TO |
134 | * @see CRM_Utils_Hook::managedEntities |
135 | */ | |
136 | public function getManagedEntities() { | |
be2fb01f | 137 | return []; |
3bd831aa TO |
138 | } |
139 | ||
81bb85ea | 140 | /** |
fe482240 | 141 | * Provides permissions that are unwise for Anonymous Roles to have. |
81bb85ea | 142 | * |
a6c01b45 CW |
143 | * @return array |
144 | * list of permissions | |
81bb85ea AC |
145 | * @see CRM_Component_Info::getPermissions |
146 | */ | |
147 | public function getAnonymousPermissionWarnings() { | |
be2fb01f | 148 | return []; |
81bb85ea AC |
149 | } |
150 | ||
6a488035 TO |
151 | /** |
152 | * Provides permissions that are used by component. | |
153 | * Needs to be implemented in component's information | |
154 | * class. | |
155 | * | |
33777e4a PJ |
156 | * NOTE: if using conditionally permission return, |
157 | * implementation of $getAllUnconditionally is required. | |
dd244018 EM |
158 | * |
159 | * @param bool $getAllUnconditionally | |
160 | * | |
72b3a70c CW |
161 | * @return array|null |
162 | * collection of permissions, null if none | |
6a488035 | 163 | */ |
33777e4a | 164 | abstract public function getPermissions($getAllUnconditionally = FALSE); |
6a488035 | 165 | |
91dee34b | 166 | /** |
fe482240 | 167 | * Determine how many other records refer to a given record. |
91dee34b | 168 | * |
6a0b768e TO |
169 | * @param CRM_Core_DAO $dao |
170 | * The item for which we want a reference count. | |
a6c01b45 CW |
171 | * @return array |
172 | * each item in the array is an array with keys: | |
91dee34b TO |
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) { | |
be2fb01f | 178 | return []; |
91dee34b TO |
179 | } |
180 | ||
6a488035 | 181 | /** |
0880a9d0 | 182 | * Provides information about user dashboard element. |
6a488035 TO |
183 | * offered by this component. |
184 | * | |
72b3a70c CW |
185 | * @return array|null |
186 | * collection of required dashboard settings, | |
6a488035 | 187 | * null if no element offered |
6a488035 TO |
188 | */ |
189 | abstract public function getUserDashboardElement(); | |
190 | ||
191 | /** | |
0880a9d0 | 192 | * Provides information about user dashboard element. |
6a488035 TO |
193 | * offered by this component. |
194 | * | |
72b3a70c CW |
195 | * @return array|null |
196 | * collection of required dashboard settings, | |
6a488035 | 197 | * null if no element offered |
6a488035 TO |
198 | */ |
199 | abstract public function registerTab(); | |
200 | ||
b04115b4 CW |
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 | ||
6a488035 TO |
210 | /** |
211 | * Provides information about advanced search pane | |
212 | * offered by this component. | |
213 | * | |
72b3a70c CW |
214 | * @return array|null |
215 | * collection of required pane settings, | |
6a488035 | 216 | * null if no element offered |
6a488035 TO |
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 | * | |
72b3a70c CW |
226 | * @return array|null |
227 | * collection of activity types | |
6a488035 TO |
228 | */ |
229 | abstract public function getActivityTypes(); | |
230 | ||
231 | /** | |
232 | * Provides information whether given component is currently | |
233 | * marked as enabled in configuration. | |
234 | * | |
389bcebf | 235 | * @return bool |
a6c01b45 | 236 | * true if component is enabled, false if not |
6a488035 TO |
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 | ||
6a488035 TO |
246 | /** |
247 | * Provides component's menu definition object. | |
248 | * | |
72b3a70c CW |
249 | * @return mixed |
250 | * component's menu definition object | |
6a488035 TO |
251 | */ |
252 | public function getMenuObject() { | |
253 | return $this->_instantiate(self::COMPONENT_MENU_CLASS); | |
254 | } | |
255 | ||
256 | /** | |
257 | * Provides component's invocation object. | |
258 | * | |
72b3a70c CW |
259 | * @return mixed |
260 | * component's invocation object | |
6a488035 TO |
261 | */ |
262 | public function getInvokeObject() { | |
263 | return $this->_instantiate(self::COMPONENT_INVOKE_CLASS); | |
264 | } | |
265 | ||
266 | /** | |
267 | * Provides component's BAO Query object. | |
268 | * | |
72b3a70c CW |
269 | * @return mixed |
270 | * component's BAO Query object | |
6a488035 TO |
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. | |
ea3ddccf | 278 | * |
279 | * @param CRM_Core_Form $form | |
6a488035 TO |
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 | * | |
72b3a70c CW |
289 | * @return mixed |
290 | * component's User Dashboard applet object | |
6a488035 TO |
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 | * | |
72b3a70c CW |
299 | * @return mixed |
300 | * component's contact record tab object | |
6a488035 TO |
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 | * | |
a6c01b45 CW |
309 | * @return string |
310 | * component's advanced search pane's template path | |
6a488035 TO |
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 | * | |
389bcebf | 320 | * @return bool |
a6c01b45 | 321 | * true if component needs search integration |
6a488035 TO |
322 | */ |
323 | public function usesSearch() { | |
324 | return $this->info['search'] ? TRUE : FALSE; | |
325 | } | |
326 | ||
327 | /** | |
fe482240 | 328 | * Provides the xml menu files. |
6a488035 | 329 | * |
a6c01b45 CW |
330 | * @return array |
331 | * array of menu files | |
6a488035 TO |
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 | * | |
a6c01b45 CW |
342 | * @return string |
343 | * component keyword | |
6a488035 TO |
344 | */ |
345 | public function getKeyword() { | |
346 | return $this->keyword; | |
347 | } | |
348 | ||
349 | /** | |
350 | * Helper for figuring out menu XML file location. | |
351 | * | |
72b3a70c CW |
352 | * @return mixed |
353 | * component's element as class instance | |
6a488035 TO |
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 | * | |
77b97be7 EM |
364 | * @param $cl |
365 | * | |
72b3a70c CW |
366 | * @return mixed |
367 | * component's element as class instance | |
6a488035 TO |
368 | */ |
369 | private function _instantiate($cl) { | |
370 | $className = $this->namespace . '_' . $cl; | |
2aa397bc | 371 | require_once str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php'; |
6a488035 TO |
372 | return new $className(); |
373 | } | |
96025800 | 374 | |
6a488035 | 375 | } |