[civicrm-core.git] / CRM / Core / Resources / CollectionAdderInterface.php

<?php
/*
 +--------------------------------------------------------------------+
 | Copyright CiviCRM LLC. All rights reserved.                        |
 |                                                                    |
 | This work is published under the GNU AGPLv3 license with some      |
 | permitted exceptions and without any warranty. For full license    |
 | and copyright information, see https://civicrm.org/licensing       |
 +--------------------------------------------------------------------+
 */

/**
 * The collection-adder interface provides write-only support for a collection.
 *
 * @see CRM_Core_Resources_CollectionAdderTrait
 */
interface CRM_Core_Resources_CollectionAdderInterface {

  /**
   * Add an item to the collection.
   *
   * @param array $snippet
   * @return array
   *   The full/computed snippet (with defaults applied).
   * @see CRM_Core_Resources_CollectionInterface::add()
   */
  public function add($snippet);

  // TODO public function addBundle($bundle);

  /**
   * Add an HTML blob.
   *
   * Ex: addMarkup('<p>Hello world!</p>', ['weight' => 123]);
   *
   * @param string $markup
   *   HTML code.
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addMarkup(string $code, int $weight, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   * @see CRM_Core_Resources_CollectionAdderInterface::addScript()
   */
  public function addMarkup(string $markup, ...$options);

  /**
   * Export permission data to the client to enable smarter GUIs.
   *
   * Note: Application security stems from the server's enforcement
   * of the security logic (e.g. in the API permissions). There's no way
   * the client can use this info to make the app more secure; however,
   * it can produce a better-tuned (non-broken) UI.
   *
   * @param string|iterable $permNames
   *   List of permission names to check/export.
   * @return static
   */
  public function addPermissions($permNames);

  /**
   * Add a JavaScript file to the current page using <SCRIPT SRC>.
   *
   * Ex: addScript('alert("Hello world");', ['weight' => 123]);
   *
   * @param string $code
   *   JavaScript source code.
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addScript(string $code, int $weight, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addScript(string $code, ...$options);

  /**
   * Add a JavaScript file to the current page using <SCRIPT SRC>.
   *
   * Ex: addScriptFile('myextension', 'myscript.js', ['weight' => 123]);
   *
   * @param string $ext
   *   Extension name; use 'civicrm' for core.
   * @param string $file
   *   File path -- relative to the extension base dir.
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addScriptFile(string $code, int $weight, string $region, mixed $translate).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addScriptFile(string $ext, string $file, ...$options);

  /**
   * Add a JavaScript URL to the current page using <SCRIPT SRC>.
   *
   * Ex: addScriptUrl('http://example.com/foo.js', ['weight' => 123])
   *
   * @param string $url
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addScriptUrl(string $url, int $weight, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addScriptUrl(string $url, ...$options);

  /**
   * Add translated string to the js CRM object.
   * It can then be retrived from the client-side ts() function
   * Variable substitutions can happen from client-side
   *
   * Note: this function rarely needs to be called directly and is mostly for internal use.
   * See CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files
   *
   * Simple example:
   * // From php:
   * CRM_Core_Resources::singleton()->addString('Hello');
   * // The string is now available to javascript code i.e.
   * ts('Hello');
   *
   * Example with client-side substitutions:
   * // From php:
   * CRM_Core_Resources::singleton()->addString('Your %1 has been %2');
   * // ts() in javascript works the same as in php, for example:
   * ts('Your %1 has been %2', {1: objectName, 2: actionTaken});
   *
   * NOTE: This function does not work with server-side substitutions
   * (as this might result in collisions and unwanted variable injections)
   * Instead, use code like:
   * CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs)))));
   * And from javascript access it at CRM.myNamespace.myString
   *
   * @param string|array $text
   * @param string|null $domain
   * @return static
   */
  public function addString($text, $domain = 'civicrm');

  /**
   * Add a CSS content to the current page using <STYLE>.
   *
   * Ex: addStyle('p { color: red; }', ['weight' => 100]);
   *
   * @param string $code
   *   CSS source code.
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addStyle(string $code, int $weight, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addStyle(string $code, ...$options);

  /**
   * Add a CSS file to the current page using <LINK HREF>.
   *
   * Ex: addStyleFile('myextension', 'mystyles.css', ['weight' => 100]);
   *
   * @param string $ext
   *   Extension name; use 'civicrm' for core.
   * @param string $file
   *   File path -- relative to the extension base dir.
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addStyle(string $code, int $weight, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addStyleFile(string $ext, string $file, ...$options);

  /**
   * Add a CSS file to the current page using <LINK HREF>.
   *
   * Ex: addStyleUrl('http://example.com/foo.css', ['weight' => 100]);
   *
   * @param string $url
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addStyleUrl(string $code, int $weight, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addStyleUrl(string $url, ...$options);

  /**
   * Add JavaScript variables to CRM.vars
   *
   * Example:
   *   From the server:
   *     CRM_Core_Resources::singleton()->addVars('myNamespace', array('foo' => 'bar'));
   *   Access var from javascript:
   *     CRM.vars.myNamespace.foo // "bar"
   *
   * @see https://docs.civicrm.org/dev/en/latest/standards/javascript/
   *
   * @param string $nameSpace
   *   Usually the name of your extension.
   * @param array $vars
   *   Data to export.
   * @param array $options
   *   Open-ended list of key-value options. See CollectionInterface docs.
   *   Positional equivalence: addVars(string $namespace, array $vars, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   */
  public function addVars(string $nameSpace, array $vars, ...$options);

  /**
   * Add JavaScript variables to the root of the CRM object.
   * This function is usually reserved for low-level system use.
   * Extensions and components should generally use addVars instead.
   *
   * @param array $settings
   *   Data to export.
   * @param array $options
   *   Not used.
   *   Positional equivalence: addSetting(array $settings, string $region).
   * @return static
   * @see CRM_Core_Resources_CollectionInterface
   * @see CRM_Core_Resources_CollectionAdderInterface::addSetting()
   */
  public function addSetting(array $settings, ...$options);

  /**
   * Add JavaScript variables to the global CRM object via a callback function.
   *
   * @param callable $callable
   * @return static
   */
  public function addSettingsFactory($callable);

}
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	*
950538ac TO	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]);
c8cbd3ba TO	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.
c8cbd3ba TO	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	*
060617e9 TO	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.
c8cbd3ba TO	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.
c8cbd3ba TO	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]);
c8cbd3ba TO	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.
c8cbd3ba TO	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]);
c8cbd3ba TO	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.
c8cbd3ba TO	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]);
c8cbd3ba TO	175	*
060617e9 TO	176	* @param string $url
060617e9 TO	177	* @param array $options
c8cbd3ba TO	178	* Open-ended list of key-value options. See CollectionInterface docs.
c8cbd3ba TO	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.
c8cbd3ba TO	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.
c8cbd3ba TO	217	* Positional equivalence: addSetting(array $settings, string $region).
060617e9	218	* @return static
c8cbd3ba TO	219	* @see CRM_Core_Resources_CollectionInterface
c8cbd3ba TO	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	}