Sampo‐UI updates by GhentCDH - GhentCDH/sampo-ui GitHub Wiki

The purpose of this fork is to update Sampo-UI to be more modern, future-proof, robust and easily configurable.

Changes

Node version

Sampo-UI previously only ran on node v16.13. Additionally, it required the package-lock.json file to properly install all dependencies; simply using package.json would not correctly install all dependencies or generate a correct package-lock.json. This fork now runs Sampo-UI on the as of writing latest node lts-version namely 22.17.

Mono repository

The previously monolithic app has been split into a client app and a server app. Each manages their own node modules and gets built separately. This means they each only install the dependencies they actually need, instead of having dependencies for server and client together which could lead to more conflicts.

Changing the monolithic app into 2 apps means the configs directory also needed to become its own thing. This also means the way of accessing it has changed. First of all, multiple things that were previously not in the configs directory, but needed to be there, have been moved there. The exact project structure now looks like this:

root/
├── client/
│   ├── src/
|       ├── ...
│   ├── Dockerfile
│   ├── Package.json
│   ├── ...
├── server/
│   ├── src/
|       ├── ...
│   ├── Dockerfile
│   ├── Package.json
│   ├── ...
├── configs/
│   ├── sampo/
|       ├── assets/
|       ├── only_instance_pages/
|       ├── search_perspectives/
|       ├── sparql_queries/
|       ├── translations/
│   ├── portalConfig.json

So what has moved to configs is:

  • assets: this contains all images and icons referenced anywhere in config json files.
  • sparql_queries: this contains the js files with the sparql_queries previously part of the server.
  • translations: this contains the json locale files that previously got built with the client.

Configs are now mounted as a volume in the server container. This means the server codebase can still access them in almost the same way. However, the same can not be done for the client. To solve this, the server now has an endpoint where it serves the config files to the client. The client then saves files it already requested in a zustand store as to not need to send needless requests.

For static files in the configs such as images and icons, a new field has been added portalConfig.json namely staticsUrl, which should be an empty string by default. If this field is empty or missing, the client will look for static files in the assets folder of configs. If you want to server your statics from another url you can simply set the staticsUrl field to whatever you need. As an example, say you in your portalConfig.json:

{
    "portalID": "sampo",
    "rootUrl": "",
    "staticsUrl": "",
    ...
}

and one of your perspectives has: "frontPageImage": "main_page/works-452x262.jpg",. The empty staticsUrl means the client will assume the url for this banner image is API_URL/assets/main_page/works-452x262.jpg, so the image must be put in the /assets/main_page directory. If the staticsUrl were set to example.com that means the url of the image should be example.com/main_page/works-452x262.jpg.

Important to note is that other than this nothing changed to the actual contents of config files. The only thing that changed is that they are now completely detached from the rest of the codebase.

Docker for development and prod images

As client and server are now built separately they each have their own Dockerfile. There is a compose-prod.yaml file quickly build and run production containers. Development can now easily be run using docker as well, by running docker compose up. See the readme for more details on how to build and run.

React and MUI upgrades

React 17 has been upgraded to React 18. Upgrading to React 19 should be possible but will require more time and effort. MUI has been upgraded from v5 to v6. Trying to upgrade to v7 would require fixing more breaking changes.

Upgrading to react 18 causes a warning in development from the @nosferatu500/react-sortable-tree package to do with the rowDirection on a DOM element. This warning seems to be caused by an error in the package itself; since there does not seem to be a straightforward way to fix it and it does not impair any functionality, it has not (yet) been fixed.

As of MUI 6 the AccordionSummary component is wrapped in a button tag. This causes warnings when other button components are children of that component. However this also does not cause any actual errors. Fixing this warning would also require significant changes.

Despite these warnings in development, upgrading to react 18 and mui 6 is very important to avoid using deprecated code.

In the process of upgrading Node, React and MUI multiple other packages have also been upgraded or replaced. In particular @mui/styles had to be migrated to use @mui/material/styles and tss-react instead.

Redux store

The redux store has not yet been upgraded but should get migrated to modern Redux at some point as the version currently used will become deprecated.

Json Schema

This is an idea that has not been implemented yet, but is worth looking into. Using Json Schema for the config files would allow validating that the config is valid, as well as using autocomplete when writing configs.

A basic partial json schema for portalConfig.json has been made in this branch. This can serve as a basis for making full json schemas for all configs.

Experimental server changes

Since different sparql endpoints can have their own little quirks sampo has a bunch of different base queries depending on what kind of endpoint is used. This means however that in forks of sampo there are some extemely specific changes being made to the server code to allow for their endpoint to be used.

We would like for sampo to be more generic and sustainable by making it possible to deploy new sampo-UI apps simply by changing configs. To that end there is a branch where I tried out a way to allow passing your own base query templates as part of config. This way if someone wants to use sampo-UI on an endpoint that is not supported they can fully pass their own queries. This then has the benefit of not having multiple forks that each have their own extra features and bugfixes which makes it very difficult to merge with the main repository.

I have started working on this idea on this and got the basic idea working, but it still requires more work and testing with different endpoints.

.stories.js files

Sampo used .stories.js files for documentation of components. These files also imported config files. As mentioned earlier, the way config files are accessed has changed quite a bit, however since these stories files are only for documentation I did not change anything about them. Furthermore, I think these documentation files requiring config is a little strange and there must be a cleaner way to handle this.

I am not sure if the changes I made would break the documentations page, but I found it worth mentioning that despite changing the configs structure, the stories files were not touched.