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:

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:

{
    "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.

Example of reference screen detail view: