feat: support frontend plugins via env.config.jsx #234

arbrandes · 2024-11-11T21:57:55Z

This provides a mechanism to configure frontend plugins using patches to a base env.config.jsx, in such a way that multiple plugins can take advantage of the file (including for purposes beyond frontend plugins) without clobbering each other.

This is an alternate approach to #233.

This provides a mechanism to configure frontend plugins using patches to a base `env.config.jsx`, in such a way that multiple plugins can take advantage of the file (including for purposes beyond frontend plugins) without clobbering each other.

arbrandes · 2024-11-11T22:10:17Z

@hinakhadim, I'm particularly interested in your take on whether the provided patches are sufficient for Indigo.

brian-smith-tcril

Overall this is wonderful! Extremely well documented. Thank you so much!

I left one comment with a small suggestion, and I think one other thing isn't documented here.

We discussed having an "escape hatch" for site operators that want to have total control over the env.config.jsx files. I think it'd be nice to add documentation for the "escape hatch" strategy including:

Where to put env.config.jsx files
How to get the tutor-mfe image build to pick up those env.config.jsx files
Downsides to using the "escape hatch" method over the recommended patch method
- Example: needing to manually add code to env.config.jsx files that plugins would add automatically.

brian-smith-tcril · 2024-11-12T15:24:41Z

README.rst

+mfe-env-config-static-imports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use this patch for any additional static imports you need in ``env.config.jsx``. They will be available here if you used the `mfe-docker-post-npm-install patch <#mfe-docker-post-npm-install>`_ to install an NPM package globally.
+
+It gets rendered at the very top of the file. You should use normal `ES6 import syntax <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import>`_.
+
+File changed: ``tutormfe/templates/mfe/build/mfe/env.config.jsx``
+
+mfe-env-config-head
+~~~~~~~~~~~~~~~~~~~
+
+Use this patch for arbitrary ``env.config.jsx`` javascript code. It gets rendered immediately after static imports, and is particularly useful for defining slightly more complex components for use in plugin slots.
+
+File changed: ``tutormfe/templates/mfe/build/mfe/env.config.jsx``


Since mfe-env-config-static-imports-{} and mfe-env-config-dynamic-imports-{} don't exist, it might be nice to note these are only available as a "all MFEs" thing and not possible to use on a per-MFE basis.

Edit: same applies to mfe-env-config-tail

hinakhadim · 2024-11-13T19:48:20Z

This is an excellent approach! It enables plugin developers to make adjustments to env.config.jsx indirectly, preserving the original file. In essence, it should function well even when multiple plugins are involved and will work well for indigo. The documentation is very well done, outstanding work!

If possible, could we include an example of this approach in the documentation for better understanding?
One consideration: as the list of plugin_slots grows, it might lead to a large number of patches. I’m not entirely sure about the implications of this. In other words, we have to manage the list of plugin_slots. If a plugin_slot name changes, then we have to update it here too. I am assuming it is based on the point 3 in this conversation.

I’ll test this out and will be happy to share feedback based on testing with tutor-indigo.

sarina

Reviewed just the README, looks good.

sarina · 2024-11-14T14:46:46Z

README.rst

+
+Let's take a closer look at what's happening here, starting with the patch name: the prefix is ``mfe-env-config-plugin-`` followed by the name of the slot you're trying to configure. In this case, ``footer_slot``.  (There's a full list of `possible slot names <#mfe-env-config-plugin-slot-catalog>`_ below.) Next, we're hiding the default contents of the footer with a ``PLUGIN_OPERATIONS.Hide``. (Refer to the `frontend-plugin-framework README <https://github.com/openedx/frontend-plugin-framework/#>`_ for a full description of the possible plugin types and operations.) The ``default_contents`` widget ID always refers to what's in an unconfigured slot. Finally, we use ``PLUGIN_OPERATIONS.Insert`` to add our custom JSX component, composed of a simple ``<h1>`` message.  We give it a widgetID of ``custom_footer``.
+
+That's it!  If you rebuild the ``mfe`` image after enabling the plugin, "This is the footer." should appear at the bottom of every MFE.


Could this be linked to instructions to rebuild the mfe image?

sarina · 2024-11-14T14:47:47Z

README.rst

+
+.. _mfe-env-config-plugin-slot-catalog:
+
+Here's a list of the currently available frontend plugin slots, separated by category. The documentation of each slot can be found by following the corresponding link.


What's the strategy to keep this document up to date? Is there a template for new plugin documentation within the MFE that might include a note to update the tutor readme?

I figure the strategy can be similar to the one for new feature and waffle flags in edx-platform. Which is to say, one of two things happens:

As soon as a new flag/slot is merged in the upstream repo, somebody also opens a PR to Tutor to support it. This could indeed benefit from some sort of automated reminder, but given that new MFE features are more and more commonly required to work with PR sandboxes as part of the review process, and that PR sandboxes are built with Tutor, adding these to Tutor nightly will simply be a built-in step in getting the slot merged.

When Tutor and its plugins are updated when a new new release is coming out, part of the work is combing through upstream repos for added and changed features. This should become less and less necessary as Tutor nightly gets "automatically" updated as described above, but if by any chance a slot or two were missed, this is where they would be added.

Sounds good, ty

Oh, and one neat thing about this PR is that it will make it possible for PR sandboxes to configure slots for testing (once the Grove plugin is updated to match).

This approach has one major drawback: Implementing a new slot will require making an upstream PR to tutor-mfe: this will cause a lot of back-and-forth, especially as we intend to have many more plugin slots in Open edX.

Another minor drawback is the requirement to create a Tutor plugin for users who implement their own plugin slots.

As far as I understand, there is little benefit to having an explicit list of slots here. All it gives us is some syntax sugar. We can achieve a similar result with the following MFE-specific filter:

tutormfe.hooks.Filters.PLUGIN_SLOTS.add_item(( "profile", "footer_slot", """ { /* Hide the global footer we defined earlier. */ op: PLUGIN_OPERATIONS.Hide, widgetId: 'custom_footer', }""" )) tutormfe.hooks.Filters.PLUGIN_SLOTS.add_item(( "profile", "footer_slot", """{ /* Insert a custom footer specific to the Profile MFE. */ op: PLUGIN_OPERATIONS.Insert, widget: { id: 'custom_profile_footer', type: DIRECT_PLUGIN, RenderWidget: () => ( <h1>This is the Profile MFE's footer.</h1> ) } } ))"""

Yes, but listing all the slots gives us one majoir advantage: it will be very evident what slots are actually available for a particular version of Tutor. Sure, we can still document them here anyway, but if we make it so a slot only works if it's explicitly supported, then it's also obligatory to document a slot when it's added here.

In any case, I'll give the PLUGIN_SLOTS filter a shot. I'm not sure yet if it's going to work with the single env.config.jsx approach I tried here.

arbrandes · 2024-11-14T15:48:52Z

tutormfe/templates/mfe/build/mfe/env.config.jsx

+
+    {%- for app_name, app in iter_mfes() %}
+    if (process.env.npm_package_name == '@edx/frontend-app-{{ app_name }}') {
+      {%- if patch("mfe-env-config-dynamic-imports-{}".format(app_name)) %}


I just realized this if is redundant. I had another try-catch here before, but it's not necessary, and no longer is the if. I'll rip it out.

regisb

I like this approach better but I have an issue with the explicit list of plugin slots. Let me know what you think of my suggestion.

regisb · 2024-11-19T11:23:51Z

tutormfe/plugin.py

 @tutor_hooks.Actions.PLUGIN_LOADED.add()
 def _clear_get_mfes_cache(_name: str) -> None:
    """
    Don't forget to clear cache, or we'll have some strange surprises...
    """
    get_mfes.cache_clear()
+    get_slots.cache_clear()


Let's not do that. This will break in some edge cases. Instead, both get_slots and get_mfes should use tutor.hooks.lru_cache.

regisb · 2024-11-19T11:30:38Z

README.rst

+
+.. _mfe-env-config-plugin-slot-catalog:
+
+Here's a list of the currently available frontend plugin slots, separated by category. The documentation of each slot can be found by following the corresponding link.


This approach has one major drawback: Implementing a new slot will require making an upstream PR to tutor-mfe: this will cause a lot of back-and-forth, especially as we intend to have many more plugin slots in Open edX.

Another minor drawback is the requirement to create a Tutor plugin for users who implement their own plugin slots.

As far as I understand, there is little benefit to having an explicit list of slots here. All it gives us is some syntax sugar. We can achieve a similar result with the following MFE-specific filter:

tutormfe.hooks.Filters.PLUGIN_SLOTS.add_item(( "profile", "footer_slot", """ { /* Hide the global footer we defined earlier. */ op: PLUGIN_OPERATIONS.Hide, widgetId: 'custom_footer', }""" )) tutormfe.hooks.Filters.PLUGIN_SLOTS.add_item(( "profile", "footer_slot", """{ /* Insert a custom footer specific to the Profile MFE. */ op: PLUGIN_OPERATIONS.Insert, widget: { id: 'custom_profile_footer', type: DIRECT_PLUGIN, RenderWidget: () => ( <h1>This is the Profile MFE's footer.</h1> ) } } ))"""

arbrandes changed the base branch from master to nightly November 11, 2024 21:59

arbrandes force-pushed the frontend-plugin-support branch from 92e964b to 5846c79 Compare November 11, 2024 22:01

arbrandes changed the title ~~frontend plugin support~~ feat: support frontend plugins via env.config.jsx Nov 11, 2024

arbrandes force-pushed the frontend-plugin-support branch from 5846c79 to be1f804 Compare November 11, 2024 22:04

arbrandes mentioned this pull request Nov 11, 2024

docs: Add info on how to use frontend plugin slots #233

Open

arbrandes requested review from regisb and hinakhadim November 11, 2024 22:09

brian-smith-tcril reviewed Nov 12, 2024

View reviewed changes

arbrandes mentioned this pull request Nov 13, 2024

Support Javascript configuration #199

Open

sarina reviewed Nov 14, 2024

View reviewed changes

arbrandes commented Nov 14, 2024

View reviewed changes

regisb reviewed Nov 19, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: support frontend plugins via env.config.jsx #234

feat: support frontend plugins via env.config.jsx #234

arbrandes commented Nov 11, 2024 •

edited

Loading

arbrandes commented Nov 11, 2024

brian-smith-tcril left a comment

brian-smith-tcril Nov 12, 2024

hinakhadim commented Nov 13, 2024

sarina left a comment

sarina Nov 14, 2024

sarina Nov 14, 2024

arbrandes Nov 14, 2024

sarina Nov 14, 2024

arbrandes Nov 14, 2024

regisb Nov 19, 2024

arbrandes Nov 20, 2024

arbrandes Nov 14, 2024

regisb left a comment

regisb Nov 19, 2024

regisb Nov 19, 2024


		Let's take a closer look at what's happening here, starting with the patch name: the prefix is ``mfe-env-config-plugin-`` followed by the name of the slot you're trying to configure. In this case, ``footer_slot``. (There's a full list of `possible slot names <#mfe-env-config-plugin-slot-catalog>`_ below.) Next, we're hiding the default contents of the footer with a ``PLUGIN_OPERATIONS.Hide``. (Refer to the `frontend-plugin-framework README <https://github.com/openedx/frontend-plugin-framework/#>`_ for a full description of the possible plugin types and operations.) The ``default_contents`` widget ID always refers to what's in an unconfigured slot. Finally, we use ``PLUGIN_OPERATIONS.Insert`` to add our custom JSX component, composed of a simple ``<h1>`` message. We give it a widgetID of ``custom_footer``.

		That's it! If you rebuild the ``mfe`` image after enabling the plugin, "This is the footer." should appear at the bottom of every MFE.


		.. _mfe-env-config-plugin-slot-catalog:

		Here's a list of the currently available frontend plugin slots, separated by category. The documentation of each slot can be found by following the corresponding link.

feat: support frontend plugins via env.config.jsx #234

Are you sure you want to change the base?

feat: support frontend plugins via env.config.jsx #234

Conversation

arbrandes commented Nov 11, 2024 • edited Loading

arbrandes commented Nov 11, 2024

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hinakhadim commented Nov 13, 2024

sarina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

regisb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arbrandes commented Nov 11, 2024 •

edited

Loading