Skip to content

Gluu Admin UI: Frontend Plugin development document

Jump to bottom
duttarnab edited this page Feb 2, 2022 · 2 revisions

Points considered when writing a frontend plugin

  1. The Admin UI application will work with core features like Auth, Setting, etc.
  2. When a plugin is plugged into the Admin UI application, then all the plugin menus will be displayed on the left menu panel of GUI. On clicking a menu will open the associated page.
  3. A plugin could be added or removed without making any changes in Admin UI code.
  4. The installed UI plugins will interact with backend (rest) apis for CRUD and then render data on UI.
  5. To avoid duplication of code in each added plugin, the added Plugins can make use of the main application generic components.

Pre-requisites

The plugin developer should have an understanding of the following:

  • JavaScript: The plugin developer should know the JavaScript language
  • React This project base on react and hence you should have a good working experience with React
  • Redux: Redux is used for state management combine with Saga
  • API: The communication between the oAuth server and the UI is manage via REST call and protected with oauth2.0

Structure of a plugin

The below image shows the structure of an Admin UI frontend plugin.

  1. components: This folder is where you should put all your components and pages.

  2. redux: This folder is where all the state management and API call code should be.

  • redux/apis: code for all API calls to rest backends
  • redux/sagas: sagas code
  • redux/reducers: redux reducers code
  • redux/actions: redux actions and actions types code
  1. plugin-metadata.js: this file should be placed at the root of the plugin folder. The plugin-metadata.js exports all plugin menus, routes, plugin reducers and sagas in a single object.

plugin-metadata.js

import MyPluginFirstPage from './components/MyPluginFirstPage'
import MyPluginSecondPage from './components/MyPluginSecondPage'
import MyPluginSubPage from './components/MyPluginSubPage'
import myPluginReducer from './redux/reducers/MyPluginReducer'
import myPluginSaga from './redux/sagas/MyPluginSaga'

const PLUGIN_BASE_APTH = '/myplugin'

const pluginMetadata = {
  menus: [
    {
      title: 'My Test Plugin',
      icon: 'fa-search',
      children: [
        {
          title: 'Page One',
          path: PLUGIN_BASE_APTH + '/one',
          permission: '/config/acrs.readonly',
        },
        {
          title: 'Section One',
          children: [
            {
              title: 'Sub Page One',
              path: PLUGIN_BASE_APTH + '/two',
              permission: '/config/acrs.readonly',
            },
            {
              title: 'Sub Page Two',
              path: PLUGIN_BASE_APTH + '/three',
              permission: '/config/acrs.readonly',
            },
          ],
        },
      ],
    },
  ],
  routes: [
    {
      component: MyPluginFirstPage,
      path: PLUGIN_BASE_APTH + '/one',
      permission: '/config/acrs.readonly',
    },
    {
      component: MyPluginSecondPage,
      path: PLUGIN_BASE_APTH + '/two',
      permission: '/config/acrs.readonly',
    },
    {
      component: MyPluginSubPage,
      path: PLUGIN_BASE_APTH + '/three',
      permission: '/config/acrs.readonly',
    },
  ],
  reducers: [{ name: 'myPluginReducer', reducer: myPluginReducer }],
  sagas: [myPluginSaga()],
}

export default pluginMetadata

Menu system hierarchy

A menu object in plugin-metadata.js consists of the following fields.

  • title: the title of the menu. (mandatory)
  • icon: the icon of the menu selected from awesome fonts.
  • children: the array of sub-menu objects of that menu. In above example menu with title Section One has children. (only needed if the menus have sub-menus)
  • path: the path the menu. This is used for mapping it to the routes. (only needed if the menu has no sub-menus)
  • permission: user permission (scope) required to see the menu on UI. (only needed if the menu has no sub-menus)

Routes

Routes are the objects containing data to map the menus with the React components. A route object consists of the following fields.

  • path: the path used for mapping menu with route.
  • permission: user permission (scope) required to see the menu on UI.
  • component: the react component map to the route.

Adding a plugin to Admin UI

Please refer to the structure Admin UI project to understand the process of adding a plugin.

  1. In the root directory of Admin UI application we have plugins-config.js file. This configuration file will export a list of the plugins which will be plugged into the Admin UI application. So the first step is to add the entry of the plugin object with title, key and metadataFile in the list. Here, the value of metadataFile is the relative path of the plugin-metadata.js of the plugin.
const plugins = [
  {
    title: 'MyPlugin',
    key: 'my-plugin',
    metadataFile: './myplugin/plugin-metadata',
  },
]
export default plugins
  1. There will be a plugins folder in the root directory of the Admin-UI application. Add the plugin with the above-described structure in this folder.

Aggregator files

There are 3 files placed in the plugins folder of the Admin-UI project to aggregate metadata of all plugins added. Note that these files should not be modified when adding/removing a new plugin.

  • PluginMenuResolver.js: this file aggregates all menus and routes objects from plugin-metadata.js of all added plugins.
  • PluginReducersResolver.js: this file aggregates all reducers from plugin-metadata.js of all added plugins.
  • PluginSagasResolver.js: this file aggregates all sagas from plugin-metadata.js of all added plugins.

Removing an added plugin from Admin UI

  1. Remove the plugin entry from plugins-config.js.
  2. Remove the plugin folder from gluu-admin-ui/plugins.
  3. Build Admin UI project and deploy the build on the server.

Sample plugin

To help bootstrap the plugin development, we have put together a sample plugin.

  1. Clone the base Admin UI project here.
  2. Switch to admin-ui-plugin_template branch of this project.
  3. Navigate under the plugins folder, there you will see a folder named myplugin, that folder represents and contains the code for a basic plugin that displays basic information and showcases some usages.
  4. Take the time to explore that folder and observes the relationship between his elements.

Structure of myplugin plugin

Clone this wiki locally