Runtime custom components

[Ceetto]

Mounting custom components at runtime

I worked out a potential way to mount and use custom components at runtime. You can try it out on this branch.

With it you can use custom components even when using pre-built images of the sampo core.

How to use

You make an extra config folder for your custom components with this structure:

Right now the only custom component in there is a test component MyCustomComponent, to add more you can add more directories under components with each their own src/index.jsx and webpack.config.js.

You then need to build them simply by running

npm i
npm run build

or

./build.sh

You then need to mount the dist directory into your client container like this:

volumes:
  - ./custom_components/dist:/app/custom-components

You can refer to custom components in your config json files like this:

"component": "CustomComponent",
"componentName": "MyCustomComponent",

How it works

In webpack.base.js (part of the custom components config) the custom components assign themselves to window.____customComponents. It also marks react as external so that it will reference window.React, meaning the same react as the core application.

In ResultClassRoute.js we now check a case for custom components. CustomComponentWrapper acts as a wrapper component rendering the component using loadCustomComponent.
When React renders CustomComponentWrapper for the first time, loadCustomComponent dynamically injects a <script> tag pointing to /custom-components/MyCustomComponent.js. The browser fetches and executes that script, which writes the component onto window.__customComponents. The onload handler then reads it off window, unwraps the .default export, and resolves the promise. setComponent(() => component) stores it in React state — the function wrapper being necessary because React's state setter treats bare functions as updater callbacks rather than values.

Once Component is set in state, CustomComponentWrapper re-renders and returns <Component {...props} />. From React's perspective this is completely normal — it just sees a function component. The custom component receives all the props a core app component could use, allowing the custom component developer to do whatever they want.

Because the custom component uses window.React — the same instance the host app exposed — there is only ever one React running. This is important because React hooks track state through a per-instance fiber tree, so two React instances would break hooks entirely.

Questions

I passed the props in a way that seemed clean but also gives all the data necessary. It could turn out to be there are some things missing that might make some components impossible to make. Please let me know if I missed anything like that.

Next steps

So far this is only for resultClass components. This same system could also work for facets.

[Ceetto]

@HeikkiR @annasahola

[annasahola]

One thing that could cause problems is custom components using existing components inside them (e.g., a custom component imports the existing component ObjectListItemLink). Since the custom components here are built before being mounted, I guess you would have to copy/duplicate all the components imported in the custom component index.jsx to the custom component source folders as well?

I'm wondering if there's a clean way to utilize Webpack's resolve.modules and resolve.alias with an existing image. Using modules and aliases, any file in the client's src folder could be easily replaced with a file from another folder if it exists (demoed in this pull request), but this solution would to my understanding always require rebuilding the client. If possible, perhaps any Sampos utilizing custom components could utilize a prebuilt image but force rebuild for the client part specifically (with custom component files mounted during this new build) when containers are started? Or alternatively these "customized" Sampos could just require building a new image using the main Sampo-UI repo as the build context (so the new Sampo repo would only have to have the config and custom component files instead of everything like now).

[Ceetto]

Another option is to expose all the libraries (like MUI), components and helpers (from the core app) a custom component could need on the Window object. That way the custom components can import them as externals.
I am testing this out right now and it seems to work great.

example custom component code:

// custom_components/MyCustomComponent/index.jsx
import React from 'react'
import Box from '@mui/material/Box'
import Typography from '@mui/material/Typography'
import { ResultTable } from '@sampo-ui/components'

const MyCustomComponent = (props) => {
  return (
    <Box sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
      <Box sx={{ p: 1, backgroundColor: '#e3f2fd', borderBottom: '1px solid #90caf9' }}>
        <Typography variant='body2' color='primary'>
          Custom Component — wrapping ResultTable
        </Typography>
      </Box>
      <Box sx={{ flex: 1, overflow: 'hidden' }}>
        <ResultTable {...props} />
      </Box>
    </Box>
  )
}

export default MyCustomComponent

This component simply imports the ResultTable component and adds a little extra box on top of it to confirm it's the custom component. This results in this:

As for the pull request demoing using aliases to make any file in the src folder replaceable; if we only did that wouldn't you still need to edit your ResultClassRoute to add cases for your custom components (if you are adding new components and not just replacing existing ones). Additionally is there a need to allow making any file replaceable like this? With the customisable layout config discussed in #68 will there still sometimes be a need to replace entire files? If so I guess adding that option is not much extra effort and it does not impede my proposed method of adding custom components.

[annasahola]

Looks great! Regarding the pull request, yes, using that approach for loading new custom components would require providing a changed ResultClassRoute as well (as the demo is just about being replace any file in src).

For most cases I imagine just being able to define new components (like your solution already allows), being able to add new chart data creation functions / modify library_configs in some way and having the configuration for layout would be enough. From a developer perspective it would just be a nice bonus to be able to override things if needed.

For example, during the development of the LetterSampo Finland portal, we wanted to add these buttons with specific styling to the front page leading to example pages/searches (see landing page section "Select example searches, visualizations, and linked information"). On another project we might want to add something wholly different.

So in these kind of cases it would be nice to have the possibility to just override some existing file (e.g. the landing page layout file in this case) to avoid having to always add new configuration options for things that might be used in just one portal or complicated to write a generic configuration for. But, of course, if this ends up being too cumbersome or problematic to implement properly, these kind of portals could always just fork the whole Sampo-UI code the "old way" instead of using an existing image or the base repository as build context.

[Ceetto]

@HeikkiR @annasahola
I believe my implementation of it should be done now. I also addressed all the other issues you mentioned in our previous meeting.
See this wiki page for exact documentation on the usage and implementation.

[HeikkiR]

Excellent! We have a new war history project that was recently funded and @annasahola just started creating a new Sampo-UI application based on your work. This should allow testing and development of Sampo-UI.