Standardize plugin slots

arbrandes commented 4 months ago

Description

With this issue we're aiming to coordinate the following:

Standardize plugin slot name conventions

Every slot should adhere to the following conventions:

It should be reasonably easy to deduce what a slot is used for from its slot ID
Slot IDs should use snake case: footer_slot
Slot IDs should end with _slot

Standardize how slots are exposed

Instead of inserting PluginSlots randomly throughout the code, they should each be implemented in their own subdirectory of plugin-slots, like so:

src/plugin-slots
├── SequenceContainerSlot
│   ├── index.jsx
└── UnitTitleSlot
    ├── index.jsx

The component name itself should be suffixed with Slot.

Add clear documentation

The main README should have a section dedicated to pointing users to the README in the src/plugin-slots directory, whin in turn should contain a list of all slots available in the MFE in question. Each slot entry should then link to the README for each individual slot implementation, as per the directory structure below:

src/plugin-slots
├── README.md
└── UnitTitleSlot
    ├── images
    │   └── post_unit_title.png
    ├── index.jsx
    └── README.md

An individual slot's README should:

Explain what the slot's purpose is
Give a simple example of a plugin that utilizes that slot
Show, with screenshots, what the example plugin would look like on the page

Create slots as an example on every MFE supported by Tutor in Redwood

For each MFE supported by tutor-mfe, we'll give operators the option to use the Footer as a PluginSlot instead of forking frontend-component-footer.

To achieve this, we'll create a separate repository called frontend-slot-footer that provides a <FooterSlot /> implementation with <Footer /> from frontend-component-footer as its default content. Relevant MFEs will then be changed to depend on frontend-slot-footer instead of frontend-component-footer and replace all instances of <Footer /> with <FooterSlot />. This way, users that fork frontend-component-footer for customization will not need to take any action post-merge, while others that want to try out the new slot will be able to do so transparently.

- [ ] https://github.com/openedx/frontend-plugin-framework/pull/60
- [ ] https://github.com/openedx/frontend-plugin-framework/pull/61
- [ ] https://github.com/openedx/frontend-component-footer/pull/423
- [ ] https://github.com/openedx/frontend-component-footer/pull/427
- [ ] https://github.com/openedx/frontend-app-account/pull/1044
- [ ] https://github.com/openedx/frontend-app-communications/pull/201
- [ ] https://github.com/openedx/frontend-app-communications/pull/202
- [ ] https://github.com/openedx/frontend-app-discussions/pull/698
- [ ] https://github.com/openedx/frontend-app-discussions/pull/701
- [ ] https://github.com/openedx/frontend-app-gradebook/pull/391
- [ ] https://github.com/openedx/frontend-app-learning/pull/1381
- [ ] https://github.com/openedx/frontend-app-learner-dashboard/pull/345
- [ ] https://github.com/openedx/frontend-app-profile/pull/1022
- [ ] https://github.com/openedx/frontend-app-profile/pull/1017
- [ ] https://github.com/openedx/frontend-app-ora-grading/pull/331
- [ ] https://github.com/openedx/frontend-template-application/pull/799
- [ ] Create ADR in the FPF repository to codify what was done here

### Redwood backports
- [ ] https://github.com/openedx/frontend-app-account/pull/1058
- [ ] https://github.com/openedx/frontend-app-communications/pull/203
- [ ] https://github.com/openedx/frontend-app-discussions/pull/714
- [ ] https://github.com/openedx/frontend-app-gradebook/pull/397
- [ ] https://github.com/openedx/frontend-app-learning/pull/1408
- [ ] https://github.com/openedx/frontend-app-learner-dashboard/pull/356
- [ ] https://github.com/openedx/frontend-app-profile/pull/1030
- [ ] https://github.com/openedx/frontend-app-ora-grading/pull/332

brian-smith-tcril commented 4 months ago

Footer Slots:

Authn (no footer)
Account https://github.com/openedx/frontend-app-account/pull/1044 https://github.com/openedx/frontend-app-account/pull/1048 https://github.com/openedx/frontend-app-account/pull/1050
Communications https://github.com/openedx/frontend-app-communications/pull/201 https://github.com/openedx/frontend-app-communications/pull/202
Course Authoring (Studio Footer)
Discussions https://github.com/openedx/frontend-app-discussions/pull/698 https://github.com/openedx/frontend-app-discussions/pull/701
Gradebook https://github.com/openedx/frontend-app-gradebook/pull/391
Learner Dashboard https://github.com/openedx/frontend-app-learner-dashboard/pull/345
Learning https://github.com/openedx/frontend-app-learning/pull/1381
ORA Grading https://github.com/openedx/frontend-app-ora-grading/pull/331
Profile https://github.com/openedx/frontend-app-profile/pull/1017

Other Slots:

https://github.com/openedx/frontend-app-learner-dashboard/issues/344

arbrandes commented 4 months ago

We re-examined our stance on asking users that fork frontend-component-footer to take action after this work lands, and are going instead with an approach that takes that customization path into account. From the updated description:

For each MFE supported by tutor-mfe, we'll give operators the option to use the Footer as a PluginSlot instead of forking frontend-component-footer.

To achieve this, we'll create a separate repository called frontend-slot-footer that provides a <FooterSlot /> implementation with <Footer /> from frontend-component-footer as its default content. Relevant MFEs will then be changed to depend on frontend-slot-footer instead of frontend-component-footer and replace all instances of <Footer /> with <FooterSlot />. This way, users that fork frontend-component-footer for customization will not need to take any action post-merge, while others that want to try out the new slot will be able to do so transparently.

davidjoy commented 4 months ago

Would it make sense to just put FooterSlot in the existing footer repository, or in frontend-platform to avoid needing another repository? (I haven't thought this through completely, but figure you have)

brian-smith-tcril commented 4 months ago

Would it make sense to just put FooterSlot in the existing footer repository

We tried this first, but ran into issues. The options to make this possible would either be:

Make it so the exported Footer component includes the FooterSlot
- This felt less than ideal from a semantic perspective. It isn't clear as a consumer if you have the slot or not.
Export the FooterSlot component as a named export
- This is what we tried at first, it was a problem for people that use forked footers because their forks didn't export that component, so the MFEs were expecting something the fork didn't provide.

or in frontend-platform

Hadn't considered that.

openedx / wg-frontend