docs: rewrite the rest of the ADR

Author: Cup0fCoffee

docs/decisions/0002-footer-links.rst

@@ -41,16 +41,58 @@ Decision
 
 .. This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …"
 
-There are to two types of customizations - those that alter the styles and
-those that alter the content of the component. We will expose both
-customization option to be configurable through the `MFE's config mechanism`_.
+Links
+=====
 
-For styles, to allow a great degree of freedom in customization, we will allow,
-where appropriate, to either supply a list of CSS classes which will be applied
-to a particular component, or a list of CSS attributes and values.
+For specifying the footer links, we are going to use `MFE's config mechanism`_.
+That would allow to specify a list of links in various ways:
+
+* At build time:
+  * Via environmental variables
+  * By providing them in ``env.config.js``, like so:
+
+    .. code-block:: javascript
+
+        const config = {
+            FOOTER_LINKS: [
+                {"url": "https://google.com", "text": "Terms of service"},
+                {"url": "https://duckduckgo.com", "text": "Acceptable Use Policy"},
+                {"url": "https://openedx.org", "text": "Privacy Policy"},
+            ],
+        };
+
+        export default config;
+
+* At runtime, via ``MFE_CONFIG`` in LMS's Django settings:
+
+    .. code-block:: python
+
+        MFE_CONFIG = {
+            "FOOTER_LINKS": [
+                {"url": "https://google.com", "text": "Terms of service"},
+                {"url": "https://duckduckgo.com", "text": "Acceptable Use Policy"},
+                {"url": "https://openedx.org", "text": "Privacy Policy"},
+            ],
+        }
+
+In case the array is undefined or empty, we won't render any links (or it's
+container).
 
 .. _MFE's config mechanism: https://github.com/openedx/frontend-platform/blob/master/src/config.js
 
+Styles
+======
+
+Since the root of the footer component is rendered as a footer HTML element, it
+is unique enough to use ``footer`` as selector. To make it more convenient to
+style footer's children, we will add unique class names, which will simplify
+the SCSS selectors.
+
+These SCSS styles can be put in a custom `branding package`_ into
+``paragon/_overrides.scss``.
+
+.. _branding package: https://github.com/openedx/brand-openedx
+
 Consequences
 ************
 
@@ -59,27 +101,17 @@ Consequences
 Positive
 ========
 
-* Styles and additional content (i.e. all the customizations to the component)
-  can be configured in the same place (or at least using the same API).
-* Can set defaults at build time, and overwrite them at runtime.
-* Have the option to do at build time.
-* Can customize for each MFE independently.
-* Using ``eox-tenant`` can customize per tenant (org, microsite).
+* There will be an option to make the MFE footer look similar to the legacy UI
+  footer, without having to create and maintain a fork.
+* Can add custom text/urls for links, unlike what branding v1 API allows.
 
 Negative
 ========
 
-* At the time of writing, Tutor doesn't pass ``env.config.js`` or environmental
-  variables at build time, which means that anyone using tutor directly, or
-  tools that are built on top of it (e.g. Grove, cookiecutter-openedx-devops)
-  will have to use ``MFE_CONFIG`` Web API.
-* There exist branding mechanism and theming mechanism for styling MFEs, and
-  the styles are expected to go there. The consequence of the decision above is
-  that the styles will be in a separate place.
-* Developers/designers would have to edit CSS styles and classes in the
-  python/yaml/js files, which can be inconvenient.
-* Configuration keys through which the customizations are exposed can
-  potentially overlap, causing collisions. Hard to catch and debug.
+* There are already parameters that allow configuring the footer links for the
+  legacy UI, which means that configuration will be duplicated (potentially in
+  multiple places), in cases when the aim is to make the links in the legacy UI
+  and MFE footers that same.
 
 Rejected Alternatives
 *********************
@@ -97,23 +129,30 @@ same as the cons from decoupling.
 Styling using CSS variables
 ===========================
 
-Exposing styling customizations through the CSS variables would give a benefit
-of being able to set the customizations in the branding package, together with
-the rest of the styles. The cons however, are that it would be harder to
-customize it for different MFEs and tenants, because you would need different
-branding packages for each, and the customization options would be limited to
-changing only the CSS attributes we decide can be changed, because you can't
-set arbitrary styles through a CSS variable, only a value for a CSS attribute.
-
-Styling using classes
-=====================
-
-We could add CSS classes to the component, so that the styles for those
-components could be defined in a branding package using the CSS classes as
-selectors. Pros and cons of this alternative are similar to the one above, for
-the exception that it is possible to define any number of CSS attributes in a
-style block, and child elements can be referenced using CSS selectors, allowing
-a greater degree of customisability.
+Exposing styling customizations through the CSS variables would be similar to
+styling via CSS classes, and it would be better aligned with the current
+philosophy of Paragon, since it prefers CSS variables over custom CSS classes.
+
+The cons however, is that you can only expose one CSS attribute per variable.
+This means that we would either heavily limit the styling options, or would
+have to create many variables for each element and CSS attribute.
+
+Brading API V1
+==============
+
+LMS already has an API endpoint which could be used to retrieve the links that
+are used in the footer (legacy UI footer uses the same API) in JSON format -
+``api/branding/v1/footer``.
+
+The pros of using this approach would be that legacy and MFE footer would use
+the same API and would have the same links, without having to duplicate the
+configuration.
+
+The cons of using this approach are:
+
+* It would be necessary to make an additional API call from an MFE to get the
+  links.
+* No custom links, only what is allowed by the branding API.
 
 .. References
 .. **********