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

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.

image2

Example of reference screen detail view:

image3