docs: add an ADR for the footer links and styling

openedx · Aug 21, 2023 · 8593f4b · 8593f4b
1 parent 2100dc1
commit 8593f4b
Showing 1 changed file with 221 additions and 0 deletions.
diff --git a/docs/decisions/0002-footer-links.rst b/docs/decisions/0002-footer-links.rst
@@ -0,0 +1,221 @@
+2. Footer Links
+########################
+.. The title should be a short noun phrase. For example, "1. Django IDA" or "9. LDAP for Multitenant Integration"; filename should be lowercase with punctuation removed and spaces replaced by dash
+
+Status
+******
+
+**Draft (=> Accepted)**
+
+.. **Accepted** *2023-05-11*
+
+.. Standard statuses
+    - **Draft** if the decision is newly proposed and in active discussion
+    - **Provisional** if the decision is still preliminary and in experimental phase
+    - **Accepted** *(date)* once it is agreed upon
+    - **Superseded** *(date)* with a reference to its replacement if a later ADR changes or reverses the decision
+
+    If an ADR has Draft status and the PR is under review, you can either use the intended final status (e.g. Provisional, Accepted, etc.), or you can clarify both the current and intended status using something like the following: "Draft (=> Provisional)". Either of these options is especially useful if the merged status is not intended to be Accepted.
+
+Context
+*******
+
+.. This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.
+
+The footer component is basic - it only has a trademark logo and a language
+selector. It doesn't look similar to the legacy UI footer.
+
+It also doesn't have many customization options. You can customize
+LMS base URL and trade mark logo.
+
+If you want to have more advanced customizations, it's necessary to fork the
+component, modify it, and then install the fork as a package instead of the
+default footer at build time of MFEs.
+
+We want to make the MFE footer to closer resemble the legacy UI footer by
+adding the same footer links as in the legacy UI, and to make it easier to
+style the footer component.
+
+Decision
+********
+
+.. This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …"
+
+Links
+=====
+
+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 = {
+            ENABLE_BRANDING_API: true,
+            ...
+        };
+
+        export default config;
+
+* At runtime, via ``MFE_CONFIG`` in LMS's Django settings:
+
+    .. code-block:: python
+
+        MFE_CONFIG = {
+            "ENABLE_BRANDING_API": True,
+        }
+
+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
+
+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
+************
+
+.. This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.
+
+Positive
+========
+
+* 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
+========
+
+* 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
+*********************
+
+.. This section lists alternate options considered, described briefly, with pros and cons.
+
+React component props API
+=========================
+
+Instead of reading the configuration values in the component, we could be
+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.
+
+MFE Config API
+==============
+
+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.
+
+However, it would require duplication the configuration for the links. Also,
+branding API has more data and internationalization for links text.
+
+Third party footer
+==================
+
+The proposed changes won't affect anyone who won't use this feature. And these
+changes eliminate some frequent reasons for forking the footer component. Thus
+creating a third party footer for these features, instead of upstreaming them
+seems unjustified.
+
+.. References
+.. **********
+
+.. (Optional) List any additional references here that would be useful to the future reader. See `Documenting Architecture Decisions`_ for further input.