[TASK] Add documentation for AssetCollector

This adds phpdoc for the public AssetCollector::add...() functions and notes for users migrating from PageRenderer::add...(). Resolves: #90870 Releases: master Change-Id: I8896b83f172a0e70ff5bdae61106c3a66d29667c Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/63970 Tested-by: TYPO3com <noreply@typo3.com> Tested-by: Frank Nägler <frank.naegler@typo3.org> Tested-by: Andreas Fernandez <a.fernandez@scripting-base.de> Reviewed-by: Frank Nägler <frank.naegler@typo3.org> Reviewed-by: Andreas Fernandez <a.fernandez@scripting-base.de>

[TASK] Add documentation for AssetCollector
This adds phpdoc for the public AssetCollector::add...() functions and notes for users migrating from PageRenderer::add...(). Resolves: #90870 Releases: master Change-Id: I8896b83f172a0e70ff5bdae61106c3a66d29667c Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/63970 Tested-by: TYPO3com <noreply@typo3.com> Tested-by: Frank Nägler <frank.naegler@typo3.org> Tested-by: Andreas Fernandez <a.fernandez@scripting-base.de> Reviewed-by: Frank Nägler <frank.naegler@typo3.org> Reviewed-by: Andreas Fernandez <a.fernandez@scripting-base.de>
a244e1ad · Jonas Eberle · Frank Nägler · 66f36c25 · a244e1ad · a244e1ad
Commit a244e1ad authored 5 years ago by Jonas Eberle Committed by Frank Nägler 5 years ago
--- a/typo3/sysext/core/Classes/Page/AssetCollector.php
+++ b/typo3/sysext/core/Classes/Page/AssetCollector.php
@@ -65,6 +65,13 @@ class AssetCollector implements SingletonInterface
     */
    protected $media = [];
+    /**
+     * @param string $identifier
+     * @param string $source URI to JavaScript file (allows EXT: syntax)
+     * @param array $attributes additional HTML <script> tag attributes
+     * @param array $options ['priority' => true] means rendering before other tags
+     * @return AssetCollector
+     */
    public function addJavaScript(string $identifier, string $source, array $attributes = [], array $options = []): self
    {
        $existingAttributes = $this->javaScripts[$identifier]['attributes'] ?? [];
@@ -79,6 +86,13 @@ class AssetCollector implements SingletonInterface
        return $this;
    }
+    /**
+     * @param string $identifier
+     * @param string $source JavaScript code
+     * @param array $attributes additional HTML <script> tag attributes
+     * @param array $options ['priority' => true] means rendering before other tags
+     * @return AssetCollector
+     */
    public function addInlineJavaScript(string $identifier, string $source, array $attributes = [], array $options = []): self
    {
        $existingAttributes = $this->inlineJavaScripts[$identifier]['attributes'] ?? [];
@@ -93,6 +107,13 @@ class AssetCollector implements SingletonInterface
        return $this;
    }
+    /**
+     * @param string $identifier
+     * @param string $source URI to stylesheet file (allows EXT: syntax)
+     * @param array $attributes additional HTML <link> tag attributes
+     * @param array $options ['priority' => true] means rendering before other tags
+     * @return AssetCollector
+     */
    public function addStyleSheet(string $identifier, string $source, array $attributes = [], array $options = []): self
    {
        $existingAttributes = $this->styleSheets[$identifier]['attributes'] ?? [];
@@ -107,6 +128,13 @@ class AssetCollector implements SingletonInterface
        return $this;
    }
+    /**
+     * @param string $identifier
+     * @param string $source stylesheet code
+     * @param array $attributes additional HTML <link> tag attributes
+     * @param array $options ['priority' => true] means rendering before other tags
+     * @return AssetCollector
+     */
    public function addInlineStyleSheet(string $identifier, string $source, array $attributes = [], array $options = []): self
    {
        $existingAttributes = $this->inlineStyleSheets[$identifier]['attributes'] ?? [];

--- a/typo3/sysext/core/Documentation/Changelog/10.3/Feature-90522-IntroduceAssetCollector.rst
+++ b/typo3/sysext/core/Documentation/Changelog/10.3/Feature-90522-IntroduceAssetCollector.rst
@@ -64,6 +64,39 @@ There are also two new ViewHelpers, the :html:`<f:asset.css>` and the - :html:`<
      alert('hello world');
   </f:asset.script>
+Considerations
+--------------
+Currently, assets registered with the AssetCollector are not included in callbacks of these hooks:
+- :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['cssCompressHandler']`
+- :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['jsCompressHandler']`
+- :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['cssConcatenateHandler']`
+- :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['jsConcatenateHandler']`
+Currently, CSS and JavaScript registered with the AssetCollector will always be rendered after their
+PageRenderer counterparts. The order is:
+- :html:`<head>`
+- :ts:`page.includeJSLibs.forceOnTop`
+- :ts:`page.includeJSLibs`
+- :ts:`page.includeJS.forceOnTop`
+- :ts:`page.includeJS`
+- :php:`AssetCollector::addJavaScript()` with 'priority'
+- :ts:`page.jsInline`
+- :php:`AssetCollector::addInlineJavaScript()` with 'priority'
+- :html:`</head>`
+- :ts:`page.includeJSFooterlibs.forceOnTop`
+- :ts:`page.includeJSFooterlibs`
+- :ts:`page.includeJSFooter.forceOnTop`
+- :ts:`page.includeJSFooter`
+- :php:`AssetCollector::addJavaScript()`
+- :ts:`page.jsFooterInline`
+- :php:`AssetCollector::addInlineJavaScript()`
+Currently, JavaScript registered with AssetCollector is not affected by
+:ts:`config.moveJsFromHeaderToFooter`.
 Examples
 --------