Refbox services integration

Refbox?

A box to display repository-service integration:

#359 #233, part of lindat-common

Internally it uses rest api call to obtain json such as the following (shortened...)

{
  "displayText": "Zeman, Daniel; Mareček, David; Mašek, Jan; Popel, Martin; Ramasamy, Loganathan; Rosa, Rudolf; Štěpánek, Jan and Žabokrtský, Zdeněk, 2015, \n  <i>HamleDT 3.0</i>, LINDAT/CLARIN digital library at Institute of Formal and Applied Linguistics, Charles University in Prague, \n  <a href=\"http://hdl.handle.net/11234/1-1508\">http://hdl.handle.net/11234/1-1508</a>.\n",
  "exportFormats": {
    "exportFormat": [...]
  },
  "featuredServices": {
    "featuredService": [
      {
        "name": "PML-TQ",
        "url": "https://lindat.mff.cuni.cz/services/pmltq/",
        "description": "Tool for searching and browsing treebanks online",
        "links": {
          "entry": [
            {
              "key": "Czech",
              "value": "https://lindat.mff.cuni.cz/services/pmltq/#!/treebank/hamledt_cs"
            },
            {
              "key": "Arabic",
              "value": "https://lindat.mff.cuni.cz/services/pmltq/#!/treebank/hamledt_ar"
            },
            ...
          ]
        }
      },
      {
        "name": "KonText",
        "url": "http://lindat.mff.cuni.cz/services/kontext",
        "description": "KonText is a basic web application for querying corpora",
        "links": {
          "entry": [
            {
              "key": "Tamil",
              "value": "http://lindat.mff.cuni.cz/services/kontext/run.cgi/first_form?corpname=hamledt_30_ta_a"
            },
            {
              "key": "Dutch",
              "value": "http://lindat.mff.cuni.cz/services/kontext/run.cgi/first_form?corpname=hamledt_30_nl_a"
            },
            ...
          ]
        }
      }
    ]
  },
  "title": "HamleDT 3.0"
}

There are two featured services and both of them have links (shown in the dropdown list) to subsets of the data. The available services, their url and description are defined in a configuration file. Association between an item and a service happens by adding specific metadata fields. This is possible through UI (see sections below).

Basic configuration

The featured services are configured in two places:

1. configuration file lr.cfg
2. metadata schema definitions

In lr.cfg you list all the services, their names, urls and descriptions. For example:

###############
#
# featured services config
#
###############
featured.services = pmltq,kontext
featured.service.kontext.fullname = KonText
featured.service.kontext.url = http://lindat.mff.cuni.cz/services/kontext
featured.service.kontext.description = KonText is a basic web application for querying corpora
featured.service.pmltq.fullname = PML-TQ
featured.service.pmltq.url = https://lindat.mff.cuni.cz/services/pmltq/
featured.service.pmltq.description = Tool for searching and browsing treebanks online

The line featured.services = is a comma separated list which defines sort of aliases for the service names. These are used on the next lines and in the second part (metadata schema definitions) of configuration. The schema for the rest of the lines is featured.service.ALIAS.{fullname,url,description}, where ALIAS is one from the featured.services = line.

The other part of configuration is in one of the metadata registries (the one called local). You need to create a new field for each alias.

For the example we have here, there are fields called:

local.featuredService.kontext
local.featuredService.pmltq

The schema is local.featuredService.ALIAS where alias is the string defined in the lr.cfg file above. You can add these fields through UI (xmlui/admin/metadata-registry) or define them in local-types.xml and reimport the file with bin/dspace.

UI

After finishing the configuration it's possible to indicate the presence of an item in a service. This is done by filling the local.featuredService.ALIAS metadata for that item. When you are viewing an item you can click edit item and go to "Services" tab. There you can add keys and values. In the example case the keys are language names (eg. "Dutch") and the value is link to the Dutch data in the service (eg. "http://lindat.mff.cuni.cz/services/kontext/run.cgi/first_form?corpname=hamledt_30_nl_a"). This tab is available to administrators and to members of group "Service Managers"

Adding new service

Let's add a service called "NeW service" alongside already defined services. We'll choose an alias "newservice".

1. Modify lr.cfg, add new alias featured.services = pmltq,kontext,newservice
2. add the rest of the definitions in lr.cfg

...
featured.service.newservice.fullname = NeW service
featured.service.newservice.url = http://example.com/newservice
featured.service.newservice.description = This is a great new service

3. as an administrator login to the repository, go to xmlui/admin/metadata-registry and edit the local registry. The element name is featuredService, the qualifier is newservice. After confirming the list should contain local.featuredService.newservice
4. view an item, click edit, click services tab. You should already see a form for "NeW service", fill it out.