-
Notifications
You must be signed in to change notification settings - Fork 13
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,labelandfilename. The filename should match a .json file located in thesrc/client/translations/directory. -
endpointinyasguiConfig: 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 foridfield. Thisidis going to be used to refer to this perspective in other files. -
endpoint:endpointshould be an object that should have aurl,useAuthandprefixesFileproperties.urlis used to define the endpoint that is queried anduseAuthspecifies whether the endpoint requires authentication. If authentication is usedSPARQL_ENDPOINT_BASIC_AUTHenvironment variable (=authentication key used) needs to be defined.prefixesFileshould 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
baseURIto be that URI.In case of multiple different base URIs, you can define
baseURIsobject, that should have different base URI types as properties. The property name should have the start of the local ID as their key andbaseURIandURITemplateas the object's properties.baseURIshould contain the base URI itself andURITemplateshould 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
localIDAsURIshould be set totrueinresultClasses.[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, whereidis 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.jsin 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,objectorstring. -
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 propertydataProviderUrlfor 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 searchtexttype facet is used and for a list facetlistfacet type is used. Other possible facet types includetimespan,integerandhierarchical. -
filterType: This is a string specifying the type of filter used in the facet. Possible filter types areuriFilter,textFilter,timespanFilter,dateNoTimespanFilterandintegerFilter. -
predicate: This is a string specifying the predicate used for getting the facet values from the class being faceted (=facetClassdefined 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.instanceCountorprefLabel. -
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:prefLabelassortByPredicatewould mean using theskos:prefLabels 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:prefLabelis 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:
LeafletMapDeck
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
}
}