How to create custom submodel visualizations

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 slection 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 implment your own custom visualizations for submodels and submodel elements. The following three steps will explain how you can provide these visualizations.

1. Fork the Mnestix GitHub repository

As for any other contribution to Mnestix, you will have to start by forking the GitHub repository. You can find the option to fork a repository on the main page of the repository.

This will create a new repository with a copy of the Mnestix source code. After creating the fork, you can clone the repository locally and start developing.

2. Create your React component

You can find all currently existing submodel visualizations at the following path: src/app/[locale]/viewer/_components/submodel. The path for the submodel elements visualizations is this: src/app/[locale]/viewer/_components/submodel-elements. Before creating your React component, we suggest to create a directory for your submodel (element) visualization in the respective folders to put all your components in.

Creating a visualization for a submodel

After you created the sub-directory for your own visualizations, you can create your .tsx-file inside your directory and start developing the component. Custom submodel visualizations use the input type SubmodelDetailComponentProps, which contains the submodel data as AAS-core-3 type.

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

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

export default function CustomSubmodel({submodel}: SubmodelDetailComponentProps){

    return (
            <h1>This is the custom visualization for submodel {submodel.idShort}</h1>
    )
}

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 = {
    [SubmodelSemanticId.CoffeeConsumptionContainer]: CoffeeConsumptionDetail,
    [SubmodelSemanticId.CarbonFootprint]: CarbonFootprintDetail,
    [SubmodelSemanticId.CarbonFootprintIRDI]: CarbonFootprintDetail,
    [SubmodelSemanticId.ReferenceCounterContainer]: ReferenceCounterDetail,
    [SubmodelSemanticId.TimeSeries]: TimeSeriesDetail,
    [SubmodelSemanticId.HierarchicalStructuresV10]: HierarchicalStructuresDetail,
    [SubmodelSemanticId.HierarchicalStructuresV11]: HierarchicalStructuresDetail,
    [SubmodelSemanticId.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 name as the value as shown in the code segment above. Important: Don’t forget to import your React component at the top of the file! You might also want to add your semantic id to the SubmodelSemanticId-enum used in the examples above. This especially makes sense for standardized submodels.

Creating a visualization for a submodel element

Creating a visualization for a submodel element is similar to creating a submodel visualization. After you created the sub-directory for your submodel element, you have to create the .tsx-file and your React component. Custom submodel visualizations use the input type SubmodelElementComponentProps, which among other data mainly contains the submodel element as the AAS-core-3 type.

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

import {SubmodelElementComponentProps} from 'app/[locale]/viewer/_components/submodel-elements/SubmodelElementComponentProps';

export default function CustomSubmodelElement({submodelElement}: SubmodelElementComponentProps) {

    return (
        <h1>This is the custom visualization for submodel Element {submodelElement.idShort}</h1>
    );
}

If you want Mnestix to autmoatically apply the custom submodel element visualization for general submodel element visualizations, you have to register the mapping from semantic-id to component in the file src/app/[locale]/viewer/_components/submodel-elements/SubmodelElementCustomVisualizationMap.ts, which should look similar to this:

export const submodelElementCustomVisualizationMap = {
    [SubmodelElementSemanticId.Address]: AddressComponent,
    [SubmodelElementSemanticId.ContactInformation]: ContactInformationComponent,
    [SubmodelElementSemanticId.Markings]: MarkingsComponent,
    [SubmodelElementSemanticId.MarkingsIrdi]: MarkingsComponent,
    [SubmodelElementSemanticId.Document]: DocumentComponent,
    [SubmodelElementSemanticId.DocumentIrdi]: DocumentComponent,
    <Your semantic id as a string>: <React component name>, 
};

Exactly like for the submodel visualizations, you have to add an entry with your semantic id as the key and the React component name as the value. Again, don’t forget to import your React component at the top of your file! Optionally, you can add the semantic id to the SubmodelElementSemanticId-enum here as well. This especially makes sense for standardized submodel elements and if you have to reuse the semantic id.

3. (Optional) Create a pull request

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.

Provide feedback

Saved searches