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