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 * The collection-adder interface provides write-only support for a collection.
15 * @see CRM_Core_Resources_CollectionAdderTrait
17 interface CRM_Core_Resources_CollectionAdderInterface
{
20 * Add an item to the collection.
22 * @param array $snippet
24 * The full/computed snippet (with defaults applied).
25 * @see CRM_Core_Resources_CollectionInterface::add()
27 public function add($snippet);
29 // TODO public function addBundle($bundle);
34 * Ex: addMarkup('<p>Hello world!</p>', ['weight' => 123]);
36 * @param string $markup
38 * @param array $options
39 * Open-ended list of key-value options. See CollectionInterface docs.
40 * Positional equivalence: addMarkup(string $code, int $weight, string $region).
42 * @see CRM_Core_Resources_CollectionInterface
43 * @see CRM_Core_Resources_CollectionAdderInterface::addScript()
45 public function addMarkup(string $markup, ...$options);
48 * Export permission data to the client to enable smarter GUIs.
50 * Note: Application security stems from the server's enforcement
51 * of the security logic (e.g. in the API permissions). There's no way
52 * the client can use this info to make the app more secure; however,
53 * it can produce a better-tuned (non-broken) UI.
55 * @param string|iterable $permNames
56 * List of permission names to check/export.
59 public function addPermissions($permNames);
62 * Add a JavaScript file to the current page using <SCRIPT SRC>.
64 * Ex: addScript('alert("Hello world");', ['weight' => 123]);
67 * JavaScript source code.
68 * @param array $options
69 * Open-ended list of key-value options. See CollectionInterface docs.
70 * Positional equivalence: addScript(string $code, int $weight, string $region).
72 * @see CRM_Core_Resources_CollectionInterface
74 public function addScript(string $code, ...$options);
77 * Add a JavaScript file to the current page using <SCRIPT SRC>.
79 * Ex: addScriptFile('myextension', 'myscript.js', ['weight' => 123]);
82 * Extension name; use 'civicrm' for core.
84 * File path -- relative to the extension base dir.
85 * @param array $options
86 * Open-ended list of key-value options. See CollectionInterface docs.
87 * Positional equivalence: addScriptFile(string $code, int $weight, string $region, mixed $translate).
89 * @see CRM_Core_Resources_CollectionInterface
91 public function addScriptFile(string $ext, string $file, ...$options);
94 * Add a JavaScript URL to the current page using <SCRIPT SRC>.
96 * Ex: addScriptUrl('http://example.com/foo.js', ['weight' => 123])
99 * @param array $options
100 * Open-ended list of key-value options. See CollectionInterface docs.
101 * Positional equivalence: addScriptUrl(string $url, int $weight, string $region).
103 * @see CRM_Core_Resources_CollectionInterface
105 public function addScriptUrl(string $url, ...$options);
108 * Add translated string to the js CRM object.
109 * It can then be retrived from the client-side ts() function
110 * Variable substitutions can happen from client-side
112 * Note: this function rarely needs to be called directly and is mostly for internal use.
113 * See CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files
117 * CRM_Core_Resources::singleton()->addString('Hello');
118 * // The string is now available to javascript code i.e.
121 * Example with client-side substitutions:
123 * CRM_Core_Resources::singleton()->addString('Your %1 has been %2');
124 * // ts() in javascript works the same as in php, for example:
125 * ts('Your %1 has been %2', {1: objectName, 2: actionTaken});
127 * NOTE: This function does not work with server-side substitutions
128 * (as this might result in collisions and unwanted variable injections)
129 * Instead, use code like:
130 * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs)))));
131 * And from javascript access it at CRM.myNamespace.myString
133 * @param string|array $text
134 * @param string|null $domain
137 public function addString($text, $domain = 'civicrm');
140 * Add a CSS content to the current page using <STYLE>.
142 * Ex: addStyle('p { color: red; }', ['weight' => 100]);
144 * @param string $code
146 * @param array $options
147 * Open-ended list of key-value options. See CollectionInterface docs.
148 * Positional equivalence: addStyle(string $code, int $weight, string $region).
150 * @see CRM_Core_Resources_CollectionInterface
152 public function addStyle(string $code, ...$options);
155 * Add a CSS file to the current page using <LINK HREF>.
157 * Ex: addStyleFile('myextension', 'mystyles.css', ['weight' => 100]);
160 * Extension name; use 'civicrm' for core.
161 * @param string $file
162 * File path -- relative to the extension base dir.
163 * @param array $options
164 * Open-ended list of key-value options. See CollectionInterface docs.
165 * Positional equivalence: addStyle(string $code, int $weight, string $region).
167 * @see CRM_Core_Resources_CollectionInterface
169 public function addStyleFile(string $ext, string $file, ...$options);
172 * Add a CSS file to the current page using <LINK HREF>.
174 * Ex: addStyleUrl('http://example.com/foo.css', ['weight' => 100]);
177 * @param array $options
178 * Open-ended list of key-value options. See CollectionInterface docs.
179 * Positional equivalence: addStyleUrl(string $code, int $weight, string $region).
181 * @see CRM_Core_Resources_CollectionInterface
183 public function addStyleUrl(string $url, ...$options);
186 * Add JavaScript variables to CRM.vars
190 * CRM_Core_Resources::singleton()->addVars('myNamespace', array('foo' => 'bar'));
191 * Access var from javascript:
192 * CRM.vars.myNamespace.foo // "bar"
194 * @see https://docs.civicrm.org/dev/en/latest/standards/javascript/
196 * @param string $nameSpace
197 * Usually the name of your extension.
200 * @param array $options
201 * Open-ended list of key-value options. See CollectionInterface docs.
202 * Positional equivalence: addVars(string $namespace, array $vars, string $region).
204 * @see CRM_Core_Resources_CollectionInterface
206 public function addVars(string $nameSpace, array $vars, ...$options);
209 * Add JavaScript variables to the root of the CRM object.
210 * This function is usually reserved for low-level system use.
211 * Extensions and components should generally use addVars instead.
213 * @param array $settings
215 * @param array $options
217 * Positional equivalence: addSetting(array $settings, string $region).
219 * @see CRM_Core_Resources_CollectionInterface
220 * @see CRM_Core_Resources_CollectionAdderInterface::addSetting()
222 public function addSetting(array $settings, ...$options);
225 * Add JavaScript variables to the global CRM object via a callback function.
227 * @param callable $callable
230 public function addSettingsFactory($callable);