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:

# 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[].browser_download_url')
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:

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):

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:

# 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 static directory
  • alt: alternate text for the image, if the image cannot be displayed, as plain string
  • url: URL to link from the logo

• 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

• 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:

"cssProperties": {
  "color-primary": "#00ffff"
}

Or you can set the individual HSL values:

"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.

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)