aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Asset/AssetResolverInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Asset;
   4
   5 /**
   6  * Resolves asset libraries into concrete CSS and JavaScript assets.
   7  *
   8  * Given an attached assets collection (to be loaded for the current response),
   9  * the asset resolver can resolve those asset libraries into a list of concrete
  10  * CSS and JavaScript assets.
  11  *
  12  * In other words: this allows developers to translate Drupal's asset
  13  * abstraction (asset libraries) into concrete assets.
  14  *
  15  * @see \Drupal\Core\Asset\AttachedAssetsInterface
  16  * @see \Drupal\Core\Asset\LibraryDependencyResolverInterface
  17  */
  18 interface AssetResolverInterface {
  19
  20   /**
  21    * Returns the CSS assets for the current response's libraries.
  22    *
  23    * It returns the CSS assets in order, according to the SMACSS categories
  24    * specified in the assets' weights:
  25    * - CSS_BASE
  26    * - CSS_LAYOUT
  27    * - CSS_COMPONENT
  28    * - CSS_STATE
  29    * - CSS_THEME
  30    * @see https://www.drupal.org/node/1887918#separate-concerns
  31    * This ensures proper cascading of styles so themes can easily override
  32    * module styles through CSS selectors.
  33    *
  34    * Themes may replace module-defined CSS files by adding a stylesheet with the
  35    * same filename. For example, themes/bartik/system-menus.css would replace
  36    * modules/system/system-menus.css. This allows themes to override complete
  37    * CSS files, rather than specific selectors, when necessary.
  38    *
  39    * Also invokes hook_css_alter(), to allow CSS assets to be altered.
  40    *
  41    * @param \Drupal\Core\Asset\AttachedAssetsInterface $assets
  42    *   The assets attached to the current response.
  43    * @param bool $optimize
  44    *   Whether to apply the CSS asset collection optimizer, to return an
  45    *   optimized CSS asset collection rather than an unoptimized one.
  46    *
  47    * @return array
  48    *   A (possibly optimized) collection of CSS assets.
  49    */
  50   public function getCssAssets(AttachedAssetsInterface $assets, $optimize);
  51
  52   /**
  53    * Returns the JavaScript assets for the current response's libraries.
  54    *
  55    * References to JavaScript files are placed in a certain order: first, all
  56    * 'core' files, then all 'module' and finally all 'theme' JavaScript files
  57    * are added to the page. Then, all settings are output, followed by 'inline'
  58    * JavaScript code. If running update.php, all preprocessing is disabled.
  59    *
  60    * Note that hook_js_alter(&$javascript) is called during this function call
  61    * to allow alterations of the JavaScript during its presentation. The correct
  62    * way to add JavaScript during hook_js_alter() is to add another element to
  63    * the $javascript array, deriving from drupal_js_defaults(). See
  64    * locale_js_alter() for an example of this.
  65    *
  66    * @param \Drupal\Core\Asset\AttachedAssetsInterface $assets
  67    *   The assets attached to the current response.
  68    *   Note that this object is modified to reflect the final JavaScript
  69    *   settings assets.
  70    * @param bool $optimize
  71    *   Whether to apply the JavaScript asset collection optimizer, to return
  72    *   optimized JavaScript asset collections rather than an unoptimized ones.
  73    *
  74    * @return array
  75    *   A nested array containing 2 values:
  76    *   - at index zero: the (possibly optimized) collection of JavaScript assets
  77    *     for the top of the page
  78    *   - at index one: the (possibly optimized) collection of JavaScript assets
  79    *     for the bottom of the page
  80    */
  81   public function getJsAssets(AttachedAssetsInterface $assets, $optimize);
  82
  83 }