feat!: organize plugin slots as components, add footer slot (openedx#1408)

arbrandes · brian-smith-tcril · web-flow · commit c8a95eb93d8d · 2024-06-06T15:06:54.000-03:00
BREAKING CHANGE: slot ids have been changed for consistency
* `sequence_container_plugin` -&gt; `sequence_container_slot`
* `unit_title_plugin` -&gt; `unit_title_slot`

Co-authored-by: Brian Smith &lt;112954497+brian-smith-tcril@users.noreply.github.com&gt;
diff --git a/README.rst b/README.rst
@@ -100,6 +100,12 @@ The Learning MFE is similar to all the other Open edX MFEs. Read the Open
 edX Developer Guide's section on
 `MFE applications <https://edx.readthedocs.io/projects/edx-developer-docs/en/latest/developers_guide/micro_frontends_in_open_edx.html>`_.
 
+Plugins
+=======
+This MFE can be customized using `Frontend Plugin Framework <https://github.com/openedx/frontend-plugin-framework>`_.
+
+The parts of this MFE that can be customized in that manner are documented `here </src/plugin-slots>`_.
+
 Environment Variables
 ======================
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -31,7 +31,6 @@
   },
   "dependencies": {
     "@edx/brand": "npm:@openedx/brand-openedx@^1.2.2",
-    "@edx/frontend-component-footer": "^13.0.4",
     "@edx/frontend-component-header": "^5.0.2",
     "@edx/frontend-lib-learning-assistant": "^2.0.0",
     "@edx/frontend-lib-special-exams": "^3.0.1",
@@ -43,7 +42,8 @@
     "@fortawesome/free-regular-svg-icons": "5.15.4",
     "@fortawesome/free-solid-svg-icons": "5.15.4",
     "@fortawesome/react-fontawesome": "^0.1.4",
-    "@openedx/frontend-plugin-framework": "^1.0.2",
+    "@openedx/frontend-plugin-framework": "^1.1.2",
+    "@openedx/frontend-slot-footer": "^1.0.2",
     "@openedx/paragon": "^22.3.0",
     "@popperjs/core": "2.11.8",
     "@reduxjs/toolkit": "1.8.1",
diff --git a/src/courseware/course/sequence/Sequence.jsx b/src/courseware/course/sequence/Sequence.jsx
@@ -9,11 +9,11 @@ import {
 import { useIntl } from '@edx/frontend-platform/i18n';
 import { useSelector } from 'react-redux';
 import SequenceExamWrapper from '@edx/frontend-lib-special-exams';
-import { PluginSlot } from '@openedx/frontend-plugin-framework';
 
 import PageLoading from '@src/generic/PageLoading';
 import { useModel } from '@src/generic/model-store';
 import { useSequenceBannerTextAlert, useSequenceEntranceExamAlert } from '@src/alerts/sequence-alerts/hooks';
+import SequenceContainerSlot from '../../../plugin-slots/SequenceContainerSlot';
 
 import { getCoursewareOutlineSidebarSettings } from '../../data/selectors';
 import CourseLicense from '../course-license';
@@ -202,13 +202,7 @@ const Sequence = ({
         </div>
         {isNewDiscussionSidebarViewEnabled ? <NewSidebar /> : <Sidebar />}
       </div>
-      <PluginSlot
-        id="sequence_container_plugin"
-        pluginProps={{
-          courseId,
-          unitId,
-        }}
-      />
+      <SequenceContainerSlot courseId={courseId} unitId={unitId} />
     </>
   );
 
diff --git a/src/courseware/course/sequence/Unit/__snapshots__/index.test.jsx.snap b/src/courseware/course/sequence/Unit/__snapshots__/index.test.jsx.snap
@@ -28,14 +28,9 @@ exports[`Unit component output snapshot: not bookmarked, do not show content 1`]
     >
       unit-title
     </h3>
-    <PluginSlot
-      id="unit_title_plugin"
-      pluginProps={
-        Object {
-          "courseId": "test-course-id",
-          "unitId": "test-props-id",
-        }
-      }
+    <UnitTitleSlot
+      courseId="test-course-id"
+      unitId="test-props-id"
     />
   </div>
   <h2
diff --git a/src/courseware/course/sequence/Unit/index.jsx b/src/courseware/course/sequence/Unit/index.jsx
@@ -7,14 +7,14 @@ import { useIntl } from '@edx/frontend-platform/i18n';
 import { useModel } from '@src/generic/model-store';
 import { usePluginsCallback } from '@src/generic/plugin-store';
 
-import { PluginSlot } from '@openedx/frontend-plugin-framework';
 import BookmarkButton from '../../bookmark/BookmarkButton';
 import messages from '../messages';
 import ContentIFrame from './ContentIFrame';
 import UnitSuspense from './UnitSuspense';
 import { modelKeys, views } from './constants';
 import { useExamAccess, useShouldDisplayHonorCode } from './hooks';
 import { getIFrameUrl } from './urls';
+import UnitTitleSlot from '../../../../plugin-slots/UnitTitleSlot';
 
 const Unit = ({
   courseId,
@@ -43,13 +43,7 @@ const Unit = ({
     <div className="unit">
       <div className="mb-0">
         <h3 className="h3">{unit.title}</h3>
-        <PluginSlot
-          id="unit_title_plugin"
-          pluginProps={{
-            courseId,
-            unitId: id,
-          }}
-        />
+        <UnitTitleSlot courseId={courseId} unitId={id} />
       </div>
       <h2 className="sr-only">{formatMessage(messages.headerPlaceholder)}</h2>
       <BookmarkButton
diff --git a/src/generic/CourseAccessErrorPage.jsx b/src/generic/CourseAccessErrorPage.jsx
@@ -1,9 +1,9 @@
 import React, { useEffect } from 'react';
 import { LearningHeader as Header } from '@edx/frontend-component-header';
-import Footer from '@edx/frontend-component-footer';
 import { useParams, Navigate } from 'react-router-dom';
 import { useDispatch, useSelector } from 'react-redux';
 import { injectIntl, intlShape } from '@edx/frontend-platform/i18n';
+import FooterSlot from '@openedx/frontend-slot-footer';
 import useActiveEnterpriseAlert from '../alerts/active-enteprise-alert';
 import { AlertList } from './user-messages';
 import { fetchDiscussionTab } from '../course-home/data/thunks';
@@ -32,7 +32,7 @@ const CourseAccessErrorPage = ({ intl }) => {
         <PageLoading
           srMessage={intl.formatMessage(messages.loading)}
         />
-        <Footer />
+        <FooterSlot />
       </>
     );
   }
@@ -51,7 +51,7 @@ const CourseAccessErrorPage = ({ intl }) => {
           }}
         />
       </main>
-      <Footer />
+      <FooterSlot />
     </>
   );
 };
diff --git a/src/plugin-slots/FooterSlot/README.md b/src/plugin-slots/FooterSlot/README.md
@@ -0,0 +1,50 @@
+# Footer Slot
+
+### Slot ID: `footer_slot`
+
+## Description
+
+This slot is used to replace/modify/hide the footer.
+
+The implementation of the `FooterSlot` component lives in [the `frontend-slot-footer` repository](https://github.com/openedx/frontend-slot-footer/).
+
+## Example
+
+The following `env.config.jsx` will replace the default footer.
+
+![Screenshot of Default Footer](./images/default_footer.png)
+
+with a simple custom footer
+
+![Screenshot of Custom Footer](./images/custom_footer.png)
+
+```jsx
+import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
+
+const config = {
+  pluginSlots: {
+    footer_slot: {
+      plugins: [
+        {
+          // Hide the default footer
+          op: PLUGIN_OPERATIONS.Hide,
+          widgetId: 'default_contents',
+        },
+        {
+          // Insert a custom footer
+          op: PLUGIN_OPERATIONS.Insert,
+          widget: {
+            id: 'custom_footer',
+            type: DIRECT_PLUGIN,
+            RenderWidget: () => (
+              <h1 style={{textAlign: 'center'}}>🦶</h1>
+            ),
+          },
+        },
+      ]
+    }
+  },
+}
+
+export default config;
+```
diff --git a/src/plugin-slots/FooterSlot/images/custom_footer.png b/src/plugin-slots/FooterSlot/images/custom_footer.png
diff --git a/src/plugin-slots/FooterSlot/images/default_footer.png b/src/plugin-slots/FooterSlot/images/default_footer.png
diff --git a/src/plugin-slots/README.md b/src/plugin-slots/README.md
@@ -0,0 +1,5 @@
+# `frontend-app-learning` Plugin Slots
+
+* [`footer_slot`](./FooterSlot/)
+* [`sequence_container_slot`](./SequenceContainerSlot/)
+* [`unit_title_slot`](./UnitTitleSlot/)
diff --git a/src/plugin-slots/SequenceContainerSlot/README.md b/src/plugin-slots/SequenceContainerSlot/README.md
@@ -0,0 +1,45 @@
+# Sequence Container Slot
+
+### Slot ID: `sequence_container_slot`
+### Props:
+* `courseId`
+* `unitId`
+
+## Description
+
+This slot is used for adding content after the Sequence content section.
+
+## Example
+
+The following `env.config.jsx` will render the `course_id` and `unit_id` of the course as `<p>` elements in a `<div>`.
+
+![Screenshot of Content added after the Sequence Container](./images/post_sequence_container.png)
+
+```js
+import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
+
+const config = {
+  pluginSlots: {
+    sequence_container_slot: {
+      plugins: [
+        {
+          // Insert custom content after sequence content
+          op: PLUGIN_OPERATIONS.Insert,
+          widget: {
+            id: 'custom_sequence_container_content',
+            type: DIRECT_PLUGIN,
+            RenderWidget: ({courseId, unitId}) => (
+              <div>
+                <p>📚: {courseId}</p>
+                <p>📙: {unitId}</p>
+              </div>
+            ),
+          },
+        },
+      ]
+    }
+  },
+}
+
+export default config;
+```
diff --git a/src/plugin-slots/SequenceContainerSlot/images/post_sequence_container.png b/src/plugin-slots/SequenceContainerSlot/images/post_sequence_container.png
diff --git a/src/plugin-slots/SequenceContainerSlot/index.jsx b/src/plugin-slots/SequenceContainerSlot/index.jsx
@@ -0,0 +1,23 @@
+import PropTypes from 'prop-types';
+import { PluginSlot } from '@openedx/frontend-plugin-framework';
+
+const SequenceContainerSlot = ({ courseId, unitId }) => (
+  <PluginSlot
+    id="sequence_container_slot"
+    pluginProps={{
+      courseId,
+      unitId,
+    }}
+  />
+);
+
+SequenceContainerSlot.propTypes = {
+  courseId: PropTypes.string.isRequired,
+  unitId: PropTypes.string,
+};
+
+SequenceContainerSlot.defaultProps = {
+  unitId: null,
+};
+
+export default SequenceContainerSlot;
diff --git a/src/plugin-slots/UnitTitleSlot/README.md b/src/plugin-slots/UnitTitleSlot/README.md
@@ -0,0 +1,45 @@
+# Unit Title Slot
+
+### Slot ID: `unit_title_slot`
+### Props:
+* `courseId`
+* `unitId`
+
+## Description
+
+This slot is used for adding content after the Unit title.
+
+## Example
+
+The following `env.config.jsx` will render the `course_id` and `unit_id` of the course as `<p>` elements.
+
+![Screenshot of Content added after the Unit Title](./images/post_unit_title.png)
+
+```js
+import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
+
+const config = {
+  pluginSlots: {
+    unit_title_slot: {
+      plugins: [
+        {
+          // Insert custom content after unit title
+          op: PLUGIN_OPERATIONS.Insert,
+          widget: {
+            id: 'custom_unit_title_content',
+            type: DIRECT_PLUGIN,
+            RenderWidget: ({courseId, unitId}) => (
+              <>
+                <p>📚: {courseId}</p>
+                <p>📙: {unitId}</p>
+              </>
+            ),
+          },
+        },
+      ]
+    }
+  },
+}
+
+export default config;
+```
diff --git a/src/plugin-slots/UnitTitleSlot/images/post_unit_title.png b/src/plugin-slots/UnitTitleSlot/images/post_unit_title.png
diff --git a/src/plugin-slots/UnitTitleSlot/index.jsx b/src/plugin-slots/UnitTitleSlot/index.jsx
@@ -0,0 +1,19 @@
+import PropTypes from 'prop-types';
+import { PluginSlot } from '@openedx/frontend-plugin-framework';
+
+const UnitTitleSlot = ({ courseId, unitId }) => (
+  <PluginSlot
+    id="unit_title_slot"
+    pluginProps={{
+      courseId,
+      unitId,
+    }}
+  />
+);
+
+UnitTitleSlot.propTypes = {
+  courseId: PropTypes.string.isRequired,
+  unitId: PropTypes.string.isRequired,
+};
+
+export default UnitTitleSlot;
diff --git a/src/tab-page/TabPage.jsx b/src/tab-page/TabPage.jsx
@@ -4,9 +4,9 @@ import { injectIntl, intlShape } from '@edx/frontend-platform/i18n';
 import { useDispatch, useSelector } from 'react-redux';
 import { Navigate } from 'react-router-dom';
 
-import Footer from '@edx/frontend-component-footer';
 import { Toast } from '@openedx/paragon';
 import { LearningHeader as Header } from '@edx/frontend-component-header';
+import FooterSlot from '@openedx/frontend-slot-footer';
 import PageLoading from '../generic/PageLoading';
 import { getAccessDeniedRedirectUrl } from '../shared/access';
 import { useModel } from '../generic/model-store';
@@ -80,7 +80,7 @@ const TabPage = ({ intl, ...props }) => {
           {intl.formatMessage(messages.failure)}
         </p>
       )}
-      <Footer />
+      <FooterSlot />
     </>
   );
 };
