Merge branch '6.0' into welcome-bot

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,15 +37,15 @@ 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>
 </registry>
 ```
 
 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*

docs/classic-ui/tinymce-customization.md

@@ -26,7 +26,7 @@ They are less complicated to implement than the third option.
 
 This option is best for system administrators and developers who write their own add-ons to ease reproducibility.
 
-You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the following content.
+You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the JSON configuration of the custom format.
 
 ```xml
 <registry>
@@ -44,6 +44,37 @@ You can add a GenericSetup configuration file to your add-on, such as {file}`pro
 </registry>
 ```
 
+```{important}
+The content of the `formats` record will overwrite the value in the {guilabel}`Formats` field in the TinyMCE control panel at {menuselection}`Site Setup --> TinyMCE --> Default`.
+If you want to preserve the default content, you must copy it into your XML.
+```
+
+Next, define where to place the new format inside the {menuselection}`Format` menu's submenus.
+You can add your custom format to one of the following menu items.
+These menu items in the TinyMCE editor correspond to field items in the TinyMCE control panel at {menuselection}`Site Setup --> TinyMCE --> Default`.
+
+(tinymce-formats-styles-label)=
+
+-   {guilabel}`Header styles`
+-   {guilabel}`Inline styles`
+-   {guilabel}`Block styles`
+-   {guilabel}`Alignment styles`
+-   {guilabel}`Table styles`
+
+The syntax for each element in those fields is `Title|format`.
+The following example XML snippet adds your format to the {menuselection}`Inline styles` menu.
+Unlike the previous example, the example does not remove the default values, but appends to it.
+
+```xml
+<record field="inline_styles"
+        interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
+        name="plone.inline_styles">
+  <value>
+    <element>My custom format|myformat</element>
+  </value>
+</record>
+```
+
 
 ### Edit the `Formats` option in the TinyMCE control panel
 
@@ -53,13 +84,14 @@ You can manually customize the `Formats` value through-the-web in the TinyMCE co
 
 1.  Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar.
 1.  Scroll down to {guilabel}`Formats`, and edit the JSON configuration.
+1.  Insert your custom format to one of the fields mentioned above.
 1.  Click the {guilabel}`Save` button.
 
 
-
 ### Inject formats with files named {file}`tinymce-formats.css`
 
 This option is more complex to implement than the previous options.
+However it is the only option where you can add items to the {menuselection}`Formats` submenu as siblings to the {ref}`Formats styles <tinymce-formats-styles-label>` configurations.
 
 In Plone 6, TinyMCE has a special logic that automatically reads registered files named {file}`tinymce-formats.css` and adds the CSS classes defined in those files to TinyMCE's {menuselection}`Format --> Formats` menu by using the [`importcss_file_filter` option](https://www.tiny.cloud/docs/tinymce/latest/importcss/#importcss_file_filter).
 
@@ -76,6 +108,27 @@ CSS styles defined in this file will automatically be added to the top level of
 
 ## Remove imported formats
 
+Similar to adding formats, you can remove formats in a couple of ways.
+
+
+### Add-on GenericSetup configuration file
+
+Alternatively, you can use GenericSetup in your add-on.
+
+```xml
+<record field="content_css"
+          interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
+          name="plone.content_css"
+  >
+    <value purge="true">
+      <element>++theme++barceloneta/tinymce/tinymce-ui-content.css</element>
+    </value>
+  </record>
+```
+
+
+### Configure the TinyMCE control panel
+
 Plone 6 Classic UI ships with the Barceloneta theme which includes two custom formats, `highlight-inline` and `p.highlight-paragraph`, in the TinyMCE {menuselection}`Format --> Formats` menu.
 You can remove these formats through the TinyMCE control panel.