3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
13 * Class CRM_Core_Resources_CollectionTrait
15 * This trait is a building-block for creating classes which maintain a list of
16 * resources. It defines a set of helper functions which provide syntactic sugar
17 * for calling the add() method. It implements most of the `CollectionAdderInterface`.
19 * @see CRM_Core_Resources_CollectionAdderInterface
21 trait CRM_Core_Resources_CollectionAdderTrait
{
24 * Add an item to the collection.
26 * @param array $snippet
28 * The full/computed snippet (with defaults applied).
29 * @see CRM_Core_Resources_CollectionInterface::add()
30 * @see CRM_Core_Resources_CollectionTrait::add()
32 abstract public function add($snippet);
35 * Locate the 'settings' snippet.
37 * @param array $options
39 * @see CRM_Core_Resources_CollectionTrait::findCreateSettingSnippet()
41 abstract public function &findCreateSettingSnippet($options = []): array;
46 * Ex: addMarkup('<p>Hello world!</p>', ['weight' => 123]);
48 * @param string $markup
50 * @param array $options
51 * Open-ended list of key-value options. See CollectionInterface docs.
52 * Positional equivalence: addMarkup(string $code, int $weight, string $region).
54 * @see CRM_Core_Resources_CollectionInterface
55 * @see CRM_Core_Resources_CollectionAdderInterface::addMarkup()
57 public function addMarkup(string $markup, ...$options) {
58 $this->add(self
::mergeStandardOptions($options, [
65 * Export permission data to the client to enable smarter GUIs.
67 * @param string|iterable $permNames
68 * List of permission names to check/export.
70 * @see CRM_Core_Resources_CollectionAdderInterface::addPermissions()
72 public function addPermissions($permNames) {
73 // TODO: Maybe this should be its own resource type to allow smarter management?
74 $permNames = is_scalar($permNames) ?
[$permNames] : $permNames;
77 foreach ($permNames as $permName) {
78 $perms[$permName] = CRM_Core_Permission
::check($permName);
80 return $this->addSetting([
81 'permissions' => $perms,
86 * Add a JavaScript file to the current page using <SCRIPT SRC>.
88 * Ex: addScript('alert("Hello world");', ['weight' => 123]);
91 * JavaScript source code.
92 * @param array $options
93 * Open-ended list of key-value options. See CollectionInterface docs.
94 * Positional equivalence: addScript(string $code, int $weight, string $region).
96 * @see CRM_Core_Resources_CollectionInterface
97 * @see CRM_Core_Resources_CollectionAdderInterface::addScript()
99 public function addScript(string $code, ...$options) {
100 $this->add(self
::mergeStandardOptions($options, [
107 * Add a JavaScript file to the current page using <SCRIPT SRC>.
109 * Ex: addScriptFile('myextension', 'myscript.js', ['weight' => 123]);
112 * Extension name; use 'civicrm' for core.
113 * @param string $file
114 * File path -- relative to the extension base dir.
115 * @param array $options
116 * Open-ended list of key-value options. See CollectionInterface docs.
117 * Positional equivalence: addScriptFile(string $code, int $weight, string $region, mixed $translate).
119 * @see CRM_Core_Resources_CollectionInterface
120 * @see CRM_Core_Resources_CollectionAdderInterface::addScriptFile()
122 public function addScriptFile(string $ext, string $file, ...$options) {
123 $this->add(self
::mergeStandardOptions($options, [
124 'scriptFile' => [$ext, $file],
125 'name' => "$ext:$file",
126 // Setting the name above may appear superfluous, but it preserves a historical quirk
127 // where Region::add() and Resources::addScriptFile() produce slightly different orderings.
133 * Add a JavaScript URL to the current page using <SCRIPT SRC>.
135 * Ex: addScriptUrl('http://example.com/foo.js', ['weight' => 123])
138 * @param array $options
139 * Open-ended list of key-value options. See CollectionInterface docs.
140 * Positional equivalence: addScriptUrl(string $url, int $weight, string $region).
142 * @see CRM_Core_Resources_CollectionInterface
143 * @see CRM_Core_Resources_CollectionAdderInterface::addScriptUrl()
145 public function addScriptUrl(string $url, ...$options) {
146 $this->add(self
::mergeStandardOptions($options, [
149 // Setting the name above may appear superfluous, but it preserves a historical quirk
150 // where Region::add() and Resources::addScriptUrl() produce slightly different orderings.
156 * Add translated string to the js CRM object.
157 * It can then be retrived from the client-side ts() function
158 * Variable substitutions can happen from client-side
160 * Note: this function rarely needs to be called directly and is mostly for internal use.
161 * See CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files
165 * CRM_Core_Resources::singleton()->addString('Hello');
166 * // The string is now available to javascript code i.e.
169 * Example with client-side substitutions:
171 * CRM_Core_Resources::singleton()->addString('Your %1 has been %2');
172 * // ts() in javascript works the same as in php, for example:
173 * ts('Your %1 has been %2', {1: objectName, 2: actionTaken});
175 * NOTE: This function does not work with server-side substitutions
176 * (as this might result in collisions and unwanted variable injections)
177 * Instead, use code like:
178 * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs)))));
179 * And from javascript access it at CRM.myNamespace.myString
181 * @param string|array $text
182 * @param string|null $domain
184 * @see CRM_Core_Resources_CollectionAdderInterface::addString()
186 public function addString($text, $domain = 'civicrm') {
187 // TODO: Maybe this should be its own resource type to allow smarter management?
189 foreach ((array) $text as $str) {
190 $translated = ts($str, [
191 'domain' => ($domain == 'civicrm') ?
NULL : [$domain, NULL],
195 // We only need to push this string to client if the translation
196 // is actually different from the original
197 if ($translated != $str) {
198 $bucket = $domain == 'civicrm' ?
'strings' : 'strings::' . $domain;
200 $bucket => [$str => $translated],
208 * Add a CSS content to the current page using <STYLE>.
210 * Ex: addStyle('p { color: red; }', ['weight' => 100]);
212 * @param string $code
214 * @param array $options
215 * Open-ended list of key-value options. See CollectionInterface docs.
216 * Positional equivalence: addStyle(string $code, int $weight, string $region).
218 * @see CRM_Core_Resources_CollectionInterface
219 * @see CRM_Core_Resources_CollectionAdderInterface::addStyle()
221 public function addStyle(string $code, ...$options) {
222 $this->add(self
::mergeStandardOptions($options, [
229 * Add a CSS file to the current page using <LINK HREF>.
231 * Ex: addStyleFile('myextension', 'mystyles.css', ['weight' => 100]);
234 * Extension name; use 'civicrm' for core.
235 * @param string $file
236 * File path -- relative to the extension base dir.
237 * @param array $options
238 * Open-ended list of key-value options. See CollectionInterface docs.
239 * Positional equivalence: addStyle(string $code, int $weight, string $region).
241 * @see CRM_Core_Resources_CollectionInterface
242 * @see CRM_Core_Resources_CollectionAdderInterface::addStyleFile()
244 public function addStyleFile(string $ext, string $file, ...$options) {
245 $this->add(self
::mergeStandardOptions($options, [
246 'styleFile' => [$ext, $file],
247 'name' => "$ext:$file",
248 // Setting the name above may appear superfluous, but it preserves a historical quirk
249 // where Region::add() and Resources::addScriptUrl() produce slightly different orderings.
255 * Add a CSS file to the current page using <LINK HREF>.
257 * Ex: addStyleUrl('http://example.com/foo.css', ['weight' => 100]);
260 * @param array $options
261 * Open-ended list of key-value options. See CollectionInterface docs.
262 * Positional equivalence: addStyleUrl(string $code, int $weight, string $region).
264 * @see CRM_Core_Resources_CollectionInterface
265 * @see CRM_Core_Resources_CollectionAdderInterface::addStyleUrl()
267 public function addStyleUrl(string $url, ...$options) {
268 $this->add(self
::mergeStandardOptions($options, [
271 // Setting the name above may appear superfluous, but it preserves a historical quirk
272 // where Region::add() and Resources::addScriptUrl() produce slightly different orderings.
278 * Add JavaScript variables to the root of the CRM object.
279 * This function is usually reserved for low-level system use.
280 * Extensions and components should generally use addVars instead.
282 * @param array $settings
284 * @param array $options
286 * Positional equivalence: addSetting(array $settings, string $region).
288 * @see CRM_Core_Resources_CollectionInterface
289 * @see CRM_Core_Resources_CollectionAdderInterface::addSetting()
291 public function addSetting(array $settings, ...$options) {
292 $s = &$this->findCreateSettingSnippet($options);
293 $s['settings'] = self
::mergeSettings($s['settings'], $settings);
298 * Add JavaScript variables to the global CRM object via a callback function.
300 * @param callable $callable
302 * @see CRM_Core_Resources_CollectionAdderInterface::addSettingsFactory()
304 public function addSettingsFactory($callable) {
305 $s = &$this->findCreateSettingSnippet();
306 $s['settingsFactories'][] = $callable;
311 * Add JavaScript variables to CRM.vars
315 * CRM_Core_Resources::singleton()->addVars('myNamespace', array('foo' => 'bar'));
316 * Access var from javascript:
317 * CRM.vars.myNamespace.foo // "bar"
319 * @see https://docs.civicrm.org/dev/en/latest/standards/javascript/
321 * @param string $nameSpace
322 * Usually the name of your extension.
325 * @param array $options
326 * Open-ended list of key-value options. See CollectionInterface docs.
327 * Positional equivalence: addVars(string $namespace, array $vars, string $region).
329 * @see CRM_Core_Resources_CollectionInterface
330 * @see CRM_Core_Resources_CollectionAdderInterface::addVars()
332 public function addVars(string $nameSpace, array $vars, ...$options) {
333 $s = &$this->findCreateSettingSnippet($options);
334 $s['settings']['vars'][$nameSpace] = self
::mergeSettings(
335 $s['settings']['vars'][$nameSpace] ??
[],
342 * Given the "$options" for "addScriptUrl()" (etal), normalize the contents
343 * and potentially add more.
345 * @param array $splats
346 * A list of options, as represented by the splat mechanism ("...$options").
347 * This may appear in one of two ways:
348 * - New (String Index): as in `addFoo($foo, array $options)`
349 * - Old (Numeric Index): as in `addFoo($foo, int $weight = X, string $region = Y, bool $translate = X)`
350 * @param array $defaults
351 * List of values to merge into $options.
354 public static function mergeStandardOptions(array $splats, array $defaults = []) {
355 $count = count($splats);
358 // Common+simple case: No splat options. We can short-circuit.
362 // Might be new format (key-value pairs) or old format
363 $parsed = is_array($splats[0]) ?
$splats[0] : ['weight' => $splats[0]];
367 $parsed = ['weight' => $splats[0], 'region' => $splats[1]];
371 $parsed = ['weight' => $splats[0], 'region' => $splats[1], 'translate' => $splats[2]];
375 throw new \
RuntimeException("Cannot resolve resource options. For clearest behavior, pass options in key-value format.");
378 return array_merge($defaults, $parsed);
382 * Given the "$options" for "addSetting()" (etal), normalize the contents
383 * and potentially add more.
385 * @param array $splats
386 * A list of options, as represented by the splat mechanism ("...$options").
387 * This may appear in one of two ways:
388 * - New (String Index): as in `addFoo($foo, array $options)`
389 * - Old (Numeric Index): as in `addFoo($foo, int $weight = X, string $region = Y, bool $translate = X)`
390 * @param array $defaults
391 * List of values to merge into $options.
394 public static function mergeSettingOptions(array $splats, array $defaults = []) {
395 $count = count($splats);
398 // Common+simple case: No splat options. We can short-circuit.
402 // Might be new format (key-value pairs) or old format
403 $parsed = is_array($splats[0]) ?
$splats[0] : ['region' => $splats[0]];
407 throw new \
RuntimeException("Cannot resolve resource options. For clearest behavior, pass options in key-value format.");
410 return array_merge($defaults, $parsed);
414 * @param array $settings
415 * @param array $additions
417 * combination of $settings and $additions
419 public static function mergeSettings(array $settings, array $additions): array {
420 foreach ($additions as $k => $v) {
421 if (isset($settings[$k]) && is_array($settings[$k]) && is_array($v)) {