From 51e5dc6d3190f223704a81b21ce896a8a69333ec Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 6 Dec 2024 02:40:45 -0800
Subject: [PATCH] =?UTF-8?q?Document=20how=20to=20specify=20a=20static=20re?=
 =?UTF-8?q?source=20bundle=20to=20load=20as=20the=20last=20=E2=80=A6=20(#1?=
 =?UTF-8?q?802)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Document how to specify a static resource bundle to load as the last one in Classic UI

* Merge content from #1803

* Add clause for multiple `all`s

* More merge and removal of redundant content

* Update docs/classic-ui/static-resources.md

Co-authored-by: Peter Mathis <petschki@users.noreply.github.com>

* Update docs/classic-ui/static-resources.md

Co-authored-by: Yuri <yurj@alfa.it>

* Retain friendly "you", but use "both"

---------

Co-authored-by: Peter Mathis <petschki@users.noreply.github.com>
Co-authored-by: Johannes Raggam <thetetet@gmail.com>
Co-authored-by: Yuri <yurj@alfa.it>
---
 docs/classic-ui/static-resources.md | 64 ++++++++++++++++++++---------
 1 file changed, 44 insertions(+), 20 deletions(-)

diff --git a/docs/classic-ui/static-resources.md b/docs/classic-ui/static-resources.md
index 84a8aec56..5234813e9 100644
--- a/docs/classic-ui/static-resources.md
+++ b/docs/classic-ui/static-resources.md
@@ -12,7 +12,11 @@ myst:
 # Static resources
 
 We often want to ship a website with a static resource, such as an image, icon, CSS, or JavaScript file.
-For this, we need to register static resources.
+For CSS and JavaScript files, we can use the resource registry to register, then deliver, them to the client browser.
+
+The resource registry provides a programmatic way, either in code or through the web, to extend and configure the dependencies between static resources.
+It also automatically manages caching of static resources.
+If you were to hard-code these resources in templates with `<link>` or `<script>` tags, you would not have these advantages.
 
 ```{seealso}
 For some additional implementation information, see {ref}`classic-ui-theming-from-scratch-theme-label`.
@@ -33,7 +37,7 @@ The JavaScript files have to be in the `browser/static` folder of your Plone 6 p
   <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/jscript">
     <value key="enabled">True</value>
     <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
-    <value key="load_async">False</value> 
+    <value key="load_async">False</value>
     <value key="load_defer">False</value>
     <value key="depends">plone</value>
   </records>
@@ -41,7 +45,7 @@ The JavaScript files have to be in the `browser/static` folder of your Plone 6 p
 ```
 
 You can register a CSS resource in the same way.
-  
+
 ```xml
     <registry>
     <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
@@ -52,15 +56,15 @@ You can register a CSS resource in the same way.
   </registry>
 ```
 
-Registering a JavaScript file and a CSS file in the same bundle is also possible.
+You can also register both a JavaScript file and a CSS file in the same bundle.
 
-```xml 
+```xml
 <registry>
   <records interface="plone.base.interfaces.resources.IBundleRegistry" prefix="plone.bundles/css">
     <value key="enabled">True</value>
     <value key="csscompilation">++plone++myproject.site/style.min.css</value>
     <value key="jscompilation">++plone++myproject.site/javascript.min.js</value>
-    <value key="load_async">False</value> 
+    <value key="load_async">False</value>
     <value key="load_defer">False</value>
     <value key="depends">plone</value>
   </records>
@@ -72,32 +76,52 @@ Registering a JavaScript file and a CSS file in the same bundle is also possible
 
 ## Available attributes
 
-The following attributes are available for registering a static resource:
+The following attributes are available for registering a static resource.
 
 `enabled`
-:   Whether the bundle is enabled or not.
+:   Boolean.
+    Whether the bundle is enabled or not.
     If it is disabled, the bundle will not be loaded.
 
 `jscompilation`
-:   The path to the compiled JavaScript file.
+:   String.
+    The path to the compiled JavaScript file.
 
 `csscompilation`
-:   The path to the compiled CSS file.
+:   String.
+    The path to the compiled CSS file.
 
 `depends`
-:   A list of bundles that this bundle depends on.
+:   String.
+    A comma-separated list of bundles that this bundle depends on.
+    For a single dependency, do not insert commas.
 
-`load_async`
-:   Whether the bundle should be loaded asynchronously or not.
-    *Only JavaScript*
+    When a bundle depends on another one, its `<script>` or `<link>` tag is rendered after the bundle it depends on.
 
-`load_defer`
-:   Whether the bundle should be loaded deferred or not.
-    *Only JavaScript*
+    If the bundle's dependencies do not exist, then the bundle will not render.
 
+    The `depends` attribute may be assigned the value of `all`, making this bundle render last, after all other bundles.
+    The `all` value lets you load CSS files after the automatically added theme resources and override CSS declarations from your own custom CSS files.
 
-(classic-ui-static-resources-loading-order-label)=
+    If you set multiple bundles to `all`, then these bundles will render in alphabetical order by its name.
 
-## Loading order of resources
+    ```{note}
+    You can also add custom CSS through-the-web via the {guilabel}`Theming` control panel, under {menuselection}`Site Setup --> Theming --> Advanced settings --> Custom Styles`.
+    Setting `depends` to `all` does not affect custom CSS that you define in the {guilabel}`Theming` control panel, which _always_ renders as the last style resource.
+    It only affects bundles, not control panel settings.
+    ```
 
-`depends` is used to define the loading order of resources by specifying the name of the depending bundle.
+    ```{versionadded} Plone 6.0.14
+    `depends` value of `all`.
+    ```
+
+`load_async`
+:   Boolean.
+    Whether the bundle should be loaded asynchronously or not.
+    *Only JavaScript*
+
+`load_defer`
+:   Boolean.
+    Whether the bundle should be loaded deferred or not.
+    If you use `load_async`, this attribute has no effect.
+    *Only JavaScript*