<!-- Source: https://docs.squirro.com/en/latest/technical/ui/reference-screen.html -->
# Reference Screen

The _Reference Screen_ is a split screen view of two documents side-by-side that helps the user identify entities in one document and retrieve relevant information about that entity in a second (reference) document.

For example, if a document is tagged with multiple entities one of which is “Scrum“, the reference screen can display a relevant guideline, in this case a Scrum guideline, that helps the user to quickly look up and understand the principle of Scrum.

## Configuration

The reference screen is configured in the _Project Configuration_ under the _SETTINGS_ tab:

[![image1](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/2682356092/2682356263.png)](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/2682356092/2682356263.png)

The `topic.references` configuration takes a JSON dictionary as input.

|  |  |  |
| --- | --- | --- |
| **Key** | **Type** | **Description** |
| **Reference Types** |  |  |
| `ref_types` | **Required** `array` | Array containing all individually defined `ref_type` objects. |
| **Reference Type Object** |  |  |
| `ref_type` | **Required** `string` | Unique reference type name used internally |
| `icon` | **Required** `string` | Material icon name used in Search results page and alongside the title above reference item |
| `title` | **Required** `string` | Title to be displayed above reference item and as alt-text to icon in Search page |
| `ref_item_title` | `string` | Only used if present and no subtypes are specified. Reference item specific (overrides `title`) to be displayed above reference item. Interpreted as Jinja2 template. |
| `query` | `string` | Required if no subtypes are specified. Squirro search query used to return reference items for particular item. Interpreted as Jinja2 template. |
| `show_in_cards` | `string` | Set it to `true` if you want the reference type icon to show in Item Cards (if any references exist for that item). By default, it is set to `false`. |
| `available` | `string` | Optional dynamic field value based on item. Interpreted as Jinja2 template. Value interpretation: - `true` - reference item are accessible and Icon on search page is active - `false` - reference item are not present and Icon on search page is disabled - `null` or other value - unknown state, Icon stays active on search page - same as if `available` field was not specified. Accessible variables and functions: `item.created_at`, `item.external_id`, `item.id`, `item.keywords`, `item.language`, `item.link`, `item.title` |
| **Reference Subtypes** |  |  |
| `subtypes` | `array` | List of reference subtypes if any. |
| **Reference Subtype Object** |  |  |
| `ref_type` | **Required** `string` | Unique reference type name used internally |
| `title` | **Required** `string` | Title to be displayed above reference item and as alt-text to icon in Search page |
| `ref_item_title` | `string` | Reference item specific (overrides `title`) to be displayed above reference item. Interpreted as Jinja2 template. |
| `icon` | `string` | Material icon name used in Search results page and alongside the title above reference item. It is optional for subtypes, but recommended. |
| `query` | **Required** `string` | Squirro search query used to return reference items for particular item. Required if no subtypes are specified. Interpreted as Jinja2 template. |

## Accessible Variables and Functions

- `item` - the currently viewed item
- `ref_item` - the referenced item
- fields available in `item` and `ref_item:`

  - `item.created_at`
  - `item.external_id`
  - `item.id`
  - `item.keywords`
  - `item.language`
  - `item.link`
  - `item.title`
  - `lang.get_name(item.language) -` get a human-readable language name based on ISO 639-1 code

## Example

The following is an example configuration for reference screens:

```python
{
    "ref_types": [
        {
            "icon": "lightbulb",
            "ref_type": "reference2",
            "subtypes": [
                {
                    "query": "scrum",
                    "ref_type": "reference2.mentions",
                    "title": "Mentions"
                },
                {
                    "query": "scrum",
                    "ref_type": "reference2.mentions2",
                    "title": "More mentions"
                }
            ],
            "title": "Reference Documents"
        },
        {
            "available": "true",
            "icon": "translate",
            "query": "scrum guide czech",
            "ref_item_title": "\n{% if \"original\" in ref_item.keywords.translation %}\n Original in {{ lang.get_name(ref_item.language) }}\n {% else %}\n Translated from {{ lang.get_name(item.language) }} to {{ lang.get_name(ref_item.language) }}\n {% endif %}\n",
            "ref_type": "translation",
            "title": "Translation"
        }
    ]
}
```

The reference screen is accessed on a Card widget when clicking on the icon that was defined in the reference configuration.

[![image2](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/2682356092/2682617964.png)](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/2682356092/2682617964.png)

Example of reference screen detail view:

[![image3](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/2682356092/2682519890.png)](https://s3.amazonaws.com/download.squirro.net/docs/migrated-attachments/2682356092/2682519890.png)