Cocoda Mapping Tool

A web-based tool for creating mappings between knowledge organization systems.

Try out the latest release version, the current development version, and consult the usage documentation!

Table of Contents

• Install
  • Release versions
  • Development versions
  • Serving the Files
  • Docker
• Usage
• Configuration
• Maintainers
• Contribute
• License

Install

Release versions

Releases can be downloaded in form of static files. Extract into a web server directory and adjust configuration file cocoda.json. You could automate download and extraction of the latest release with jq like this:

```bash

You can also manually download the latest release here: https://github.com/gbv/cocoda/releases/latest

wget -N $(curl -s https://api.github.com/repos/gbv/cocoda/releases/latest | jq -r '.assets[].browserdownloadurl') unzip cocoda-.zip rm cocoda-.zip ```

The directory cocoda is then ready to be served with any web server.

Development versions

Alternatively, it's possible to clone the Cocoda repository:

bash git clone https://github.com/gbv/cocoda.git cd cododa

Then install required Node modules with npm and run build (requires Node.js v18 or above, v20 recommended):

bash npm ci npm run build

Files are created in directory dist, including the configuration file.

Serving the Files

Any web server can be used to serve Cocoda files. No special configuration is necessary. For instance using the http-server npm package to serve Cocoda at http://localhost:8000:

```bash

serve the pre-built release

npx http-server -p 8000 cocoda/

or serve the build version

npx http-server -p 8000 dist/ ```

Docker

Cocoda is also available via Docker. Please refer to our Docker documentation for more information and instructions.

Usage

There is a detailled end-user manual available in German and in English. The German version will likely be more up-to-date. Documentation sources are located in directory docs.

Configuration

For the pre-built version, configuration options can be overridden by using cocoda.json in the root of the directory and by passing query parameter config with an URL of a config file (CORS headers must be enabled to load if from another domain).

The default options are given in the file config/cocoda.default.json (please consult this file for examples on how to use the configuration options). When using a manual build, create file config/cocoda.json and rebuild (npm run build) after editing (you can also run npm run build -- --config-only if you already have a build in folder dist/ and only need to update the config file).

The following fields are recognized so far:

• title: the main title of the instance as plain string

• cssProperties: object of global CSS properties, used for color settings

• logos: a list of logos to display left to the title, each with subfields:

  • file: image URL relative to the public directory
  • alt: alternate text for the image, if the image cannot be displayed, as plain string
  • url: URL to link from the logo

• favicon: URL of a custom favicon.

• menu: a list of links to show in the menu, each with subfields:

  • url: the link URL
  • prefLabel: mapping of language codes to link titles

• searchLinks: a list of search links to quickly link to external resources from concepts. Each searchlink has subfields:

  • url an URL template with possible parameters {prefLabel} and/or {notation}
  • prefLabel: mapping of language codes to link titles
  • separator: defines how to join multiple values (especially multiple {notation} values) when constructing the final URL.

• favoriteSchemes: list of vocabulary URIs to be favorited by default.

• languages: array with supported interface languages

• registries: lists registries where to get data from

• overrideRegistries: false (default) or true controls whether to override registries listed in config/cocoda.default.json

• auth: URL to a login-server instance to be used for authentication

• conceptLists: a list of concept lists. Each list can be either an object or a URL that returns a JSON object. Objects are basically JSKOS registries with required properties prefLabel and concepts. If concepts is a string, it will be considered a URL which returns a JSON array of concepts. Optional properties are notation and scopeNote.

• autoRefresh: an object with auto refresh values in milliseconds. autoRefresh.mappings determines how often mappings in MappingBrowser will be reloaded (default: 10000 = every 10 seconds), autoRefresh.update determines how often Cocoda will look for an update (default: 120000 = every 2 minutes).

Using the pre-built version, the application only has to be reloaded after editing the configuration file.

Color settings

Colors can be changed with the cssProperties configuration object. Most colors are derived from a set of basic color codes, each given with three values in HSL color model (hue, saturation, and lightness). Some other colors can be given by standard CSS color name or code. Colors can be provided as hexadecimal RGB value or, for selected properties, with HSL value components. The following color properties are can be configured, at least:

| Color Property | Description | HSL | |:----------------------------------|:----------------------------------------------------------------------------|-----| | color-primary | Primary color is for selected elements, links, etc. | ✓ | | color-secondary | Secondary color is for menus, selectable elements, warnings, etc. | ✓ | | color-text | Color for text, labels, etc. | ✓ | | color-text-secondary | Color for text on background color-secondary | ✓ | | color-button | Color for clickable buttons | ✓ | | color-success | Color for confirmation messages, mapped concepts, positive votes | ✓ | | color-danger | Color for error messages, error indicators, delete buttons, negative votes | ✓ | | color-background | Background color of the application | | | color-background-component | Background color of components (concept browser, mapping editor, etc.) | | | color-background-component-heading | Background color for component headings. | | | color-background-navbar | Background color for the navigation bar | | | color-link | Color of the links | | | color-link-hover | Color of the links when hovering | |

See src/style/colors.css for additional CSS color properties. Some comments are included to provide clarity on its purpose and usage within the application. Property names not included in the list above may change in future releases.

For instance the color property color-primary can be set in RGB like this:

json "cssProperties": { "color-primary": "#00ffff" } Or you can set the individual HSL values:

json "cssProperties": { "color-primary-h": "180", "color-primary-s": "100%", "color-primary-l": "40%" } Internally, RGB values will also be converted to HSL for properties if the property supports HSL.

Image files

Images files (.png, .svg, .ico) in the config directory are made available at path /config and can be referenced like this:

~~~json "favicon": "config/favicon.ico", "logos": [ { "file": "config/logo.png", "alt": "Mapping Editor ", "url": "https://example.org/" } ] ~~~

Maintainers

• @nichtich
• @rodolv-commons

Contribute

Your contributions to improve Cocoda are very welcome: please open a GitHub issue for feature suggestions and bug reports! See the file CONTRIBUTING.md for more information about how and where to best contribute and for development details.

See https://gbv.github.io/cocoda/ for API documentation automatically build from Node sources.

License

MIT ©2019 Verbundzentrale des GBV (VZG)