diff --git a/docs/Other/MetaIdInGUI_1.png b/docs/Other/MetaIdInGUI_1.png new file mode 100644 index 0000000..fd8eb15 Binary files /dev/null and b/docs/Other/MetaIdInGUI_1.png differ diff --git a/docs/Other/metaid.md b/docs/Other/metaid.md new file mode 100644 index 0000000..7f5ff36 --- /dev/null +++ b/docs/Other/metaid.md @@ -0,0 +1,172 @@ +# Links from a dataset +A table may have links to external resources, such as definitions in a classification database or a statistics home page. PxWebApi needs to provide links to these resources. + +The use case is to provide content in the Information pane of the PxWeb gui: + + ![Information pane in PxWeb](MetaIdInGUI_1.png?raw=true) + +If you click on "Statistics page" you go to https://www.ssb.no/en/arblonn . +The response from the API contains the following information for this link: + +```json + "link": { + "related": [ + { + "extension": { + "relation": "statistics-homepage", + "metaid": "KORTNAVN:arblonn" + }, + "href": "https://www.ssb.no/en/arblonn", + "label": "Statistics page", + "type": "text/html" + }, +``` + +So information for a link includes: +``` +href: a URL e.g. "https://www.ssb.no/en/arblonn" , pointing to a resource +label: text describing the resource, like "Statisticspage". +relation: some description of how the resource is related to the table , like "statistics-homepage". + +type: the MIME type of the resource, typically "text/html", but could also be e.g. markdown. +metaid: the META-ID that is the source of the link, e.g. "KORTNAVN:arblonn". +``` + + +The datasource of the API has a property called META-ID. You can attach a META-ID to a table, variable or value to make the API generate a link on the table, a variable or a value. +The META-ID values are urns e.g. "KORTNAVN:arblonn". To attach more than one urn, separate them with a comma. + +The API transforms it to href,type,label and relation according to rules +given in a config file called metaid.config. + +## metaid.config +For links to metadata systems shall be created, the metaid.config file must be placed in the root directory of the application. +In metaid.config the rules are divided into three sections in the metaid.config file for attachments at tables, variables and values. The sections are be named: +* onTable +* onVariable +* onValue + +A "rule" is called a metaSystem and is identified by an ID which is a string. +When the API finds a META-ID, it iterates through all metasystems for the attachment level and checks whether the META-ID starts with the ID of the metasystem. If it matches, one or more links are generated. + +The rest of the META-ID after the ID of the metasystem is considered to be arguments. If the META-ID value is KORTNAVN:arblonn and there is a metasystem with ID KORTNAVN, the argument is arblonn. +If the META-ID value is KORTNAVN:arblonn:arg2 and there is a metasystem with ID KORTNAVN, the arguments are arblonn and arg2. + +In addition to the ID, each Metadata system has configuration for +* relation to the table, variable or value it is attached to +* Language +* Label (text) format +* URL format + +The URL format normally contains placeholders {0}, {1} … {n} where the arguments from the META-ID will be inserted. +The label format may contain placeholders depending on the attachment level, for values {0} will be replaced by the name of the variable and {1} by the name of the value. +For variables it's just {0} for the name of the variable. For label formats in the onTable section there are no placeholders. +(A metasystem may contain the name of a labelsFile. This is for cases where the generated text is not suitable and manually writen texts are needed.) + +For example this fragment of the config file: +```xml + + + + + + + + + ... + +``` + +When the API finds this META-ID "KORTNAVN:arblonn", on table level, it creates +```json + "link": { + "related": [ + { + "extension": { + "relation": "statistics-homepage", + "metaid": "KORTNAVN:arblonn" + }, + "href": "https://www.ssb.no/en/arblonn", + "label": "Statistics page", + "type": "text/html" + }, +``` +for an English request. + + +Here is a full metaid.config: +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +Note: +* The GUI looks for links with relation "statistics-homepage", "about-statistics" and "definitions" to show in the Information pane. +* The metaSystem KORTNAVN creates 2 links per language. +* The last metaSystem on value does not use the name of the variable, only the name of the value. + +### Labels file +```xml + +``` +and +```xml + + + +