243fe7384a01e72a4c632359145577261175e352 - KorAP/Kalamar

commit	243fe7384a01e72a4c632359145577261175e352	[log] [tgz]
author	Uyen-Nhu Tran <125201939+uyen-nhu@users.noreply.github.com>	Wed Apr 10 01:17:24 2024 +0200
committer	Helge <stallkamp@ids-mannheim.de>	Tue Nov 19 12:22:04 2024 +0100
tree	b627b4c3cb0a3d8bda912a9424ce3583850d26f4
parent	70d5205f5eaac66ce40db4aedf27890ca09278b9 [diff]

UI rework by Uyen

2024-11-18
- Delete unnecessary lines from .gitignore file.
- Fix sidebar to not be visible (on non-auth instances), if empty.
- Fix display/behaviour of annotation assistant bar to move correctly, when user types into the searchbar and clicks on the sidebar or anywhere else afterwards.
- Restore unlinted init.js file from patch 16 and add back changes for sidebar, top navbar, etc.

2024-10-30
- Fix overlap of documentation pop-up window.
- Change results area to not being shifted when sidebar is open.
- Add and adjust code for tour links (changed by Helge).
- Fix burger menu behaviour when clicking on tour link.
- Delete news and announcements template files from repository.
- Delete code snippets and files concerning news page.
- Change top navbar to non-sticky.
- Add and adjust code for top navbar items to be configurable (changed by Nils).

2024-10-09
- Add variables for element sizes and spacings.
- Remove static class for shifting the sidebar (fix position for annotation assistant bar on pages with the sidebar open by default).
- Fix shifted view on documentation page on small screens.
- Add check for burger icon existence.
- Add and style legend for login area.
- Delete commented-out code snippets on the go.
- Add new overall line-height.
- Add new logo addon styles back from patch set 12.
- Add back missing class attribute of hint-element.

2024-10-01
- Revise login area to be shown in a dropdown box on hovering the login icon.
- Fix login box focus, when user clicks on auto-completion.
- Add logout icon next to sign out text.
- Create new files for news and announcements (controller, templates) and fix news link.
- Fix visibility of news link for logged in and logged out users.
- Fix empty sidebar issue (make sidebar invisible, if empty).
- Fix animation issue, when the sidebar slides out (blank space, content shift).
- Fix relocation issue of annotation assistant bar.
- Fix navbar to not scroll up initially, when the user clicks on a hash link.
- Fix content display in tour window (title overlapped with text).
- Add tour link to the top navbar.
- Fix burger menu behaviour (lock navbar, when burger menu is active).
- Edit burger menu visibility, when the user clicks on tour link on small screens.
- Add media queries for navbar/dropdown.
- Fix small design issues.

2024-09-11
- Revise sidebar, searchbar, and content slide behaviour.
- Add and fix media queries for sidebar, content, and doc navigation.
- Fix news link and comments.
- Fix small design issues.

2024-08-05
- Fix sidebar visibility on starting page.
- Change slide-in state on start.

2024-07-15
- Improve appearance of title-addon on logo.
- Create and style new item on top navbar for 'News'.
- Change settings link in logout.html.ep to dynamic link.

2024-04-29
- Add an indicator for user login, and some minor design changes.
- Add back content_block headerButtonGroup due to backwards
  compatibility and modify header.html.ep to fit changes.
- Correct color of minimize button for snippets to
  nearly-white, and add media query for border-radius of
  the search bar.
- Delete helper class get_user_name and set user_handle
  instead to get the user name.
- Add scroll functionality for navbar: hide on scroll down,
  show on scroll up.
- Create burger menu and add responsive styles for navbar,
  optimize element positions in header.
- Add and style registration link to fit in login area,
  change navbar size and input fields, improve positionings of
  logo and icons, fix animation of navbar when scrolling on
  small devices.

Change-Id: Ie7803aeafb6683d18de51f8c918fb7b0dd308fcc

30 files changed

tree: b627b4c3cb0a3d8bda912a9424ce3583850d26f4

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 install the latest version of Kalamar, first fetch the resource ...

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

... and follow the steps below.

If you have any problems with installing Kalamar, see the Troubleshooting section.

Generate Static Asset Files

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

You can check your version using

npm -v

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

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

Whenever the assets change, just rerun npm install and grunt.

Start Server

Kalamar uses the Mojolicious framework, that expects a Perl version of at least 5.16. On Windows Strawberry Perl is recommended. An environment based on Perlbrew is recommended, if available. The installation guide requires App::cpanminus as well.

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 https://github.com/Akron/Mojolicious-Plugin-Localize.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.

If the endpoint is remote and requires SSL support, like the default endpoint, you have to install SSL support in addition:

cpanm IO::Socket::SSL

Updates

To update Kalamar, just run

git pull origin master
cpanm --installdeps .
npm install
grunt

And both the server and client dependencies should be up to date.

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

Or in the windows command line with:

> cmd /C "set MOJO_MODE=qr && perl .\script\kalamar daemon"

Or in the windows powershell with:

> $env:MOJO_MODE='myconf'; perl .\script\kalamar daemon; Remove-Item Env:\MOJO_MODE

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 auto rotating secrets. Allow access to a file called kalamar.secret.json in the home directory of kalamar. It will automatically be created, if it doesn't exist. (kalamar.secret is deprecated.)

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.
Tei2KorAPXML: For integrated calls to tei2korapxml, if installed.
KorAPXML2Krill: For integrated calls to korapxml2krill, if installed.
KrillIndexer: For integrated calls to Krilll, if installed and exposed by KRILL_INDEXER_PATH.
KorAPXML2CoNLLU: For integrated calls to conllu2korapxml and korapxml2conllu, if installed.

Maintaining

Caching

Kalamar supports CHI for caching, allowing various cache drivers to configure.

To see options for cache maintenance (e.g. to clear search results after index update), run the command

perl script/kalamar chi

Troubleshooting

`make` not available under Windows

Instead of running

perl Makefile.PL
make test

it is also possible to run the test suite using prove.

prove -lr t

Problem installing Crypt::Random::Source on Windows

Crypt::Random::Source recently removed support for C as a random source, which may lead to missing sources in tests under certain operating systems. You should be able to force install Crypt::Random::Source, though this environment is not recommended for production:

cpanm -f Crypt::Random::Source

Problem installing Mojolicious::Plugin::MailException on Windows

Some versions of Mojolicious::Plugin::MailException have a minor bug in the test suite, so a force install may be necessary.

cpanm -f Mojolicious::Plugin::MailException

Problem running scripts on Windows with Powershell

In case you are having issues with running scripts under Windows, you can set the execution policy with Set-ExecutionPolicy. If using the RemoteSigned execution policy, you can use Unblock-File to allow specific scripts to run.

Problem installing Module::Pluggable

In case Module::Pluggable fails as a dependency of the DateTime module, just force the installation and ignore warnings.

cpanm --force Module::Pluggable

COPYRIGHT AND LICENSE

Original Software

Copyright (C) 2015-2024, IDS Mannheim
Author: Nils Diewald, Helge Stallkamp
Contributor: Eliza Margaretha (Documentation), Susanne Feix and Rebecca Wilm (Translation), Leo Repp

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 Assets

The KorAP logo was designed by Norbert Cußler-Volz is released under the terms of the Creative Commons License BY-NC-ND 4.0. 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).