diff --git a/README.rst b/README.rst index 293567f9..4f9e3b36 100644 --- a/README.rst +++ b/README.rst @@ -1,122 +1,128 @@ -frontend-template-application -############################# +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/main/LICENSE + :alt: License -Purpose -******* - -This repository is a template for Open edX micro-frontend applications. It is -flagged as a Template Repository, meaning it can be used as a basis for new -GitHub repositories by clicking the green "Use this template" button above. -The rest of this document describes how to work with your new micro-frontend -**after you've created a new repository from the template.** - -Getting Started -*************** - -After copying the template repository, you'll want to do a find-and-replace to -replace all instances of ``frontend-template-application`` with the name of -your new repository. Also edit index.html to replace "Application Template" -with a friendly name for this application that users will see in their browser -tab. - -Prerequisites -============= - -The `devstack`_ is currently recommended as a development environment for your -new MFE. If you start it with ``make dev.up.lms`` that should give you -everything you need as a companion to this frontend. - -Note that it is also possible to use `Tutor`_ to develop an MFE. You can refer -to the `relevant tutor-mfe documentation`_ to get started using it. - -.. _Devstack: https://github.com/openedx/devstack - -.. _Tutor: https://github.com/overhangio/tutor - -.. _relevant tutor-mfe documentation: https://github.com/overhangio/tutor-mfe#mfe-development - -Cloning and Startup -=================== - -In the following steps, replace "[PLACEHOLDER]" with the name of the repo you -created when copying this template above. - -1. Clone your new repo: - - ``git clone https://github.com/openedx/frontend-app-[PLACEHOLDER].git`` - -2. Use node v18.x. - - The current version of the micro-frontend build scripts support node 18. - Using other major versions of node *may* work, but this is unsupported. For - convenience, this repository includes an .nvmrc file to help in setting the - correct node version via `nvm `_. - -3. Install npm dependencies: - - ``cd frontend-app-[PLACEHOLDER] && npm install`` - -4. Update the application port to use for local development: - - Default port is 8080. If this does not work for you, update the line - `PORT=8080` to your port in all .env.* files - -5. Start the dev server: - - ``npm start`` - -The dev server is running at `http://localhost:8080 `_ -or whatever port you setup. - -Making Your New Project's README File -===================================== - -Move ``README-template-frontend-app.rst`` to your project's ``README.rst`` -file. Please fill out all the sections - this helps out all developers -understand your MFE, how to install it, and how to use it. - -Developing -********** - -This section concerns development of ``frontend-template-application`` itself, -not the templated copy. - -It should be noted that one of the goals of this repository is for it to -function correctly as an MFE (as in ``npm install && npm start``) even if no -modifications are made. This ensures that developers get a *practical* working -example, not just a theoretical one. +.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen -This also means, of course, that any committed code should be tested and -subject to both CI and branch protection rules. +.. |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 -Project Structure -================= +.. |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 -The source for this project is organized into nested submodules according to -the `Feature-based Application Organization ADR`_. +Purpose +======= -.. _Feature-based Application Organization ADR: https://github.com/openedx/frontend-template-application/blob/master/docs/decisions/0002-feature-based-application-organization.rst +This is the Frontend Plugin Framework library. This framework is designed to allow for any type of plugin to be used when +plugging a child component into a Host MFE. The current plugin that is made available is iFrame-based, which allows +for a component that lives in another MFE (the 'Child MFE') to be plugged into a Plugin Slot that lives in the 'Host MFE'. -Build Process Notes +Getting Started +=============== + +Micro-frontend configuration document (JS) +------------------------------------------ + +Micro-frontends that would like to use the Plugin Framework need to be configured via a JavaScript configuration +document and a `pluginSlots` config. + + .. code-block:: + + const config = { + // other existing configuration + plugins: { + sidebar: { + keepDefault: false, // bool to keep default host content + plugins: [ + { + url: 'https://plugin.app/plugin1', + type: IFRAME_PLUGIN, + } + ] + } + } + } + +Host Micro-frontend (JSX) +------------------------- + +Hosts must define PluginSlot components in areas of the UI where they intend to accept extensions. +The Host MFE, and thus the owners of the Host MFE, are responsible for deciding where it’s acceptable to mount a plugin. +They also decide the dimensions, responsiveness/scrolling policy, and whether the slot supports passing any additional +data to the plugin as part of its contract. + + .. code-block:: + + + + + + // removed if keepDefault is false + + + + + + + + +Plugin Micro-frontend (JSX) and Fallback Behavior +------------------------------------------------- + +The plugin MFE is no different than any other MFE except that it defines a Plugin component as a child of a route. +This component is responsible for communicating (via postMessage) with the host page and resizing its content to match +the dimensions available in the host’s PluginSlot. + +It’s notoriously difficult to know in the host application when an iFrame has failed to load. +Because of security sandboxing, the host isn’t allowed to know the HTTP status of the request or to inspect what was +loaded, so we have to rely on waiting for a postMessage event from within the iFrame to know it has successfully loaded. + + .. code-block:: + + + + + + + }> + + + + + +Known Issues +============ + +Development Roadmap =================== -**Production Build** - -The production build is created with ``npm run build``. - -Internationalization -==================== +The main priority in developing this library is to extract components from a Host MFE to allow for teams to develop +experimental features without impeding on any other team's work or the core functionality of the Host MFE. -Please see refer to the `frontend-platform i18n howto`_ for documentation on -internationalization. +- The first target is to use this framework in Learner Dashboard MFE to extract the Recommendations panel out of the +repo. -.. _frontend-platform i18n howto: https://github.com/openedx/frontend-platform/blob/master/docs/how_tos/i18n.rst +- Incorporate other plugin proposals from the Frontend Pluggability Summit in order to provide the most appropriate +plugin option for a given component. Getting Help -************ +============ If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community. @@ -129,7 +135,7 @@ channel`_. For anything non-trivial, the best path is to open an issue in this repository with as many details about the issue you are facing as you can provide. -https://github.com/openedx/frontend-template-application/issues +https://github.com/openedx/frontend-plugin-framework/issues For more information about these options, see the `Getting Help`_ page. @@ -139,7 +145,7 @@ For more information about these options, see the `Getting Help`_ page. .. _Getting Help: https://openedx.org/getting-help License -******* +======= The code in this repository is licensed under the AGPLv3 unless otherwise noted. @@ -147,7 +153,7 @@ noted. Please see `LICENSE `_ for details. Contributing -************ +============ Contributions are very welcome. Please read `How To Contribute`_ for details. @@ -161,36 +167,22 @@ You can start a conversation by creating a new issue on this repo summarizing your idea. The Open edX Code of Conduct -**************************** +============================ All community members are expected to follow the `Open edX Code of Conduct`_. .. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/ People -****** +====== The assigned maintainers for this component and other project details may be found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml`` file in this repo. -.. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/frontend-template-application +.. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/frontend-plugin-framework Reporting Security Issues -************************* - -Please do not report security issues in public, and email security@openedx.org instead. - -.. |license-badge| image:: https://img.shields.io/github/license/openedx/frontend-template-application.svg - :target: https://github.com/openedx/frontend-template-application/blob/main/LICENSE - :alt: License +========================= -.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen - -.. |ci-badge| image:: https://github.com/openedx/frontend-template-application/actions/workflows/ci.yml/badge.svg - :target: https://github.com/openedx/frontend-template-application/actions/workflows/ci.yml - :alt: Continuous Integration - -.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-template-application/coverage.svg?branch=main - :target: https://codecov.io/github/openedx/frontend-template-application?branch=main - :alt: Codecov +Please do not report security issues in public. Email security@openedx.org instead. diff --git a/src/plugins/Plugin.jsx b/src/plugins/Plugin.jsx index 624ed46f..084274ca 100644 --- a/src/plugins/Plugin.jsx +++ b/src/plugins/Plugin.jsx @@ -11,7 +11,7 @@ import { } from './data/hooks'; import { PLUGIN_RESIZE } from './data/constants'; -// see example-plugin-app/src/PluginOne.jsx for example of customizing errorFallback +// TODO: see example-plugin-app/src/PluginOne.jsx for example of customizing errorFallback function errorFallbackDefault() { return (