1<?php
2
3namespace 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 */
18interface 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}
84