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 (see example).

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. See: Accessible variables and functions.
`query`	`string`	Required if no subtypes are specified. Squirro search query used to return reference items for particular item. Interpreted as Jinja2 template. See: Accessible variables and functions.
`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. See: Accessible variables and functions.
`query`	Required `string`	Squirro search query used to return reference items for particular item. Required if no subtypes are specified. Interpreted as Jinja2 template. See: Accessible variables and functions.

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: