Clean up layers.md, add interface to Glossary

Author: stevepiercy

docs/classic-ui/layers.md

@@ -1,54 +1,48 @@
 ---
-html_meta:
-  "description": "Layers allow you to enable and disable views and other site functionality based on installed add-ons and themes."
-  "property=og:description": "Layers allow you to enable and disable views and other site functionality based on installed add-ons and themes."
-  "property=og:title": "Layers"
-  "keywords": "layer, layers,browser layer, views, viewlets, portlets"
+myst:
+  html_meta:
+    "description": "Layers allow you to enable and disable views and other site functionality based on installed add-ons and themes."
+    "property=og:description": "Layers allow you to enable and disable views and other site functionality based on installed add-ons and themes."
+    "property=og:title": "Layers"
+    "keywords": "layer, layers,browser layer, views, viewlets, portlets"
 ---
 
 (classic-ui-layers-label)=
 
 # Layers
 
-Layers allow you to activate different code paths and modules depending on
-the external configuration.
+Layers allow you to activate different code paths and modules depending on the external configuration.
+Layers are useful in the following scenarios.
 
-Examples:
-
-- Code belonging to a theme is only active when that theme has been selected.
-- Mobile browsing code is only active when the site is being browsed on a
-  mobile phone.
+-   Code belonging to a theme is only active when that theme has been selected.
+-   Mobile browsing code is only active when the site is being browsed on a mobile phone.
 
 Layers are marker interfaces applied to the {term}`HTTPRequest` object.
-They are usually used in conjunction with {term}`ZCML` directives to
-dynamically activate various parts
-of the configuration (theme files, add-on product functionality).
+They are usually used in conjunction with {term}`ZCML` directives to dynamically activate various parts of the configuration, such as theme files or add-on product functionality.
+
+Layers ensure that only one add-on product can override the specific Plone instance functionality in your site at a time, while still allowing you to have possibly conflicting add-on products in your buildout and ZCML.
+Multiple Plone site instances can share the same ZCML and code files.
+
+Many ZCML directives take the optional `layer` parameter.
+See example [resourceDirectory](http://apidoc.zope.org/++apidoc++/ZCML/http_co__sl__sl_namespaces.zope.org_sl_browser/resourceDirectory/index.html).
 
-Layers ensure that only one add-on product can override the specific Plone
-instance functionality in your site at a time, while still allowing you
-to have possibly conflicting add-on products in your buildout and
-ZCML. Remember that multiple Plone site instances can share
-the same ZCML and code files.
+Layers are activated when an add-on product is installed or a certain theme is activated.
 
-Many ZCML directives take the optional `layer` parameter. See example,
-[resourceDirectory](http://apidoc.zope.org/++apidoc++/ZCML/http_co__sl__sl_namespaces.zope.org_sl_browser/resourceDirectory/index.html)
 
-Layers are activated when an add-on product is installed or a certain
-theme is picked.
+(classic-ui-using-layers-label)=
 
 ## Using layers
 
-Some ZCML directives for example: `browser:page` take a `layer` attribute.
+Some ZCML directives take a `layer` attribute, such as `browser:page`.
 
 Given the following:
 
-- A layer interface defined in Python code: `plonetheme.yourthemename.interfaces.IThemeSpecific`
-- Your add-on or theme package installed through add-on product installer on your site instance
+-   A layer interface defined in Python code, `plonetheme.yourthemename.interfaces.IThemeSpecific`.
+-   Your add-on or theme package installed through the add-on product installer on your site instance.
 
-then views and viewlets from your product can be enabled on the site
-instance using the following ZCML:
+Then views and viewlets from your product can be enabled on the site instance using the following ZCML:
 
-```
+```xml
 <!-- Site actions override in YourTheme -->
 <browser:viewlet
     name="plone.site_actions"
@@ -59,75 +53,87 @@ instance using the following ZCML:
     />
 ```
 
+
+(classic-ui-unconditional-overrides-label)=
+
 ### Unconditional overrides
 
-If you want to override a view or a viewlet unconditionally for all sites
-without the add-on product installer
-support you need to use `overrides.zcml`.
+If you want to override a view or a viewlet unconditionally for all sites without the add-on product installer support, you need to use `overrides.zcml`.
+
+
+(classic-ui-creating-a-layer-label)=
 
 ## Creating a layer
 
+
+(classic-ui-theme-layer-label)=
+
 ### Theme layer
 
-Theme layers can be created via the following steps:
+Theme layers can be created through the following steps.
 
-1. Subclass an interface from `IDefaultPloneLayer`:
+1.  Subclass an interface from `IDefaultPloneLayer`:
 
-   ```
-   from plone.theme.interfaces import IDefaultPloneLayer
+    ```python
+    from plone.theme.interfaces import IDefaultPloneLayer
 
-   class IThemeSpecific(IDefaultPloneLayer):
-       """Marker interface that defines a Zope 3 skin layer bound to a Skin
-          Selection in portal_skins.
-          If you need to register a viewlet only for the "YourSkin"
-          skin, this is the interface that must be used for the layer attribute
-          in YourSkin/browser/configure.zcml.
-       """
-   ```
 
-2. Register it in ZCML. The name must match the theme name.
+    class IThemeSpecific(IDefaultPloneLayer):
+        """
+        Marker interface that defines a Zope 3 skin layer bound to a Skin
+        Selection in portal_skins.
+        If you need to register a viewlet only for the "YourSkin"
+        skin, this is the interface that must be used for the layer attribute
+        in YourSkin/browser/configure.zcml.
+        """
+    ```
 
-   ```xml
-   <interface
-       interface=".interfaces.IThemeSpecific"
-       type="zope.publisher.interfaces.browser.IBrowserSkinType"
-       name="SitsSkin"
-       />
-   ```
+2.  Register it in ZCML.
+    The name must match the theme name.
 
-3. Register and set your theme as the default theme in `profiles/default/skins.xml`. Theme layers require that they are set as the default theme and not just activated on your Plone site. Example:
+    ```xml
+    <interface
+        interface=".interfaces.IThemeSpecific"
+        type="zope.publisher.interfaces.browser.IBrowserSkinType"
+        name="SitsSkin"
+        />
+    ```
 
-   ```xml
-   <object name="portal_skins" allow_any="False" cookie_persistence="False"
-       default_skin="SitsSkin">
+3.  Register and set your theme as the default theme in `profiles/default/skins.xml`.
+    Theme layers require that they are set as the default theme and not just activated on your Plone site.
+    Example:
 
-       <!-- define skins-based folder objects here if any -->
+    ```xml
+    <object name="portal_skins" allow_any="False" cookie_persistence="False"
+        default_skin="SitsSkin">
+    
+        <!-- define skins-based folder objects here if any -->
+    
+        <skin-path name="SitsSkin" based-on="Plone Default">
+            <layer name="plone_skins_style_folder_name"
+                insert-before="*"/>
+        </skin-path>
+    
+    </object>
+    ```
 
-       <skin-path name="SitsSkin" based-on="Plone Default">
-           <layer name="plone_skins_style_folder_name"
-               insert-before="*"/>
-       </skin-path>
 
-   </object>
-   ```
+(classic-ui-add-on-layer-for-clean-extensions-label)=
 
 ### Add-on layer for clean extensions
 
 An add-on product layer is enabled when an add-on product is installed.
-Since one Zope application server may contain several Plone sites,
-you need to keep enabled code paths separate by using add-on layers -
-otherwise all views and viewlets apply to all sites in one Zope application server.
+Since one Zope application server may contain several Plone sites, you need to keep enabled code paths separate by using add-on layers.
+Otherwise, all views and viewlets apply to all sites in one Zope application server.
 
-- You can enable views and viewlets specific to functional add-ons.
-- Unlike theme layers, add-on layers depend on the activated add-on
-  products, not on the selected theme.
+-   You can enable views and viewlets specific to functional add-ons.
+-   Unlike theme layers, add-on layers depend on the activated add-on products, not on the selected theme.
 
-An add-on layer is a marker interface which is applied on the
-{term}`HTTPRequest` object by Plone core logic.
+An add-on layer is a marker interface which is applied on the {term}`HTTPRequest` object by Plone core logic.
 
 First create an {term}`interface` for your layer in `your.product.interfaces.py`:
 
-```
+```python
 """ Define interfaces for your add-on.
 """
 
@@ -143,8 +149,7 @@ class IAddOnInstalled(zope.interface.Interface):
     """
 ```
 
-You then need to refer to this in the `profile/default/browserlayer.xml`
-file of your add-on installer to use it:
+You then need to refer to this in the `profile/default/browserlayer.xml` file of your add-on installer to use it:
 
 ```xml
 <layers>
@@ -160,44 +165,45 @@ The add-on layer registry is persistent and stored in the database.
 The changes to add-on layers are applied only when add-ons are installed or uninstalled.
 ```
 
-More information
+```{seealso}
+https://pypi.python.org/pypi/plone.browserlayer
+```
 
-- <https://pypi.python.org/pypi/plone.browserlayer>
 
+(classic-ui-add-on-layer-for-changing-existing-behavior-label)=
 
 ### Add-on layer for changing existing behavior
 
-You can also use layers to modify the behavior of plone or another Add-on.
+You can also use layers to modify the behavior of Plone or another add-on.
 
-To make sure that your own view is used, your Layer must be more specific than the layer where original view is registered.
+To make sure that your own view is used, your layer must be more specific than the layer where the original view is registered.
 
-For example, some z3cform things register their views on the `IPloneFormLayer` from plone.app.z3cform.interfaces.
+For example, some `z3cform` things register their views on the `IPloneFormLayer` from `plone.app.z3cform.interfaces`.
 
-If you want to override the ploneform-macros view that is registered on the `IPloneFormLayer`, your own Layer must be a subclass of IPloneFormLayer.
+If you want to override the `ploneform-macros` view that is registered on the `IPloneFormLayer`, your own layer must be a subclass of `IPloneFormLayer`.
 
-If a view does not declare a specific Layer,  it becomes registered on the `IDefaultBrowserLayer` from zope.publisher.interfaces.browser.IDefaultBrowserLayer.
+If a view does not declare a specific layer, it becomes registered on the `IDefaultBrowserLayer` from `zope.publisher.interfaces.browser.IDefaultBrowserLayer`.
 
 
+(classic-ui-manual-layers-label)=
+
 ### Manual layers
 
-Apply your layer to the {term}`HTTPRequest` in the `before_traverse` hook or
-before you call the code which looks up the interfaces.
+Apply your layer to the {term}`HTTPRequest` in the `before_traverse` hook, or before you call the code which looks up the interfaces.
 
-In the example below we turn on a layer for the request which is later
-checked by the rendering code.
+In the example below, we turn on a layer for the request, which is later checked by the rendering code.
 This way some pages can ask for special View/Viewlet rendering.
 
-Example:
-
-```
+```python
 # Defining layer
 
 from zope.publisher.interfaces.browser import IBrowserRequest
 
 class INoHeaderLayer(IBrowserRequest):
-    """ When applied to HTTP request object, header animations or images are not rendered on this.
+    """ When applied to HTTP request object, header animations
+    or images are not rendered on this.
 
-    If this layer is on request do not render header images.
+    If this layer is on request, do not render header images.
     This allows uncluttered editing of header animations and images.
     """
 
@@ -219,42 +225,48 @@ class EditHeaderAnimationsView(FormWrapper):
         return FormWrapper.__call__(self)
 ```
 
+
+(classic-ui-troubleshooting-instructions-for-layers-label)=
+
 ## Troubleshooting instructions for layers
 
-- Check that your view or whatever is working without a layer assigned
-  (globally);
-- Check that `configure.zcml` has a layer entry. Put some garbage to
-  trigger a syntax error in `configure.zcml` to make sure that it is being
-  loaded;
-- Add-on layer: check that `profiles/default/browserlayer.xml` has a
-  matching entry with a matching name;
-- Theme layer: if it's a theme layer, check that there is a matching
-  `skins.xml` entry
-- Check that layer name is correctly spelt in the view declaration.
+-   Check that your view is working without a layer assigned globally.
+-   Check that `configure.zcml` has a layer entry.
+    Put some garbage to trigger a syntax error in `configure.zcml` to make sure that it is being loaded.
+-   Add-on layer: check that `profiles/default/browserlayer.xml` has a matching entry with a matching name.
+-   Theme layer: if it is a theme layer, check that there is a matching `skins.xml` entry.
+-   Check that the layer name is spelled correctly in the view declaration.
+
+
+(classic-ui-checking-active-layers-label)=
 
 ## Checking active layers
 
+
+(classic-ui-layers-are-activated-on-the-current-request-object-label)=
+
 ### Layers are activated on the current request object
 
 Example:
 
-```
+```python
 if INoHeaderLayer.providedBy(self.request):
     # The page has asked to suspend rendering of the header animations
     return ""
 ```
 
+
+(classic-ui-active-themes-and-add-on-products-label)=
+
 ### Active themes and add-on products
 
-The `registered_layers()` method returns a list of all layers active on
-the site.
-Note that this is different to the list of layers which are applied on the
-current HTTP request object:
-the request object may contain manually activated layers.
+The `registered_layers()` method returns a list of all layers active on the site.
+Note that this is different from the list of layers which are applied on the current HTTP request object.
+The request object may contain manually activated layers.
 
 Example:
 
-```
+```python
 from interfaces import IThemeSpecific
 from plone.browserlayer.utils import registered_layers
 
@@ -266,26 +278,33 @@ else:
     pass
 ```
 
+
+(classic-ui-getting-active-theme-layer-label)=
+
 ### Getting active theme layer
 
 Only one theme layer can be active at once.
 
 The active theme name is defined in `portal_skins` properties.
 This name can be resolved to a theme layer.
 
+
+(classic-ui-debugging-active-layers-label)=
+
 ### Debugging active layers
 
-You can check the activated layers from HTTP request object by looking at
-`self.request.__provides__.__iro__`.
-Layers are evaluated from zero index (highest priority) the last index
-(lowest priority).
+You can check the activated layers from the HTTP request object by looking at `self.request.__provides__.__iro__`.
+Layers are evaluated from zero index (highest priority) to the last index (lowest priority).
+
+
+(classic-ui-testing-layers-label)=
 
 ## Testing Layers
 
-Plone testing tool kits won't register layers for you, you have to do it
-yourself somewhere in the boilerplate code:
+Plone testing tool kits will not register layers for you.
+You have to do it yourself somewhere in the boilerplate code, as shown in the following example.
 
-```
+```python
 from zope.interface import directlyProvides
 
 directlyProvides(self.portal.REQUEST, IThemeLayer)