@fylinde-openedx/frontend-plugin-framework

Frontend Plugin Framework
##########################

|license-badge| |status-badge| |ci-badge| |codecov-badge|

.. |license-badge| image:: https://img.shields.io/github/license/openedx/frontend-plugin-framework.svg
:target: https://github.com/openedx/frontend-plugin-framework/blob/master/LICENSE
:alt: License

.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen

.. |ci-badge| image:: https://github.com/openedx/frontend-plugin-framework/actions/workflows/ci.yml/badge.svg
:target: https://github.com/openedx/frontend-plugin-framework/actions/workflows/ci.yml
:alt: Continuous Integration

.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-plugin-framework/coverage.svg?branch=master
:target: https://codecov.io/github/openedx/frontend-plugin-framework?branch=master
:alt: Codecov

Purpose
=======

The Frontend Plugin Framework is designed to be an extension point to customize an Open edX MFE. This framework supports two types of plugins: iFrame-based and "Direct" plugins.

A Direct plugin allows for a component in the Host MFE -- or a React dependency -- to be made into a plugin and inserted in a plugin slot within the Host MFE.

The iFrame-based Plugin allows for a component that lives in another MFE (the Child MFE) to be plugged into a slot in
the Host MFE.

The primary way this is made possible is through JS-based configurations, where the changes to a plugin slot are defined
(see 'Plugin Operations').

Getting Started
===============
Using the Example Apps
----------------------

1. Run `make requirements in the root directory.

2. Run npm run start in the root directory.

3. Open another terminal and run npm run start:example to start the example app. You can visit http://localhost:8080 to see the example app.

4. Make change to the existing code, everything should be hot reloaded.

Add Library Dependency
----------------------

Add openedx/frontend-plugin-framework to the package.json of both Host and Child MFEs.

Host Micro-frontend (MFE)
-------------------------

Host MFEs define PluginSlot components in areas of the UI where they intend to accept plugin extensions.
The Host MFE, and thus the maintainers of the Host MFE, are responsible for deciding where it is acceptable to add a
plugin slot.

The slot also determines the dimensions and responsiveness of each plugin, and supports passing any additional
data to the plugin as part of its contract.

.. code-block::




id="sidebar" // this id is referenced in the JS-based config
pluginProps={{ // these props are passed along to each plugin
className: 'flex-grow-1',
title: 'example plugins',
}}
style={{
height: 700,
}}
>
propExampleA: 'edX Sidebar',
propExampleB: SomeIcon,
>







Host MFE JS-based Configuration
-------------------------------

Micro-frontends that would like to use the Plugin Framework need to use a JavaScript-based config named env.config
with either .js or .jsx as the extension. Technically, only the Host MFE requires an env.config.js file
as that is where the plugin slot's configuration is defined.

However, note that any Child MFE can theoretically contain one or more PluginSlot components themselves,
thereby making it both a Child MFE and a Host MFE. In this instance, the Child MFE would need its own env.config.js
file as well to define its plugin slots.

.. code-block::

// env.config.js

import { DIRECT_PLUGIN, IFRAME_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';

// import any additional dependencies or functions to be used for each plugin operation
import Sidebar from './widgets/social/Sidebar';
import SocialMediaLink from './widgets/social/SocialMediaLink';
import { wrapSidebar, modifySidebar } from './widgets/social/utils';
import { SomeIcon } from '@openedx/paragon/icons';

const config = {
// additional environment variables
pluginSlots: {
sidebar: { // plugin slot id
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: 'social_media_link',
type: DIRECT_PLUGIN,
priority: 10,
RenderWidget: SocialMediaLink,
},
},
{
op: PLUGIN_OPERATIONS.Wrap,
widgetId: 'default_contents',
wrapper: wrapSidebar,
},
{
op: PLUGIN_OPERATIONS.Modify,
widgetId: 'social_media_link',
fn: modifySidebar,
},
]
}
}
}

export default config;

For more information on how JS based configuration works, see:

* config.js_ file in Frontend Platform
* Frontend Build ADR on JavaScript-based environment configuration_
* Frontend Platform ADR to Promote JavaScript file configuration and deprecate environment variable configuration_

.. _config.js: https://github.com/openedx/frontend-platform/blob/master/src/config.js
.. _JavaScript-based environment configuration: https://github.com/openedx/frontend-platform/blob/master/docs/decisions/0007-javascript-file-configuration.rst
.. _Promote JavaScript file configuration and deprecate environment variable configuration: https://github.com/openedx/frontend-platform/blob/master/docs/decisions/0007-javascript-file-configuration.rst

Priority
``````

The priority property determines where the widgets should be placed based on a 1-100 scale. A widget with a priority of 10
will appear above a widget with a priority of 20.

Default Content
`````````````

The component that is wrapped by a Plugin Slot is referred to as the "default content". In order to render this content,
the keepDefault boolean in the slot should be set to true. For organizations who aren't using the Plugin Slot
(and therefore aren't defining a slot via JS config), keepDefault will default to true, thus ensuring that the developer
experience isn't affected; the only change to note is that the component is now wrapped in a Plugin Slot.

If you need to use a plugin operation (e.g. Wrap, Hide, Modify) on default content, the widgetId you would use to refer to the content is defaults_contents.

Note: The default content will have a priority of 50, allowing for any plugins to appear before or after the default content.

Plugin Operations
```````````````

There are four plugin operations that each require specific properties.

Insert a Direct Plugin
''''''''''''''''''''''

The Insert operation will add a widget in the plugin slot. The contents required for a Direct Plugin is the same as
is demonstrated in the Default Contents section above, with the content key being optional.

.. code-block::

/*
* {String} op - Name of plugin operation
* {Object} widget - The component to be inserted into the slot
*/

{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: 'social_media_link',
type: DIRECT_PLUGIN,
priority: 10,
RenderWidget: SocialMediaLink,
}
}

Insert an iFrame Plugin
'''''''''''''''''''''''

The Insert operation will add a widget in the plugin slot. The contents required for an iFrame Plugin is the same as
is demonstrated in the Default Contents section above.

.. code-block::

/*
* {String} op - Name of plugin operation
* {Object} widget - The component to be inserted into the slot
*/

{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: 'enterprise_navbar',
type: IFRAME_PLUGIN,
priority: 30,
url: 'http://{child_mfe_url}/plugin_iframe',
title: 'Login with XYZ',
}
}

Modify
''''''

The Modify operation allows us to modify the contents of a widget, including its id, type, content, RenderWidget function,
or its priority. The operation requires the id of the widget that will be modified and a function to make those changes.

.. code-block::

const modifyWidget = (widget) => {
widget.content = {
propExampleA: 'University XYZ Sidebar',
propExampleB: SomeOtherIcon,
};
return widget;
};

/*
* {String} op - Name of plugin operation
* {String} widgetId - The widget id needed for referencing when using Modify/Wrap/Hide
* {Function} fn - The function to call that can modify the widget's contents and properties
*/

{
op: PLUGIN_OPERATIONS.Modify,
widgetId: 'sidebar_plugin',
fn: modifyWidget,
}

Wrap
''''

Unlike Modify, the Wrap operation adds a React component around the widget, and a single widget can receive more than
one wrap operation. Each wrapper function takes in a component and id prop.

.. code-block::

const wrapWidget = ({ component, idx }) => (