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 | ||
31 | /** | |
32 | * Export permission data to the client to enable smarter GUIs. | |
33 | * | |
34 | * Note: Application security stems from the server's enforcement | |
35 | * of the security logic (e.g. in the API permissions). There's no way | |
36 | * the client can use this info to make the app more secure; however, | |
37 | * it can produce a better-tuned (non-broken) UI. | |
38 | * | |
39 | * @param string|iterable $permNames | |
40 | * List of permission names to check/export. | |
41 | * @return static | |
42 | */ | |
43 | public function addPermissions($permNames); | |
44 | ||
45 | /** | |
46 | * Add a JavaScript file to the current page using <SCRIPT SRC>. | |
47 | * | |
c8cbd3ba TO |
48 | * Ex: addScript('alert("Hello world");', ['weight' => 123]); |
49 | * | |
060617e9 TO |
50 | * @param string $code |
51 | * JavaScript source code. | |
52 | * @param array $options | |
c8cbd3ba TO |
53 | * Open-ended list of key-value options. See CollectionInterface docs. |
54 | * Positional equivalence: addScript(string $code, int $weight, string $region). | |
060617e9 | 55 | * @return static |
c8cbd3ba | 56 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
57 | */ |
58 | public function addScript(string $code, ...$options); | |
59 | ||
60 | /** | |
61 | * Add a JavaScript file to the current page using <SCRIPT SRC>. | |
62 | * | |
c8cbd3ba | 63 | * Ex: addScriptFile('myextension', 'myscript.js', ['weight' => 123]); |
060617e9 TO |
64 | * |
65 | * @param string $ext | |
c8cbd3ba | 66 | * Extension name; use 'civicrm' for core. |
060617e9 | 67 | * @param string $file |
c8cbd3ba | 68 | * File path -- relative to the extension base dir. |
060617e9 | 69 | * @param array $options |
c8cbd3ba TO |
70 | * Open-ended list of key-value options. See CollectionInterface docs. |
71 | * Positional equivalence: addScriptFile(string $code, int $weight, string $region, mixed $translate). | |
060617e9 | 72 | * @return static |
c8cbd3ba | 73 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
74 | */ |
75 | public function addScriptFile(string $ext, string $file, ...$options); | |
76 | ||
77 | /** | |
c8cbd3ba | 78 | * Add a JavaScript URL to the current page using <SCRIPT SRC>. |
060617e9 | 79 | * |
c8cbd3ba | 80 | * Ex: addScriptUrl('http://example.com/foo.js', ['weight' => 123]) |
060617e9 TO |
81 | * |
82 | * @param string $url | |
83 | * @param array $options | |
c8cbd3ba TO |
84 | * Open-ended list of key-value options. See CollectionInterface docs. |
85 | * Positional equivalence: addScriptUrl(string $url, int $weight, string $region). | |
060617e9 | 86 | * @return static |
c8cbd3ba | 87 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
88 | */ |
89 | public function addScriptUrl(string $url, ...$options); | |
90 | ||
91 | /** | |
92 | * Add translated string to the js CRM object. | |
93 | * It can then be retrived from the client-side ts() function | |
94 | * Variable substitutions can happen from client-side | |
95 | * | |
96 | * Note: this function rarely needs to be called directly and is mostly for internal use. | |
97 | * See CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files | |
98 | * | |
99 | * Simple example: | |
100 | * // From php: | |
101 | * CRM_Core_Resources::singleton()->addString('Hello'); | |
102 | * // The string is now available to javascript code i.e. | |
103 | * ts('Hello'); | |
104 | * | |
105 | * Example with client-side substitutions: | |
106 | * // From php: | |
107 | * CRM_Core_Resources::singleton()->addString('Your %1 has been %2'); | |
108 | * // ts() in javascript works the same as in php, for example: | |
109 | * ts('Your %1 has been %2', {1: objectName, 2: actionTaken}); | |
110 | * | |
111 | * NOTE: This function does not work with server-side substitutions | |
112 | * (as this might result in collisions and unwanted variable injections) | |
113 | * Instead, use code like: | |
114 | * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs))))); | |
115 | * And from javascript access it at CRM.myNamespace.myString | |
116 | * | |
117 | * @param string|array $text | |
118 | * @param string|null $domain | |
119 | * @return static | |
120 | */ | |
121 | public function addString($text, $domain = 'civicrm'); | |
122 | ||
123 | /** | |
124 | * Add a CSS content to the current page using <STYLE>. | |
125 | * | |
c8cbd3ba TO |
126 | * Ex: addStyle('p { color: red; }', ['weight' => 100]); |
127 | * | |
060617e9 TO |
128 | * @param string $code |
129 | * CSS source code. | |
130 | * @param array $options | |
c8cbd3ba TO |
131 | * Open-ended list of key-value options. See CollectionInterface docs. |
132 | * Positional equivalence: addStyle(string $code, int $weight, string $region). | |
060617e9 | 133 | * @return static |
c8cbd3ba | 134 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
135 | */ |
136 | public function addStyle(string $code, ...$options); | |
137 | ||
138 | /** | |
139 | * Add a CSS file to the current page using <LINK HREF>. | |
140 | * | |
c8cbd3ba TO |
141 | * Ex: addStyleFile('myextension', 'mystyles.css', ['weight' => 100]); |
142 | * | |
060617e9 | 143 | * @param string $ext |
c8cbd3ba | 144 | * Extension name; use 'civicrm' for core. |
060617e9 | 145 | * @param string $file |
c8cbd3ba | 146 | * File path -- relative to the extension base dir. |
060617e9 | 147 | * @param array $options |
c8cbd3ba TO |
148 | * Open-ended list of key-value options. See CollectionInterface docs. |
149 | * Positional equivalence: addStyle(string $code, int $weight, string $region). | |
060617e9 | 150 | * @return static |
c8cbd3ba | 151 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
152 | */ |
153 | public function addStyleFile(string $ext, string $file, ...$options); | |
154 | ||
155 | /** | |
156 | * Add a CSS file to the current page using <LINK HREF>. | |
157 | * | |
c8cbd3ba TO |
158 | * Ex: addStyleUrl('http://example.com/foo.css', ['weight' => 100]); |
159 | * | |
060617e9 TO |
160 | * @param string $url |
161 | * @param array $options | |
c8cbd3ba TO |
162 | * Open-ended list of key-value options. See CollectionInterface docs. |
163 | * Positional equivalence: addStyleUrl(string $code, int $weight, string $region). | |
060617e9 | 164 | * @return static |
c8cbd3ba | 165 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
166 | */ |
167 | public function addStyleUrl(string $url, ...$options); | |
168 | ||
169 | /** | |
170 | * Add JavaScript variables to CRM.vars | |
171 | * | |
172 | * Example: | |
c8cbd3ba TO |
173 | * From the server: |
174 | * CRM_Core_Resources::singleton()->addVars('myNamespace', array('foo' => 'bar')); | |
175 | * Access var from javascript: | |
176 | * CRM.vars.myNamespace.foo // "bar" | |
060617e9 TO |
177 | * |
178 | * @see https://docs.civicrm.org/dev/en/latest/standards/javascript/ | |
179 | * | |
180 | * @param string $nameSpace | |
181 | * Usually the name of your extension. | |
182 | * @param array $vars | |
183 | * Data to export. | |
184 | * @param array $options | |
c8cbd3ba TO |
185 | * Open-ended list of key-value options. See CollectionInterface docs. |
186 | * Positional equivalence: addVars(string $namespace, array $vars, string $region). | |
060617e9 | 187 | * @return static |
c8cbd3ba | 188 | * @see CRM_Core_Resources_CollectionInterface |
060617e9 TO |
189 | */ |
190 | public function addVars(string $nameSpace, array $vars, ...$options); | |
191 | ||
192 | /** | |
193 | * Add JavaScript variables to the root of the CRM object. | |
194 | * This function is usually reserved for low-level system use. | |
195 | * Extensions and components should generally use addVars instead. | |
196 | * | |
197 | * @param array $settings | |
198 | * Data to export. | |
199 | * @param array $options | |
c8cbd3ba TO |
200 | * Not used. |
201 | * Positional equivalence: addSetting(array $settings, string $region). | |
060617e9 | 202 | * @return static |
c8cbd3ba TO |
203 | * @see CRM_Core_Resources_CollectionInterface |
204 | * @see CRM_Core_Resources_CollectionAdderInterface::addSetting() | |
060617e9 TO |
205 | */ |
206 | public function addSetting(array $settings, ...$options); | |
207 | ||
208 | /** | |
209 | * Add JavaScript variables to the global CRM object via a callback function. | |
210 | * | |
211 | * @param callable $callable | |
212 | * @return static | |
213 | */ | |
214 | public function addSettingsFactory($callable); | |
215 | ||
216 | } |