CRM/Core/Resources/CollectionInterface.php

   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  * Class CRM_Core_Resources_CollectionInterface
  14  *
  15  * A resource collection is a mix of *resources* (or *snippets* or *assets*) that can be
  16  * added to a page. A fully-formed resource might look like this:
  17  *
  18  * ```
  19  * array(
  20  *   'name' => 'jQuery',
  21  *   'region' => 'html-header',
  22  *   'weight' => 100,
  23  *   'type' => 'scriptUrl',
  24  *   'scriptUrl' => 'https://example.com/js/jquery.min.js'
  25  * )
  26  * ```
  27  *
  28  * Typically, a resource is created with just one option, eg
  29  *
  30  * ```
  31  * // Add resources in array notation
  32  * $c->add(['script' => 'alert("Hello");']);
  33  * $c->add(['scriptFile' => ['civicrm', 'js/crm.ckeditor.js']]);
  34  * $c->add(['scriptUrl' => 'https://example.com/js/jquery.min.js']);
  35  * $c->add(['style' => 'p { font-size: 4em; }']);
  36  * $c->add(['styleFile' => ['civicrm', 'css/dashboard.css']]);
  37  * $c->add(['styleUrl' => 'https://example.com/css/foobar.css']);
  38  *
  39  * // Add resources with helper methods
  40  * $c->addScript('alert("Hello");');
  41  * $c->addScriptFile('civicrm', 'js/crm.ckeditor.js');
  42  * $c->addScriptUrl('https://example.com/js/jquery.min.js');
  43  * $c->addStyle('p { font-size: 4em; }');
  44  * $c->addStyleFile('civicrm', 'css/dashboard.css');
  45  * $c->addStyleUrl('https://example.com/css/foobar.css');
  46  * ```
  47  *
  48  * The other properties are automatically computed (dependent upon context),
  49  * but they may be set explicitly. These options include:
  50  *
  51  *   - type: string (markup, template, callback, script, scriptFile, scriptUrl, jquery, style, styleFile, styleUrl)
  52  *   - name: string, symbolic identifier for this resource
  53  *   - aliases: string[], list of alternative names for this resource
  54  *   - weight: int, default=1. Lower weights come before higher weights.
  55  *     (If two resources have the same weight, then a secondary ordering will be
  56  *     used to ensure reproducibility. However, the secondary ordering is
  57  *     not guaranteed among versions/implementations.)
  58  *   - disabled: int, default=0
  59  *   - region: string
  60  *   - translate: bool|string, Autoload translations. (Only applies to 'scriptFile')
  61  *       - FALSE: Do not load translated strings.
  62  *       - TRUE: Load translated strings. Use the $ext's default domain.
  63  *       - string: Load translated strings. Use a specific domain.
  64  *
  65  * For example, the following are equivalent ways to set the 'weight' option:
  66  *
  67  * ```php
  68  * $c->add([
  69  *   'script' => 'alert("Hello");',
  70  *   'weight' => 100,
  71  * ]);
  72  * $c->addScript('alert("Hello");', ['weight' => 100]);
  73  * ```
  74  *
  75  * Passing options in array (key-value) notation is clearest. For backward
  76  * compatibility, some methods (eg `addScript()`) accept options in positional form.
  77  * Where applicable, the docblock of each `addFoo()` will include a comment about positional form.
  78  *
  79  * @see CRM_Core_Resources_CollectionTrait
  80  */
  81 interface CRM_Core_Resources_CollectionInterface {
  82
  83   /**
  84    * Add an item to the collection. For example, when working with 'page-header' collection:
  85    *
  86    * Note: This function does not perform any extra encoding of markup, script code, or etc. If
  87    * you're passing in user-data, you must clean it yourself.
  88    *
  89    * @param array $snippet
  90    *   The resource to add. For a full list of properties, see CRM_Core_Resources_CollectionInterface.
  91    * @return array
  92    *   The full/computed snippet (with defaults applied).
  93    * @see CRM_Core_Resources_CollectionInterface
  94    */
  95   public function add($snippet);
  96
  97   /**
  98    * Update specific properties of a snippet.
  99    *
 100    * Ex: $region->update('default', ['disabled' => TRUE]);
 101    *
 102    * @param string $name
 103    *   Symbolic of the resource/snippet to update.
 104    * @param array $snippet
 105    *   Resource options. See CollectionInterface docs.
 106    * @return static
 107    */
 108   public function update($name, $snippet);
 109
 110   /**
 111    * Remove all snippets.
 112    *
 113    * @return static
 114    */
 115   public function clear();
 116
 117   /**
 118    * Get snippet.
 119    *
 120    * @param string $name
 121    * @return array|NULL
 122    */
 123   public function &get($name);
 124
 125   /**
 126    * Get a list of all snippets in this collection.
 127    *
 128    * @return iterable
 129    */
 130   public function getAll(): iterable;
 131
 132   /**
 133    * Alter the contents of the collection.
 134    *
 135    * @param callable $callback
 136    *   The callback is invoked once for each member in the collection.
 137    *   The callback may return one of three values:
 138    *   - TRUE: The item is OK and belongs in the collection.
 139    *   - FALSE: The item is not OK and should be omitted from the collection.
 140    *   - Array: The item should be revised (using the returned value).
 141    * @return static
 142    */
 143   public function filter($callback);
 144
 145   /**
 146    * Find all snippets which match the given criterion.
 147    *
 148    * @param callable $callback
 149    *   The callback is invoked once for each member in the collection.
 150    *   The callback may return one of two values:
 151    *   - TRUE: The item is OK and belongs in the collection.
 152    *   - FALSE: The item is not OK and should be omitted from the collection.
 153    * @return iterable
 154    *   List of matching snippets.
 155    */
 156   public function find($callback): iterable;
 157
 158   /**
 159    * Assimilate a list of resources into this list.
 160    *
 161    * @param iterable $others
 162    *   List of snippets to add.
 163    * @return static
 164    * @see CRM_Core_Resources_CollectionInterface::merge()
 165    */
 166   public function merge(iterable $others);
 167
 168 }