jskos-vue

Introduction ​

What is jskos-vue? ​

jskos-vue is a library for Vue 3 containing components and utilities related to the JSKOS data format and the coli-conc project. It was developed to make it easier to use JSKOS data and the coli-conc infrastructure in front-end projects.

Note that it was specifically developed with the needs of our Cocoda Mapping Tool and BARTOC in mind. So if certain decisions seem odd to you, it is probably because it was needed in one of those projects. Nevertheless feel free to contact us with your questions, suggestions, and use-cases!

Overview ​

This library provides the following Vue components (plus some helper components and utility functions):

Requirements ​

For a Node.js project, it is recommended to use Vite. For access to JSKOS data via web APIs we recommend cocoda-sdk or jskos-providers.

The library also supports Vue I18n, see I18n.

Installation ​

bash
npm install jskos-vue

Usage ​

Globally in a Vue project ​

This adds all of jskos-vue's components globally to your Vue project (src/main.js):

js
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

import * as JskosVue from "jskos-vue"
app.use(JskosVue)

// Import stylesheet
import "jskos-vue/dist/style.css"

app.mount('#app')

Globally in a Vue project (individual components) ​

This adds individual components (tree-shakable) globally to your Vue project (src/main.js):

js
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

import { ItemName } from "jskos-vue"
app.use(ItemName)

// Import stylesheet
import "jskos-vue/dist/style.css"

app.mount('#app')

Locally in a Vue project ​

You can also add individual components where needed (e.g. in some SFC, tree-shakable):

js
import { defineComponent } from "vue"
import { ItemName } from "jskos-vue"
// Import stylesheet
import "jskos-vue/dist/style.css"

export default defineComponent({
  // ...
  components: {
    ItemName,
  },
  // ...
})

Browser ​

The library can be used in the browser, for example via jsDelivr.

Fully working HTML example:

html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vue App</title>
    <!-- jskos-vue stylesheet and required libraries (adjust version for updates) -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jskos-vue/dist/style.css">
    <script type="importmap">
    {
      "imports": {
        "vue": "https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.js",
        "jskos-tools": "https://esm.sh/jskos-tools@1.1.2",
        "vue-scrollto": "https://esm.sh/vue-scrollto@2.20.0",
        "jskos-vue-tabs": "https://cdn.jsdelivr.net/npm/jskos-vue-tabs@0.1.8/dist/jskos-vue-tabs.js",
        "jskos-vue": "https://cdn.jsdelivr.net/npm/jskos-vue/dist/jskos-vue.js"
      }
    }
    </script>
  </head>
  <body>
    <div id="app">
      <button @click="scroll('uri:25')">Scroll to 25</button>
      <item-list
        ref="itemList"
        style="height: 100px; overflow-y: scroll; border: 1px solid black; margin-top: 20px;"
        :items="Array.from({ length: 50 }, (v, i) => ({ uri: `uri:${i}`, notation: [`${i}`], prefLabel: { en: `Test ${i}` }}))" />
    </div>
    <script type="module">
      import * as Vue from "vue"
      import * as JskosVue from "jskos-vue" 
      Vue.createApp({
        methods: {
          scroll(uri) {
            this.$refs.itemList.scrollToUri(uri)
          }
        },
      }).use(JskosVue).mount("#app")
    </script>
  </body>
</html>

Localization ​

The library comes with translated messages in English and German. Additional messages can be provided with library Vue I18n or its subset petite-vue-i18n. See test file tests/i18n.test.js for usage.

If Vue I18n is not used, localization is controlled by [jskos-tools] language preferences (function getLanguages and selectLanguage) but there is no way to override or extend translation messages.

Localization of JSKOS itemt content (e.g. labels) is always controlled by jskos-tools language preferences.

Styling Notes ​

Stylesheet ​

In order for the components to work properly, you need to include the library's stylesheet in your project. All the CSS classes and variables are prefixed with jskos-vue, so there should be no conflicts. The stylesheet is available under dist/style.css in the npm package and you can either use import or <style> to include it (see above).

Box Sizing ​

It is recommended to use the following CSS snippet in your applications to make sure box sizing is correctly calculated (more info):

css
html {
  box-sizing: border-box;
}
*, *:before, *:after {
  box-sizing: inherit;
}

This is not included by default because it might break client applications that haven't accounted for this.

CSS Variables ​

Many of the Vue components in jskos-vue use CSS variables, in particular for colors. These can easily be adjusted to match the components to your application. CSS variables are listed in each component's documentation and are defined in shared.css. There are two main ways of changing these variables:

  1. Via CSS :root or class
css
:root {
  --jskos-vue-arrow-color: blue;
}
/* or use a CSS selector that matches the component */
.jskos-vue-arrow {
  --jskos-vue-arrow-color: blue;
}
  1. Via style property
html
<arrow
  direction="right"
  style="--jskos-vue-arrow-color: blue;" />

There are also some global CSS variables that are used by multiple components:

  • --jskos-vue-bgColor - general background color
    • default: white
  • --jskos-vue-highlight-bgColor - highlight background color
    • default: #fdbd5888
  • --jskos-vue-color-lightGrey - light grey color
    • default: #737373

Note that this list is likely going to grow and that defaults can change any time during 0.x.x releases.

Development ​

Please refer to the GitHub README for development instructions.

The TS4NFDI Terminology Service Suite (TSS) provides similar components based on React instead of Vue and TSS includes API calls where jskos-vue leaves this to cocoda-sdk or other methods. A very rough correspondence of components and widgets, ignoring conceptual differences:

jskos-vueTSS
ItemNameTitleWidget
ItemListplanned EntityListWidget
ConceptTreeHierarchyWidget
/GraphViewWidget
ItemSuggestAutocompleteWidget
ItemDetailsEntityInfoWidget
/EntityRelationsWidget

In addition jskos-vue-tabs is similar to TSS TabWidget. A mapping Widget is planned in both jskos-vue and in in TSS.