docs: rewrite the ADR

Author: Cup0fCoffee

docs/decisions/0002-footer-links.rst

@@ -44,21 +44,94 @@ Decision
 Links
 =====
 
-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:
+LMS already has API that is used by the legacy UI footer. Since our goal is to
+make the legacy and MFE footers similar, it only makes sence to use the same
+API.
+
+``<LMS_BASE>/api/branding/v1/footer`` is the endpoint that can be used to
+retreive the information about the footer. A GET request has to be made, with
+``Accepts: application/json`` header, to get a JSON object with footer links.
+
+Example:
+.. code-block::
+
+    GET /api/branding/v1/footer
+    Accepts: application/json
+
+    {
+        "navigation_links": [
+            {
+              "url": "http://example.com/about",
+              "name": "about",
+              "title": "About"
+            },
+            # ...
+        ],
+        "social_links": [
+            {
+                "url": "http://example.com/social",
+                "name": "facebook",
+                "icon-class": "fa-facebook-square",
+                "title": "Facebook",
+                "action": "Sign up on Facebook!"
+            },
+            # ...
+        ],
+        "mobile_links": [
+            {
+                "url": "http://example.com/android",
+                "name": "google",
+                "image": "http://example.com/google.png",
+                "title": "Google"
+            },
+            # ...
+        ],
+        "legal_links": [
+            {
+                "url": "http://example.com/terms-of-service.html",
+                "name": "terms_of_service",
+                "title': "Terms of Service"
+            },
+            # ...
+        ],
+        "openedx_link": {
+            "url": "https://open.edx.org",
+            "title": "Powered by Open edX",
+            "image": "http://example.com/openedx.png"
+        },
+        "logo_image": "http://example.com/static/images/logo.png",
+        "copyright": "edX, Open edX and their respective logos are registered trademarks of edX Inc."
+    }
+
+
+We are interested in keys that end with ``_links``:
+
+* ``social_links``
+* ``buisiness_links``
+* ``mobile_links``
+* ``connect_links``
+* ``openedx_links``
+* ``navigation_links``
+* ``legal_links``
+
+We don't need ``logo_image`` as it's already supplied via props or MFE config.
+We will ignore ``edx_org_link``, as it's specific to the edX only, and most of
+the instances that are not hosted with edX remove it. The other keys, like
+``copyright``, can be implemented in the future.
+
+We want the footer to stay the same for the users who don't want to use this
+feature. So we are going to hide it behind a feature flag
+``ENABLE_BRANDING_API``, that can be set via `MFE's config mechanism`_. By
+default it will have value of ``false``, and it will be possible to change it
+in various ways:
+
+* At build time, 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"},
-            ],
+            ENABLE_BRANDING_API: true,
+            ...
         };
 
         export default config;
@@ -68,15 +141,14 @@ That would allow to specify a list of links in various ways:
     .. 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"},
-            ],
+            "ENABLE_BRANDING_API": True,
         }
 
-In case the array is undefined or empty, we won't render any links (or it's
-container).
+If the feature flag is set to ``true``, we will query the API endpoint and get
+the links from the response.
+
+This will allow the links in the legacy and MFE footers to be the same, and
+configured via the same parameters in the LMS configuration.
 
 .. _MFE's config mechanism: https://github.com/openedx/frontend-platform/blob/master/src/config.js
 
@@ -101,17 +173,17 @@ Consequences
 Positive
 ========
 
-* 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.
+* Legacy and MFE footers will have the same links.
+* No need to duplicate the configuration, since both footers will use the
+  branding API as a source of truth.
 
 Negative
 ========
 
-* 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.
+* An additional API request will be required when an MFE is openned.
+* Can't easily add custom links. We can in the future implement v2 of the API,
+  or combine it with the MFE Config API to allow adding custom links.
+* Will have to deal with limitations of the branding API.
 
 Rejected Alternatives
 *********************
@@ -126,33 +198,14 @@ reading it somewhere else, and passing the values as props to the react
 component. We couldn't identify any pros to this approach, and the cons are the
 same as the cons from decoupling.
 
-Styling using CSS variables
-===========================
-
-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
+MFE Config API
 ==============
 
-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:
+We could've used MFE Config to pass the links to the footer. The main advantage
+would be that easy to set custom links and text.
 
-* 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.
+However, it would require duplication the configuration for the links. Also,
+branding API has more data and internationalization for links text.
 
 Third party footer
 ==================