-
Notifications
You must be signed in to change notification settings - Fork 11
Configuration
This section goes over configuring your Sampo-UI based application into your own Sampo.
There are 3 important directories in your Sampo repository that you will mostly be editing:
src/client/translations/
src/configs/
src/server/sparql/
There's also the src/client/components/perspectives/
directory where a folder needs to be duplicated and then renamed to match your portal's ID, but can then be left alone.
Let's start with configuring the portal itself. The main configuration file for the portal is located in the src/configs/
directory with the name portalConfig.json
. The most relevant configuration options for getting your Sampo portal set up are:
-
portalID
: The ID for your portal. This ID is going to be used as a folder name for folders containing portal specific files. -
searchPerspectives
: This array contains the perspective IDs for the perspectives that should be shown in the portal. You can remove the current perspectives from the list and leave an empty array there for now. A related property,onlyInstancePages
, is used for defining perspectives that are only used for their instance pages and have no perspective paginated results view. -
defaultLocale
: The language code for your default locale that is used in the portal. This language code should match some locale ID defined in the next configuration option. -
availableLocales
: This array contains objects representing the available locales in the portal. Each locale object should have anid
,label
andfilename
. The filename should match a .json file located in thesrc/client/translations/
directory. -
endpoint
inyasguiConfig
: This URL is the endpoint used in the Yasgui Editor if the user decides they want to open their query in that.
Now you also need to duplicate rename some folders to match your defined portalID
. Duplicate and then rename the sampo
folders in the following directories to your portalID
:
src/client/translations/
src/configs/
src/server/sparql/
src/client/components/perspectives/
So for example, if your portalID
was exampleSampo
, all these directories should contain a folder named exampleSampo
that contains the files the original sampo
folders had. If you have other locales you want to use in your portal other than the English and Finnish locales found in sampo
, you can use either the localeEN.json
or localeFI.json
as a base and add your translations into a new locale file. Remember to add this new locale to the availableLocales
in the portalConfig.json
file.
After this you are now ready to start setting up the first perspective of this new portal.
In this section the important directories are:
src/configs/[portalID]/
src/server/sparql/[portalID]/
Everything in the src/configs/[portalID]/only_instance_pages/
can be deleted for now. src/configs/[portalID]/search_perspectives/
contains the configuration files for different perspectives. New perspectives are created by creating a new file named after the new perspective. You can use the sampo
perspective files like perspective1.json
as a base.
The most important configuration options for new perspectives are:
-
id
: At the start of the perspective file you should define the ID of your perspective forid
field. Thisid
is going to be used to refer to this perspective in other files. -
endpoint
:endpoint
should be an object that should have aurl
,useAuth
andprefixesFile
properties.url
is used to define the endpoint that is queried anduseAuth
specifies whether the endpoint requires authentication. If authentication is usedSPARQL_ENDPOINT_BASIC_AUTH
environment variable (=authentication key used) needs to be defined.prefixesFile
should contain the file name of the file containing all the prefixes used in the SPARQL query. The file mentioned should be located in the directory covered in the next section,src/server/sparql/[portalID]/sparql_queries/
. -
baseURI
,baseURIs
: This is an optional property that can be used to define (a) base URI(s) for the instances searched and shown in the perspective. In this case only the local ID of the instance is used as a part of the instance page URL.If all the instances share the same base URI before their local ID, you can define
baseURI
to be that URI.In case of multiple different base URIs, you can define
baseURIs
object, that should have different base URI types as properties. The property name should have the start of the local ID as their key andbaseURI
andURITemplate
as the object's properties.baseURI
should contain the base URI itself andURITemplate
should be the template of how the complete URI is formed from<BASE\_URI>
and<LOCAL\_ID>
, e.g."URITemplate": "<BASE\_URI>/<LOCAL\_ID>"
.If you want to use the whole URI (including the base) of the instance as the local ID, this property should be left out and
localIDAsURI
should be set totrue
inresultClasses.[perspective].instanceConfig
. -
sparqlQueriesFile
: This should be the filename of the file specifying the SPARQL queries used for this perspective. The file should be located in the directorysrc/server/sparql/[portalID]/sparql_queries/
. -
facetClass
: This property should define the class that is being facet searched in the perspective. -
resultClasses
: This object contains all the result classes of the perspective. One of its properties should be named after the perspective itself so you should haveresultClasses.[id]
property, whereid
is the ID of the perspective defined earlier.
Let's take a closer look at resultClasses
itself and its properties. In addition to its resultClasses.[id]
property, resultClasses
can have however many additional properties that define the other tabs shown in the perspective. resultClasses.[id]
object should have two properties,
-
paginatedResultsConfig
This object defines the default paginated results view. Some of the important properties it has:-
tabID
: Integer specifying the tab's ID. In case of paginated results, this is generally \texttt{0} (and thus the first tab in the perspective results). -
tabPath
: String specifying the tab's path that is used for defining the text shown on the tab and the relative URL for the tab. -
tabIcon
: String specifying the icon used for this tab out of the options in Sampo-UI. The icons are imported from Material UI icons and can be found in a file namedMuiIcon.js
in the main layout directorysrc/client/components/main_layout
. -
component
: String specifying the component name that should be shown in the tab. -
propertiesQueryBlock
: String specifying the name of the query used for the results to be shown on the tab. This query should be defined in the perspective's respective SPARQL query file in the directorysrc/server/sparql/[portalID]/
.
If your perspective will also be showing images in the paginated result view, properties
-
paginatedResultsAlwaysExpandedRows
: This indicates whether all row should be expanded by default if they have enough content to be collapsible.
and
-
paginatedResultsRowContentMaxHeight
: Integer specifying the maximum height of a row's content. Content that does not fit into this height will have a scrollbar.
could be helpful.
-
-
instanceConfig
This object contains the configuration for the instance pages. It has the following important properties:-
propertiesQueryBlock
: String specifying the name of the query used for the results to be shown on the tab. This query should be defined in the perspective's respective SPARQL query file in the directorysrc/server/sparql/[portalID]/
. -
localIDAsURI
: Boolean specifying whether the local ID should be used as the instance's URI without trying to form the URI from a base URI and the local ID. -
instancePageResultClasses
: This is an object with different instance page tab objects as properties. These instance page tab objects should have at least the following properties:-
tabID
: Integer specifying the tab's ID. In case of paginated results, this is generally0
(and thus the first tab in the perspective results). -
tabPath
: String specifying the tab's path that is used for defining the text shown on the tab and the relative URL for the tab. -
tabIcon
: String specifying the icon used for this tab out of the options in Sampo-UI. -
component
: String specifying the component name that should be shown in the tab.
-
-
Depending on the component to be shown on the tab, these objects might require other properties to be defined.
The used properties and facets themselves are defined in properties
and facets
properties. properties
expects an array of objects, each representing a property to be shown. facets
on the other hand expects and object that has all the different facets as properties inside it.
Let's first look at the most important properties the properties
array objects can have:
-
id
: This is the ID that's used to refer to this property. This is the ID used in the SPARQL queries as well, so if you for example want to define an image property with the IDimage
, you would define the image's properties (description, URL...) in the SPARQL query isimage__[property name]
e.g.image__description
. -
valueType
: This is a string defining what the property's type should be. This could beimage
,object
orstring
. -
makeLink
: Boolean indicating whether this property should be shown as a link. In the case that a link should be made, you should define the propertydataProviderUrl
for this property in the SPARQL query ([property name]__dataProviderUrl
). -
externalLink
: This is a boolean specifying whether the aforementioned link is an external link as opposed to an internal link. -
sortValues
: This is a boolean specifying whether the values of this property should be sorted. -
numberedList
: This is a boolean specifying whether a numbered list should be used to show the values of this property. -
disableSort
: This is a boolean specifying whether sorting for this property's values should be disabled completely.
In addition to these properties you can define, there are some other useful properties you can use to specify how and what things should be shown:
-
minWidth
: This is an integer that can be used to specify the minimum width a column should take in the paginated results table view. -
onlyOnInstancePage
: This is a boolean specifying whether this property should only be shown on instance pages and be hidden in the paginated results table view. -
expandedOnInstancePage
: This is a boolean specifying whether this property should be expanded by default on the instance page. -
hideHeader
: This is a boolean specifying whether this property's header label should be hidden in the paginated results table view. -
previewImageHeight
: This is an integer specifying the height used for preview images. This does not affect the image size when an image is opened by clicking the preview.
Now, for the properties you want to use as facets for the facet search, you should define them as properties of the facets
object. Each facet object itself has their own properties. Some of the most important properties you can define are:
-
containerClass
: This is a string that is used for specifying the height of the facet component when opened. The string should be the number written out e.g."one"
,"four"
and"ten"
. -
facetType
: This is a string specifying what type of facet should used. For a text searchtext
type facet is used and for a list facetlist
facet type is used. Other possible facet types includetimespan
,integer
andhierarchical
. -
filterType
: This is a string specifying the type of filter used in the facet. Possible filter types areuriFilter
,textFilter
,timespanFilter
,dateNoTimespanFilter
andintegerFilter
. -
predicate
: This is a string specifying the predicate used for getting the facet values from the class being faceted (=facetClass
defined at the start of the perspective file). -
sortButton
: This is a boolean specifying whether a sort button should be shown on the facet to change how the values are sorted. -
sortBy
: This is a string specifying how the facet values are sorted e.g.instanceCount
orprefLabel
. -
sortByPredicate
: This is a string specifying the predicates used for getting the facet values that are used as the basis of sorting from the class being faceted e.g.[predicate]/skos:prefLabel
assortByPredicate
would mean using theskos:prefLabel
s of the values as the basis for sorting. -
sortDirection
: This is a string specifying the sorting direction ofdesc
(descending) orasc
(ascending).
In addition to the above properties, there are also some other properties that can be used to customize the facets further:
-
facetLabelFilter
: This property can be used for filtering the facet labels if needed. The label can be referred to withprefLabel_
. -
facetLabelPredicate
: This property can be used to specify a specific predicate that should be used for getting the facet labels. If this property is not specified, the defaultskos:prefLabel
is used for getting the labels. -
searchField
: This is a boolean value specifying whether a search field should be shown to the user in the facet that can be used to search through the facet values. -
pieChartButton
: This is a boolean value specifying whether there should be a pie chart button shown in the facet that can be clicked to open a pie chart depicting the facet values and their instance counts.
The directory src/server/sparql/[portalID]/
should contain all the SPARQL query files used. The folder contains the file SparqlQueriesPrefixes.js
, which should be used to define all the prefixes to be used in the queries. Other files should contain all the queries needed for the perspectives divided to different files by perspective.
Objects returned by the queries can have the following possible properties:
-
id
: Generally the URI of the instance. -
prefLabel
: The preferred label for the instance to be shown on the client. -
dataProviderUrl
: The URL to be used for links to the instance. -
url
: The URL for images that contain the image itself. -
description
: Description for images to be shown under the image in the client when the image is clicked.
These should be defined in relation to the object type by using double underscores. For example, if you query for a image that you have listed as image
in the perspective properties, you would bind that image's URL as image__url
and its description as image__description
.
There are two different map components defined in Sampo-UI:
LeafletMap
Deck
LeafletMap
component renders a map with clickable leaflets. An example of a LeafletMap
component can be seen here.
Example LeafletMap
configuration:
"lastKnownLocations": {
"tabID": 1,
"component": "LeafletMap",
"tabPath": "production_places",
"tabIcon": "AddLocation",
"sparqlQuery": "productionPlacesQuery",
"facetClass": "perspective2",
"filterTarget": "manuscripts",
"resultMapper": "mapPlaces",
"facetID": "productionPlace",
"showExternalLayers": true,
"instanceConfig": {
"propertiesQueryBlock": "placePropertiesInfoWindow",
"relatedInstances": "manuscriptsProducedAt",
"filterTarget": "related__id",
"createPopUpContent": "createPopUpContentMMM"
}
}
A LeafletMap
component can also be included on an instance page by defining pageType
to be instancePage
. An example of a LeaftletMap
component on an instance page can be seen here.
Example instance page LeafletMap
configuration:
"findInstancePageNearbyFinds": {
"tabID": 2,
"component": "LeafletMap",
"showInstanceCountInClusters": false,
"showExternalLayers": true,
"customMapControl": true,
"pageType": "instancePage",
"tabPath": "nearby_finds",
"tabIcon": "AddLocation",
"sparqlQuery": "nearbyFindsQuery",
"resultMapper": "makeObjectList",
"instanceConfig": {
"createPopUpContent": "createPopUpContentFindSampo"
}
}
Deck
component renders a map a configurable layer over it. The Deck
component can be configured to have a heatmap layer or arc layer where 3D arcs are drown over the map.
An example of a heatmap Deck
component can be seen here. The heatmap rendered by the Deck
component can be configured by using the optional properties heatmapRadiusPixels
, heatmapThreshold
and heatmapIntensity
. If these variables are not given any values, the library defaults are used.
Example heatmap Deck
configuration:
"placesMsProducedHeatmap": {
"tabID": 2,
"component": "Deck",
"tabPath": "production_places_heatmap",
"tabIcon": "AddLocation",
"sparqlQuery": "productionPlacesQuery",
"facetClass": "perspective2",
"filterTarget": "manuscripts",
"resultMapper": "mapPlaces",
"layerType": "heatmapLayer",
"heatmapRadiusPixels": 40,
"heatmapThreshold": 0.025,
"heatmapIntensity": 1
}
An example of a arc layer Deck
component can be seen here.
Example arc layer Deck
configuration:
"placesMsMigrations": {
"tabID": 6,
"component": "Deck",
"tabPath": "migrations",
"tabIcon": "Redo",
"sparqlQuery": "migrationsQuery",
"facetClass": "perspective2",
"filterTarget": "manuscript",
"resultMapper": "makeObjectList",
"layerType": "arcLayer",
"arcWidthVariable": "instanceCountScaled",
"instanceVariable": "manuscript",
"showTooltips": true,
"postprocess": {
"func": "linearScale",
"config": {
"variable": "instanceCount",
"minAllowed": 3,
"maxAllowed": 30
}
}
}
The translations for arc layer Deck
components should have the following format:
"deckGlMap": {
"arcColouring": "Arc colouring:",
"showMoreInformation": "Click to show more information.",
"peopleMigrations": {
"legendTitle": "Arc colouring",
"legendFrom": "Person birth place",
"legendTo": "Person death place",
"from": "Birth place:",
"to": "Death place:",
"count": "Person count",
"listHeadingSingleInstance": "Person:",
"listHeadingMultipleInstances": "People:"
}
}
Perspective object needs to have the property maps
that defines the coordinates that should be at the center of the map by default and what the default zoom level should be. The maps
object should have its own property for every map component with the map component result class name as its key. The format should be the following:
"maps": {
"[COMPONENT RESULT CLASS NAME HERE]": {
"center": [
22.43,
10.37
],
"zoom": 2
}
}
Pie charts can be added using the ApexCharts
component. A single pie chart component can have multiple properties that can be rendered. The user can switch between these perspectives by using a dropdown menu when it is enabled with dropdownForResultClasses
. An example of a pie chart component can be seen here.
Since bar charts and pie charts use the same ApexCharts
, both a pie chart and bar chart can be configured for the same property query by listing both chart types in the chartTypes
array.
The minimum threshold for showing a property value and its instance count can be configured using sliceVisibilityThreshold
that expects a number specifying the minimum ratio of instance count to the total count for all values. If the instance count's ratio is lower than this, it is grouped with other such values under the label 'Other' in the pie/bar chart.
Example pie chart ApexCharts
configuration that also includes the possibility for the user to see the data in bar chart format as well:
"novelsByProperty": {
"tabID": 3,
"component": "ApexCharts",
"doNotRenderOnMount": true,
"tabPath": "pie_chart",
"tabIcon": "PieChart",
"facetClass": "novels",
"dropdownForResultClasses": true,
"defaultResultClass": "novelsByOriginalLanguage",
"resultClasses": {
"novelsByGenre": {
"sparqlQuery": "novelsByGenreQuery",
"filterTarget": "novel",
"resultMapper": "mapPieChart",
"sliceVisibilityThreshold": 0.01,
"dropdownForChartTypes": true,
"chartTypes": [
{
"id": "pie",
"createChartData": "createApexPieChartData"
},
{
"id": "bar",
"createChartData": "createApexBarChartData"
}
]
},
"novelsByOriginalLanguage": {
"sparqlQuery": "novelsByOriginalLanguageQuery",
"filterTarget": "novel",
"resultMapper": "mapPieChart",
"sliceVisibilityThreshold": 0.001,
"dropdownForChartTypes": true,
"chartTypes": [
{
"id": "pie",
"createChartData": "createApexPieChartData"
},
{
"id": "bar",
"createChartData": "createApexBarChartData"
}
]
}
}
}
Example pie chart ApexCharts
configuration without the option for user to show the data in bar chart format as well:
"instacePageWorks": {
"tabID": 2,
"component": "ApexCharts",
"doNotRenderOnMount": true,
"tabPath": "activity_chart",
"tabIcon": "ShowChart",
"facetClass": "people",
"sparqlQuery": "worksByDecadeQuery",
"resultMapper": "mapPieChart",
"filterTarget": "work",
"createChartData": "createApexPieChartData",
"pageType": "instancePage",
"sliceVisibilityThreshold": 0.01,
"dropdownForResultClasses": false
}
Translations for pie and bar charts should be provided in the apexCharts
property in the translation file:
"apexCharts": {
"grouping": "Group by:",
"by": "by",
"property": "X-axis:",
"numberOfNovels": "Number of novels",
"chartType": "Chart type:",
"pie": "pie chart",
"bar": "bar chart",
"resultClasses": {
"novelsByGenre": "genre",
"novelsByOriginalLanguage": "original language"
}
}
Bar charts can be added using the ApexCharts
component just like pie charts. For more information on configuration options, see the previous pie chart section.
Example bar chart ApexCharts
configuration that includes the possibility to show the same data also in pie chart format:
"novelsByProperty": {
"tabID": 3,
"component": "ApexCharts",
"doNotRenderOnMount": true,
"tabPath": "pie_chart",
"tabIcon": "PieChart",
"facetClass": "novels",
"dropdownForResultClasses": true,
"defaultResultClass": "novelsByOriginalLanguage",
"resultClasses": {
"novelsByGenre": {
"sparqlQuery": "novelsByGenreQuery",
"filterTarget": "novel",
"resultMapper": "mapPieChart",
"sliceVisibilityThreshold": 0.01,
"dropdownForChartTypes": true,
"chartTypes": [
{
"id": "pie",
"createChartData": "createApexPieChartData"
},
{
"id": "bar",
"createChartData": "createApexBarChartData"
}
]
},
"novelsByOriginalLanguage": {
"sparqlQuery": "novelsByOriginalLanguageQuery",
"filterTarget": "novel",
"resultMapper": "mapPieChart",
"sliceVisibilityThreshold": 0.001,
"dropdownForChartTypes": true,
"chartTypes": [
{
"id": "pie",
"createChartData": "createApexPieChartData"
},
{
"id": "bar",
"createChartData": "createApexBarChartData"
}
]
}
}
}
Example bar chart ApexCharts
configuration without the option for user to show the data in pie chart format as well:
"instacePageWorks": {
"tabID": 2,
"component": "ApexCharts",
"doNotRenderOnMount": true,
"tabPath": "activity_chart",
"tabIcon": "ShowChart",
"facetClass": "people",
"sparqlQuery": "worksByDecadeQuery",
"resultMapper": "mapPieChart",
"filterTarget": "work",
"createChartData": "createApexBarChartData",
"pageType": "instancePage",
"sliceVisibilityThreshold": 0.01,
"dropdownForResultClasses": false
}
An example of a ApexCharts
component with two stacked line charts can be seen here.
Example ApexCharts
configuration with two stacked line charts:
"productionTimespanLineChart": {
"tabID": 3,
"component": "ApexChartsDouble",
"tabPath": "production_dates",
"tabIcon": "ShowChart",
"upperResultClass": "productionTimespanLineChartUpper",
"lowerResultClass": "productionTimespanLineChartLower",
"resultClasses": {
"productionTimespanLineChartUpper": {
"height": "70%",
"sparqlQuery": "productionsByDecadeQuery",
"facetClass": "perspective2",
"filterTarget": "instance",
"resultMapper": "mapLineChart",
"resultMapperConfig": {
"fillEmptyValues": false
},
"createChartData": "createSingleLineChartData",
"title": "Manuscript production by decade",
"xaxisTitle": "Decade",
"xaxisType": "category",
"xaxisTickAmount": 30,
"yaxisTitle": "Manuscript count",
"seriesTitle": "Manuscript count",
"stroke": {
"width": 2
}
},
"productionTimespanLineChartLower": {
"height": "30%",
"sparqlQuery": "productionsByDecadeQueryLower",
"facetClass": "perspective2",
"filterTarget": "instance",
"resultMapper": "mapLineChart",
"resultMapperConfig": {
"fillEmptyValues": false
},
"createChartData": "createSingleLineChartData",
"title": "Manuscript production by decade",
"xaxisTitle": "Decade",
"xaxisType": "category",
"xaxisTickAmount": 30,
"yaxisTitle": "Manuscript count",
"seriesTitle": "Manuscript count",
"stroke": {
"width": 2
}
}
}
}
An example of a multiple line chart ApexCharts
component can be seen here.
Example multiple line chart ApexCharts
configuration:
"eventLineChart": {
"tabID": 4,
"component": "ApexCharts",
"tabPath": "event_dates",
"tabIcon": "ShowChart",
"sparqlQuery": "eventsByDecadeQuery",
"facetClass": "perspective2",
"filterTarget": "manuscript",
"resultMapper": "mapMultipleLineChart",
"resultMapperConfig": {
"fillEmptyValues": false
},
"createChartData": "createMultipleLineChartData",
"title": "Manuscript events by decade",
"xaxisTitle": "Decade",
"xaxisType": "category",
"xaxisTickAmount": 30,
"yaxisTitle": "Count",
"seriesTitle": "Count",
"stroke": {
"curve": "straight",
"width": 2
},
"fill": {
"type": "gradient",
"gradient": {
"shadeIntensity": 1,
"inverseColors": false,
"opacityFrom": 0.6,
"opacityTo": 0.05,
"stops": [
20,
60,
100,
100
]
}
}
}
Example BarChartRace
configuration:
"publicationsByDecadeAndGenre": {
"tabID": 1,
"tabIcon": "CalendarViewDay",
"tabPath": "publications_by_decade_and_genre",
"component": "BarChartRace",
"stepBegin": 1700,
"stepEnd": 2020,
"stepIncrement": 10,
"stepDuration": 3000,
"sparqlQuery": "publicationsByDecadeAndGenreQuery",
"facetClass": "publications",
"filterTarget": "publication",
"resultMapper": "makeObjectList",
"postprocess": {
"func": "toBarChartRaceFormat",
"config": {
"step": 10
}
}
}
An example of a Network
component can be seen here.
Example Network
configuration:
"manuscriptInstancePageNetwork": {
"tabID": 1,
"component": "Network",
"tabPath": "network",
"tabIcon": "BubbleChart",
"pageType": "instancePage",
"sparqlQuery": "manuscriptInstancePageNetworkLinksQuery",
"sparqlQueryNodes": "manuscriptNetworkNodesQuery",
"useNetworkAPI": true,
"limit": 200,
"optimize": 1.2,
"preprocess": "preprocessPageRank",
"style": [
{
"selector": "node",
"style": {
"shape": "ellipse",
"label": "data(prefLabel)"
}
},
{
"selector": "edge",
"style": {
"curve-style": "bezier",
"target-arrow-shape": "triangle",
"target-arrow-color": "#999",
"color": "#555",
"font-size": "6",
"text-valign": "top",
"text-halign": "center",
"edge-text-rotation": "autorotate",
"text-background-opacity": 1,
"text-background-color": "white",
"text-background-shape": "roundrectangle"
}
}
],
"layout": {
"name": "cose",
"idealEdgeLength": 100,
"nodeOverlap": 20,
"refresh": 20,
"fit": true,
"padding": 30,
"randomize": false,
"componentSpacing": 100,
"nodeRepulsion": 400000,
"edgeElasticity": 100,
"nestingFactor": 5,
"gravity": 80,
"numIter": 1347,
"initialTemp": 200,
"coolingFactor": 0.95,
"minTemp": 1
}
}