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 activefalse- reference item are not present and Icon on search page is disablednullor other value - unknown state, Icon stays active on search page - same as ifavailablefield 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 itemref_item- the referenced itemfields available in
itemandref_item:item.created_atitem.external_iditem.iditem.keywordsitem.languageitem.linkitem.titlelang.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:
| Code Block | ||
|---|---|---|
| ||
{
"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:
...
This page can now be found at Reference Screen on the Squirro Docs site.