---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: [ ]
---

```{tags} how-to
```

# Customizing the display of referenced entities

:::{note}
This page has been migrated from the old documentation, and has not yet been fully revised.
There might be inconsistencies or errors when using with current LinkAhead versions.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/94
% TODO: Potentially mergeable with display of properties

LinkAhead WebUI supports the customized display of referenced entities using
the [ext_references](/reference/webui/api/module-resolve_references.rst) module. In order to use
this module, the `BUILD_MODULE_EXT_RESOLVE_REFERENCES` build variable has to be set to `ENABLED`
(see the Build Configuration section in the [WebUI setup guide](/how_to/admin_guides/webui/install.md#build-configuration)).

You may then define your own JavaScript module to define how references to specific Records should
be resolved. The module has to be located at a directory which is known to LinkAhead WebUI; we
recommend `linkahead-webui/src/ext/js`. Set the value of the `BUILD_EXT_REFERENCES_CUSTOM_RESOLVER`
build variable to the name of this module. The module has to have a `resolve` function which takes
an entity id as its only parameter and returns a `reference_info` object with the resolved custom
reference as a `text` property. So the basic structure of the module should look like

```javascript
var my_reference_resolver = new function () {
    // Has to be called ``resolve`` and has to take exactly one
    // string parameter: the id of the referenced entity.
    this.resolve = async function (id) {
        /*
         * find the string that the reference should be resolved to,
         * e.g., from the value of the entity's properties.
         */
        return {"text": new_reference_text}
    }
}
```

An example is located in
`linkahead-webui/src/core/js/reference_resolver/linkahead_default_person.js`. It resolves any
reference to a `Person` Record to the value of its `firstname` and `lastname` properties separated
by a space and is active by default.