commit	4d6e508d0a9ca52b60521e9dab6fc7a2b24ba31d	[log] [tgz]
author	Helge <stallkamp@ids-mannheim.de>	Wed Oct 09 16:55:07 2024 +0200
committer	Helge <stallkamp@ids-mannheim.de>	Wed Oct 09 17:32:40 2024 +0200
tree	528bcb69bf15446d0bc78684822582b4dd6a6e8b
parent	dc1aaeb973c8edd788d9e9da7fff874d30c578ad [diff]

tree: 528bcb69bf15446d0bc78684822582b4dd6a6e8b

README.md

Kalamar-Plugin-Export

Kalamar-Plugin-Export Screenshot

Description

Kalamar-Plugin-Export is a web service that integrates in the plugin framework of Kalamar, to export matches for the KorAP Corpus Analysis Platform in various formats. Currently supported are RTF, CSV, and JSON.

Kalamar-Plugin-Export is meant to be a basic export plugin and should demonstrate and evaluate the plugin capabilities of Kalamar.

Prerequisites

Java 17 (OpenJDK or Oracle JDK), Git, Maven 3. Further dependencies are resolved using Maven.

Build

To build the latest version of Kalamar-Plugin-Export, do ...

git clone https://github.com/KorAP/Kalamar-Plugin-Export
cd Kalamar-Plugin-Export

... and build the jar file ...

mvn clean package

Afterwards the jar file is located in the target/ folder and can be started with ...

java -jar KalamarExportPlugin-[VERSION].jar

Per default, this will start a server at http://localhost:7777. It will also create a subfolder files to temporarily store created exports.

Registration of the plugin in Kalamar is not yet officially supported. Registration works by passing the following JSON blob to the plugin registration handler.

{
  "name" : "Export",
  "desc" : "Exports Kalamar results",
  "embed" : [{
    "panel" : "result",
    "title" : "exports KWICs and snippets",
    "icon" : "\uf019",
    "classes" : ["button-icon", "plugin" ],
    "onClick" : {
      "action" : "addWidget",
      "template" : "http://localhost:7777/export",
      "permissions":["forms","scripts","downloads"]
    }
  }]
}

The simplest way to do this at the moment is by storing the json blob in a file (the blob needs to be in a list, i.e. surrounded by [...]). The file then can be loaded using the Plugins addon in Kalamar using the Kalamar configuration file.

{
  Kalamar => {
    plugins => ['Plugins'],
  },
  'Kalamar-Plugins' => {
    default_plugins => 'plugins.json'
  }
}

For example, with this configuration addition, the content of plugins.json will be registered on every Kalamar page load.

An example demo showcases the embedded plugin.

At the moment the integration reuses the session of the host service. To make this possible, the Content Security Policy of Kalamar needs to be extended to include the whole domain that hosts both services (at the moment it's not possible to host the service on a different domain). If the domain is, e.g., ids-mannheim.de, the configuration in the Kalamar configuration file needs to be:

{
  CSP => {
    'frame-src' => 'self',
    'frame-ancestors' => ['self','https://*.ids-mannheim.de/']
  }
}

Customization

The basic configuration file is stored in src/main/resources/exportPlugin.conf. To change the configuration create a new config file and run the jar with the according filename as argument:

java -jar KalamarExportPlugin-[VERSION].jar myconf_exportPlugin.conf

Alternatively a file named exportPlugin.conf can be stored in the same directory as the java jar.

License

Kalamar-Plugin-Export is developed as part of the KorAP Corpus Analysis Platform at the Leibniz Institute for the German Language (IDS).

Kalamar-Plugin-Export is published under the BSD-2 License.