Commit | Line | Data |
---|---|---|
060617e9 TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
4 | | Copyright CiviCRM LLC. All rights reserved. | | |
5 | | | | |
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 | +--------------------------------------------------------------------+ | |
10 | */ | |
11 | ||
12 | /** | |
13 | * The collection-adder interface provides write-only support for a collection. | |
950538ac TO |
14 | * |
15 | * @see CRM_Core_Resources_CollectionAdderTrait | |
060617e9 TO |
16 | */ |
17 | interface CRM_Core_Resources_CollectionAdderInterface { | |
18 | ||
19 | /** | |
20 | * Add an item to the collection. | |
21 | * | |
22 | * @param array $snippet | |
23 | * @return array | |
24 | * The full/computed snippet (with defaults applied). | |
25 | * @see CRM_Core_Resources_CollectionInterface::add() | |
26 | */ | |
27 | public function add($snippet); | |
28 | ||
29 | // TODO public function addBundle($bundle); | |
30 | ||
e564eac6 TO |
31 | /** |
32 | * Add an HTML blob. | |
33 | * | |
34 | * Ex: addMarkup('<p>Hello world!</p>', ['weight' => 123]); | |
35 | * | |
36 | * @param string $markup | |
37 | * HTML code. | |
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). | |
41 | * @return static | |
42 | * @see CRM_Core_Resources_CollectionInterface | |
43 | * @see CRM_Core_Resources_CollectionAdderInterface::addScript() | |
44 | */ | |
45 | public function addMarkup(string $markup, ...$options); | |
46 | ||
060617e9 TO |
47 | /** |
48 | * Export permission data to the client to enable smarter GUIs. | |
49 | * | |
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. | |
54 | * | |
55 | * @param string|iterable $permNames | |
56 | * List of permission names to check/export. | |
57 | * @return static | |
58 | */ | |
59 | public function addPermissions($permNames); | |
60 | ||
61 | /** | |
62 | * Add a JavaScript file to the current page using <SCRIPT SRC>. | |
63 | * | |
c8cbd3ba TO |
64 | * Ex: addScript('alert("Hello world");', ['weight' => 123]); |
65 | * | |
060617e9 TO |
66 | * @param string $code |
67 | * JavaScript source code. | |
68 | * @param array $options | |
c8cbd3ba TO |
69 | * Open-ended list of key-value options. See CollectionInterface docs. |
70 | * Positional equivalence: addScript(string $code, int $weight, string $region). | |
060617e9 | 71 | * @return static |
c8cbd3ba | 72 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
73 | */ |
74 | public function addScript(string $code, ...$options); | |
75 | ||
76 | /** | |
77 | * Add a JavaScript file to the current page using <SCRIPT SRC>. | |
78 | * | |
c8cbd3ba | 79 | * Ex: addScriptFile('myextension', 'myscript.js', ['weight' => 123]); |
060617e9 TO |
80 | * |
81 | * @param string $ext | |
c8cbd3ba | 82 | * Extension name; use 'civicrm' for core. |
060617e9 | 83 | * @param string $file |
c8cbd3ba | 84 | * File path -- relative to the extension base dir. |
060617e9 | 85 | * @param array $options |
c8cbd3ba TO |
86 | * Open-ended list of key-value options. See CollectionInterface docs. |
87 | * Positional equivalence: addScriptFile(string $code, int $weight, string $region, mixed $translate). | |
060617e9 | 88 | * @return static |
c8cbd3ba | 89 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
90 | */ |
91 | public function addScriptFile(string $ext, string $file, ...$options); | |
92 | ||
93 | /** | |
c8cbd3ba | 94 | * Add a JavaScript URL to the current page using <SCRIPT SRC>. |
060617e9 | 95 | * |
c8cbd3ba | 96 | * Ex: addScriptUrl('http://example.com/foo.js', ['weight' => 123]) |
060617e9 TO |
97 | * |
98 | * @param string $url | |
99 | * @param array $options | |
c8cbd3ba TO |
100 | * Open-ended list of key-value options. See CollectionInterface docs. |
101 | * Positional equivalence: addScriptUrl(string $url, int $weight, string $region). | |
060617e9 | 102 | * @return static |
c8cbd3ba | 103 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
104 | */ |
105 | public function addScriptUrl(string $url, ...$options); | |
106 | ||
107 | /** | |
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 | |
111 | * | |
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 | |
114 | * | |
115 | * Simple example: | |
116 | * // From php: | |
117 | * CRM_Core_Resources::singleton()->addString('Hello'); | |
118 | * // The string is now available to javascript code i.e. | |
119 | * ts('Hello'); | |
120 | * | |
121 | * Example with client-side substitutions: | |
122 | * // From php: | |
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}); | |
126 | * | |
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 | |
132 | * | |
133 | * @param string|array $text | |
134 | * @param string|null $domain | |
135 | * @return static | |
136 | */ | |
137 | public function addString($text, $domain = 'civicrm'); | |
138 | ||
139 | /** | |
140 | * Add a CSS content to the current page using <STYLE>. | |
141 | * | |
c8cbd3ba TO |
142 | * Ex: addStyle('p { color: red; }', ['weight' => 100]); |
143 | * | |
060617e9 TO |
144 | * @param string $code |
145 | * CSS source code. | |
146 | * @param array $options | |
c8cbd3ba TO |
147 | * Open-ended list of key-value options. See CollectionInterface docs. |
148 | * Positional equivalence: addStyle(string $code, int $weight, string $region). | |
060617e9 | 149 | * @return static |
c8cbd3ba | 150 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
151 | */ |
152 | public function addStyle(string $code, ...$options); | |
153 | ||
154 | /** | |
155 | * Add a CSS file to the current page using <LINK HREF>. | |
156 | * | |
c8cbd3ba TO |
157 | * Ex: addStyleFile('myextension', 'mystyles.css', ['weight' => 100]); |
158 | * | |
060617e9 | 159 | * @param string $ext |
c8cbd3ba | 160 | * Extension name; use 'civicrm' for core. |
060617e9 | 161 | * @param string $file |
c8cbd3ba | 162 | * File path -- relative to the extension base dir. |
060617e9 | 163 | * @param array $options |
c8cbd3ba TO |
164 | * Open-ended list of key-value options. See CollectionInterface docs. |
165 | * Positional equivalence: addStyle(string $code, int $weight, string $region). | |
060617e9 | 166 | * @return static |
c8cbd3ba | 167 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
168 | */ |
169 | public function addStyleFile(string $ext, string $file, ...$options); | |
170 | ||
171 | /** | |
172 | * Add a CSS file to the current page using <LINK HREF>. | |
173 | * | |
c8cbd3ba TO |
174 | * Ex: addStyleUrl('http://example.com/foo.css', ['weight' => 100]); |
175 | * | |
060617e9 TO |
176 | * @param string $url |
177 | * @param array $options | |
c8cbd3ba TO |
178 | * Open-ended list of key-value options. See CollectionInterface docs. |
179 | * Positional equivalence: addStyleUrl(string $code, int $weight, string $region). | |
060617e9 | 180 | * @return static |
c8cbd3ba | 181 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
182 | */ |
183 | public function addStyleUrl(string $url, ...$options); | |
184 | ||
185 | /** | |
186 | * Add JavaScript variables to CRM.vars | |
187 | * | |
188 | * Example: | |
c8cbd3ba TO |
189 | * From the server: |
190 | * CRM_Core_Resources::singleton()->addVars('myNamespace', array('foo' => 'bar')); | |
191 | * Access var from javascript: | |
192 | * CRM.vars.myNamespace.foo // "bar" | |
060617e9 TO |
193 | * |
194 | * @see https://docs.civicrm.org/dev/en/latest/standards/javascript/ | |
195 | * | |
196 | * @param string $nameSpace | |
197 | * Usually the name of your extension. | |
198 | * @param array $vars | |
199 | * Data to export. | |
200 | * @param array $options | |
c8cbd3ba TO |
201 | * Open-ended list of key-value options. See CollectionInterface docs. |
202 | * Positional equivalence: addVars(string $namespace, array $vars, string $region). | |
060617e9 | 203 | * @return static |
c8cbd3ba | 204 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
205 | */ |
206 | public function addVars(string $nameSpace, array $vars, ...$options); | |
207 | ||
208 | /** | |
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. | |
212 | * | |
213 | * @param array $settings | |
214 | * Data to export. | |
215 | * @param array $options | |
c8cbd3ba TO |
216 | * Not used. |
217 | * Positional equivalence: addSetting(array $settings, string $region). | |
060617e9 | 218 | * @return static |
c8cbd3ba TO |
219 | * @see CRM_Core_Resources_CollectionInterface |
220 | * @see CRM_Core_Resources_CollectionAdderInterface::addSetting() | |
060617e9 TO |
221 | */ |
222 | public function addSetting(array $settings, ...$options); | |
223 | ||
224 | /** | |
225 | * Add JavaScript variables to the global CRM object via a callback function. | |
226 | * | |
227 | * @param callable $callable | |
228 | * @return static | |
229 | */ | |
230 | public function addSettingsFactory($callable); | |
231 | ||
232 | } |