db570fdde76bb79e1cb8ed93be31d8d2aed21ec7 - KorAP/Kalamar

commit	db570fdde76bb79e1cb8ed93be31d8d2aed21ec7	[log] [tgz]
author	Akron <nils@diewald-online.de>	Thu Nov 19 14:39:10 2020 +0100
committer	Akron <nils@diewald-online.de>	Fri Nov 20 13:14:06 2020 +0100
tree	1bcbd9d6364cecadc4797c12a772a56c5aa947ea
parent	636059dd33a8fd60b4cdc26c53f157d45c8c88d0 [diff]

tree: 1bcbd9d6364cecadc4797c12a772a56c5aa947ea

README.md

Kalamar

Kalamar is a Mojolicious-based user interface frontend for the KorAP Corpus Analysis Platform.

Kalamar Screenshots

Setup

The easiest way to install and run Kalamar is using Docker.

$ docker pull korap/kalamar

Then start Kalamar listening on port 64543.

$ docker run --network host --name kalamar korap/kalamar

Kalamar will be available at http://localhost:64543.

See the description on docker hub regarding further information.

Setup for Development

To fetch the latest version of Kalamar ...

$ git clone https://github.com/KorAP/Kalamar

Generate Static Asset Files

To generate the static asset files (scripts, styles, images ...), you need NodeJS >= 6.0.0. For processing Sass, you will need Ruby with the sass gem in addition. This will probably need administration rights, depending on your installation path. These tools may also be available with a package manager.

You can check, if all tools are available using

$ npm -v
$ sass -v

Afterwards you can install grunt and run grunt to create the assets.

$ cd Kalamar
$ npm install -g grunt-cli
$ npm install
$ grunt

Whenever the assets change, just rerun grunt.

Start Server

Kalamar uses the Mojolicious framework, that expects a Perl version of at least 5.16. The recommended environment is based on Perlbrew with App::cpanminus.

Some perl modules are not on CPAN yet, so you need to install them from GitHub. The easiest way to do this is using App::cpanminus. This will probably need administration rights.

$ cpanm git://github.com/Akron/Mojolicious-Plugin-Localize.git
$ cpanm git://github.com/Akron/Mojolicious-Plugin-TagHelpers-ContentBlock.git

Then install the dependencies using App::cpanminus (there is no need to install Kalamar) and run the test suite.

$ cd Kalamar
$ cpanm --installdeps .
$ perl Makefile.PL
$ make test

Kalamar can be deployed like all Mojolicious apps. The easiest way is to start the built-in server:

$ perl script/kalamar daemon

Kalamar will then be available at localhost:3000 in your browser.

By default, Kalamar tries to connect to https://korap.ids-mannheim.de/api/, followed by the most current version of the API. You may change that endpoint to the KorAP API provider in the configuration (see Kustvakt for further information) or by using the environment variable KALAMAR_API.

Configuration

The basic configuration file is kalamar.conf. To define derivations, create a configuration file with the pattern kalamar.myconf.conf and follow the descriptions in kalamar.conf.

To start Kalamar with a derivative configuration, set the MOJO_MODE environment variable.

$ MOJO_MODE=myconf perl script/kalamar daemon

For client-side configurations, a file kalamar.conf.js can be introduced, that will be consulted during the build process, loading optional components using a require(...) directive (see example below).

Secret file

Kalamar uses rotating secrets to sign cookies. Put a file called kalamar.secret in the root of the application with one secret per line.

Localization

To create a localized version of Kalamar, start the localize command with the target locale as its argument, e.g. pl for polish.

$ perl script/kalamar localize pl

The newly defined dictionary file can then be modified and added to the resources definition of the Localize plugin in the configuration:

Localize => {
  resources => ['kalamar.pl.dict']
}

To localize example queries according to a special corpus environment, define a name of the example corpus in the configuration.

Kalamar => {
  examplecorpus => 'mycorpus'
}

Then create a translation file based on kalamar.queries.dict as a blueprint and add it to the Localize resource list.

Templates can be localized and customized by overriding the Template dictionary entries.

Currently the JavaScript translations are separated and stored in dev/js/src/loc. To generate assets relying on different locales, add the locale to Gruntfile.js.

To localize the annotation helper according to a special corpus environment, different annotation foundries can be loaded in kalamar.conf.js. For example to support marmot and malt, the configuration may look like this:

require([
  "hint/foundries/marmot",
  "hint/foundries/malt"
]);

See dev/js/src/hint/foundries for more optional foundries.

Customization

The landing page can be customized by overriding the entry for Template_intro in the dictionary.

Some sections of the user interface can be customized by adding new content blocks. Currently the documented sections are in footer, in the bottom line of the user interface, sidebar, in the left part of the user interface if present, headerButtonGroup, in the right top part of the user interface, and loginInfo, below the login form if present.

Plugins

Some plugins are bundled as part of Kalamar. Plugins can be loaded via configuration file in an array

{
  Kalamar => {
    plugins => ['Auth']
  }
}

Currently bundled plugins are

Auth: For integrating user management supported by Kustvakt full.
Piwik: For integrating Matomo/Piwik

COPYRIGHT AND LICENSE

Original Software

Copyright (C) 2015-2020, IDS Mannheim
Author: Nils Diewald, Helge Stallkamp
Contributor: Eliza Margaretha (Documentation), Susanne Feix (Translation)

Kalamar is developed as part of the KorAP Corpus Analysis Platform at the Leibniz Institute for the German Language (IDS), member of the Leibniz Association and supported by the KobRA project, funded by the Federal Ministry of Education and Research (BMBF).

Kalamar is free software published under the BSD-2 License.

To cite this work, please refer to:
Diewald, Nils, Barbu Mititelu, Verginica and Kupietz, Marc (2019): The KorAP user interface. Accessing CoRoLa via KorAP. In: Cosma, Ruxandra/Kupietz, Marc (eds.), On design, creation and use of of the Reference Corpus of Contemporary Romanian and its analysis tools. CoRoLa, KorAP, DRuKoLA and EuReCo, Revue Roumaine de Linguistique, 64(3). Editura Academiei Române, Bucharest, Romania.

Bundled Software

ALERTIFY.js is released under the terms of the MIT License. Almond is released under the terms of the BSD License. dagre is released under the terms of the MIT License. Highlight.js is released under the terms of the BSD License. Jasmine is released under the terms of the MIT License. RequireJS is released under the terms of the BSD License. Font Awesome by Dave Gandy is released under the terms of the SIL OFL 1.1. Benchmark.js is released under the terms of the MIT License. lodash is released under the terms of the MIT License. Platform.js is released under the terms of the MIT License. INTRO.JS is released under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE (GNU AGPLv3).