One of Mnestix’ goals is to make it as easy as possible to visualize data.

Out of the box, Mnestix offers a general visualization for submodels. Additionally, Mnestix offers a selection of tailored visualizations for standardized and not standardized submodels. Those include for example visualizations for the Product Carbon Footprint submodel, the Hierarchical Structures submodel and the Time Series submodel. Additionally, Mnestix provides tailored visualizations for a selection of submodel elements, such as Address components, Document components and Entity components.

In order to realize your own use cases, Mnestix provides a means to implement your own custom visualizations for submodels and submodel elements. The following steps will explain how you can provide these visualizations.

As for any other contribution to Mnestix, you will have to start by forking the GitHub repository. You may fork either the main branch for stable release code or the dev branch for features which may still be under active development. On the repository page you will then have the option to fork the code to your own account.

Clone the Mnestix code from the GitHub repository. You may clone either the main branch for stable release code or the dev branch for features which may still be under active development. If you have forked the Mnestix repository in the previous task, clone from your private repository.

It is time to check if everything is set up correctly. In this guide we assume you have installed docker and node correctly. For a full guide on how to develop locally please consider our Development guide. All commands shown should be executed in the root directory of Mnestix.

First you need to install all required packages. This can be done with yarn install and may take some time depending on your network connection. If you have problems executing yarn, you might need to enable it using corepack enable first.

Now you can start up all background services as docker containers. We provide a few node scripts to ease the startup process. During development yarn docker:backend will suffice in most cases. For a full overview please check out the compose guide.

To start the Mnestix browser you may use yarn dev. To make sure debugging and hot-reloading works as expected you might instead use yarn debug. You can now open localhost:3000 in your internet browser and should see the Mnestix dashboard. It might take a few extra seconds at the first time as node is building your project on the go.

We suggest to create a directory for your submodel visualization inside src/user-plugins/submodels.

You can find all currently existing submodel visualizations at the following path: src/app/[locale]/viewer/_components/submodel. You might want to have a look at them for further examples.

After you created the sub-directory for your own visualization, you can create your .tsx-file and start developing the component. Custom submodel visualizations use the input type SubmodelVisualizationProps, which contains the submodel data.

You can use this stump to develop a custom submodel visualization:

import { SubmodelVisualizationProps } from 'app/[locale]/viewer/_components/submodel/SubmodelVisualizationProps';

export default function CustomSubmodel({ submodel }: SubmodelVisualizationProps) {
    return <h1>This is the custom visualization for submodel {submodel.idShort}</h1>;
}

Tip

For now the custom visualization exists but will not be shown for the SoftwareNameplate submodel. We see the generic overview of submodel data.

In order for Mnestix to automatically use your visualization, you have to provide the mapping between your visualization and the semantic id which your custom visualization should be used for. This is done in the file src/app/[locale]/viewer/_components/submodel/SubmodelsCustomVisualizationMap.ts which looks similar to this:

export const submodelsCustomVisualizationMap = {
    [SubmodelSemanticIdEnum.CoffeeConsumptionContainer]: CoffeeConsumptionDetail,
    [SubmodelSemanticIdEnum.CarbonFootprint]: CarbonFootprintDetail,
    [SubmodelSemanticIdEnum.CarbonFootprintIRDI]: CarbonFootprintDetail,
    [SubmodelSemanticIdEnum.ReferenceCounterContainer]: ReferenceCounterDetail,
    [SubmodelSemanticIdEnum.TimeSeries]: TimeSeriesDetail,
    [SubmodelSemanticIdEnum.HierarchicalStructuresV10]: HierarchicalStructuresDetail,
    [SubmodelSemanticIdEnum.HierarchicalStructuresV11]: HierarchicalStructuresDetail,
    [SubmodelSemanticIdEnum.BillOfApplications]: BillOfApplicationsDetail,
    [/*Your semantic id as a string*/]: /*React component name*/,
};

Just add an entry containing the semantic id as a key and your React component as the value. Important: Don’t forget to import your React component at the top of the file!

Tip

For the SoftwareNameplate the added mapping line will be ['https://admin-shell.io/idta/SoftwareNameplate/1/0']: SoftwareNameplateDetail,. We see the visualization now, but are still lacking the internationalization.

You probably want to display some information from the submodel. We provide you with a convenience method to search for a specific value in the submodel. Import it at the top of your file

import { findValueByIdShort } from 'lib/util/SubmodelResolverUtil';

and use it in your component

const value = findValueByIdShort(submodel.submodelElements, 'MyIDshort', 'en');

It will automatically return the requested language value for a MultiLanguageProperty.

We support internationalization for both submodel data in MultiLanguageProperty fields as well as predefined messages. Make sure to import the correct hooks on top of the file.

import { useLocale, useTranslations } from 'next-intl';

You can use the findValueByIdShort method with your preferred locale as a parameter. This may be changed to always use the currently selected language by calling the useLocale hook.

const locale = useLocale();
const value = findValueByIdShort(submodel.submodelElements, 'MyIDshort', locale);

We support message internationalization by the useTranslations hook. To keep things organized we provide a directory for all user-plugin translations at src/user-plugins/locale. Add your translations in each locale file you want to support. Be aware that these files is shared by all user-plugins so merge the files individually and not just overwrite the content.

You may now access the localized messages in your component by getting the translations for your submodel and then selecting the actual message.

const t = useTranslations('user-plugins.submodels.YourCustomSubmodel');
return <> {t('YourMessage')} </>;

For a full documentation of what is possible with next-intl visit their website.

Tip

We have provided the locale files in the repository, but you still need to merge them with the user-plugin locale files. The merged file for locale/en.json whould look something like this:

{
    "user-plugins": {
        "submodels": {
            "hello-world-component": {
                "title": "Hello World!"
            },
            "SoftwareNameplate": {
                "welcome": "Welcome to Mnestix by",
                "slogan": "Asset Administration Shell made easy!",
                "versionInfo": "This is Mnestix version {version}. It was released on {releaseDate}."
            }
        }
    }
}

Now the submodel visualization will show the translated values from the internationalization file.

Especially when you are creating a visualization for a standardized submodel, we encourage you to contribute it to the Open Source Mnestix repository, so that others can profit from it as well! This can be done by creating a pull request on the GitHub page, like seen in the following picture:

After clicking on “New pull request”, you can select “Compare across forks” and select your own repository, like seen in the picture below:

Make sure to select the dev branch as the base branch!

After you have created the pull request, it will get reviewed and merged, as soon as everything is fine and the request got approved.

In case you don’t want to share your visualization with the public, you don’t have to create the pull request. Just be aware, that your project will from now on live in its own repository and not automatically get any updates from the main repository. In order to get updates, you will have to manually merge the main repository in to your forked project with every new update. Furthermore, you have to build and publish the docker image by yourself if you wish to use your custom visualization in a productive environment.