Erste Schritte

Für Projekt im ITZBund gibt es ein vorgegebenes Seed-Projekt, welches über die internen Kommunikationswege angefragt werden kann.

Neues Projekt erstellen

Ein neues Projekt kann mit Hilfe des Kommandozeilenassistenten schnell erstellt werden.

npm init kolibri@latest my-kolibri-app

Einbinden in ein bestehendes Projekt

Einbinden von Schriftarten

Schriftarten werden von Natur aus losgelöst vom CSS geladen und müssen je nach KoliBri-Theme in die projektspezifische Rahmenseite (index.html) eingebunden werden.

Hierzu können die in der Bibliothek mitgelieferten Schriftarten in die eigenen Assets kopiert werden: node_modules/@public-ui/themes/assets, oder eigene verwendet werden.

Bitte importieren Sie nur die Schriftarten und Icons, die Sie verwenden, um unnötigen Datentransfer zu vermeiden.

<!DOCTYPE html>
<html lang="de" dir="ltr">
 <head>
  <title>Webapplication | KoliBri</title>
  <meta charset="UTF-8" />
  <meta name="description" content="..." />
  <base href="/" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="shortcut icon" type="image/x-icon" href="assets/kolibri.ico" />
  <link rel="stylesheet" href="assets/bundes/style.css" />
  <link rel="stylesheet" href="assets/codicons/codicon.css" />
  <link rel="stylesheet" href="assets/fontawesome-free/css/all.min.css" />
  <link rel="stylesheet" href="assets/icofont/icofont.min.css" />
  <link rel="stylesheet" href="assets/kreon/style.css" />
  <link rel="stylesheet" href="assets/noto-sans/noto-sans.css" />
  <link rel="stylesheet" href="assets/material-icons/iconfont/material-icons.css" />
  <link rel="stylesheet" href="assets/material-symbols/index.css" />
  <link rel="stylesheet" href="assets/roboto/roboto.css" />
  <link rel="stylesheet" href="assets/tabler-icons/tabler-icons.css" />
 </head>
</html>

Typescript

Um eine umfängliche Codevervollständigung zu erhalten, benötigen Sie folgenden Eintrag in der tsconfig.json:

{
 "compilerOptions": {
  ...
 "moduleResolution": "Node",
  ...
 },
 ...
}

I Vite + React

1. Installieren der KoliBri-Bibliotheken

npm i @public-ui/components @public-ui/themes @public-ui/react

pnpm i @public-ui/components @public-ui/themes @public-ui/react

yarn add @public-ui/components @public-ui/themes @public-ui/react

2. Integration

main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import "./index.css";

+import { register } from "@public-ui/components";
+import { defineCustomElements } from "@public-ui/components/dist/loader";
+import { DEFAULT } from "@public-ui/themes";

+register(DEFAULT, defineCustomElements)
+ .then(() => {
  ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
  <App />
  </React.StrictMode>
  );
+ })
+ .catch(console.warn);

3. Modul einbinden

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Vite + React + TS</title>
+ <script type="module" src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"></script>
  </head>
  <body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

4. Beispiel

import React from 'react';
import { KolSpin } from '@public-ui/react';

export const AppComponent = () => {
 return (
  <div>
   <KolSpin _show />
  </div>
 );
};

II Vite + Vue

1. Installieren der KoliBri-Bibliotheken

npm i @public-ui/components @public-ui/themes @public-ui/vue

pnpm i @public-ui/components @public-ui/themes @public-ui/vue

yarn add @public-ui/components @public-ui/themes @public-ui/vue

2. Plugin

kolibri.plugin.ts

import type { Plugin } from 'vue';
import { defineCustomElements } from '@public-ui/components/dist/loader';
import { register } from '@public-ui/components';
import { ITZBund } from '@public-ui/themes';
export const ComponentLibrary: Plugin = {
 install() {
  register(ITZBund, defineCustomElements)
   .then(() => console.log('Components registered'))
   .catch(console.warn);
 },
};

main.ts:

import { createApp } from 'vue'
import App from './App.vue'
import './assets/main.css'
+ import { ComponentLibrary } from './vue.plugin'

const app = createApp(App)

+ app.use(ComponentLibrary)

app.mount('#app')

3. Modul einbinden

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="UTF-8" />
  <link rel="icon" href="/favicon.ico" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <script type="module" src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"></script>
  <title>Vite App</title>
  </head>
  <body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
  </body>
</html>

4. Konfiguration anpassen

vite.config.ts

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
- plugins: [],
+ plugins: [
+ vue({
+ template: {
+ compilerOptions: {
+ // treat all tags with a dash as custom elements
+ isCustomElement: (tag) => tag.includes('-')
+ }
+ }
+ })
+ ],
  resolve: {
  alias: {
  '@': fileURLToPath(new URL('./src', import.meta.url))
  }
  }
})

5. Beispiel

<KolInputText :_value="text" :_on="{ onChange: (e: unknown, v: string) => (text = v) }"></KolInputText>
<KolButton _label="Text löschen" :_on="{ onClick: () => (text = '') }"></KolButton>

Hinweis: KoliBri-Inputs übergeben in der Regel das Ursprungsevent als ersten Parameter und den Wert des Feldes als Zweiten.

III React

1. Installieren der KoliBri-Bibliotheken

npm i @public-ui/components @public-ui/themes @public-ui/react

pnpm i @public-ui/components @public-ui/themes @public-ui/react

yarn add @public-ui/components @public-ui/themes @public-ui/react

2. Registrieren des KoliBri-Loaders

Nachdem die Vorbereitungen abgeschlossen sind, muss nur noch der KoliBri-Loader registriert werden. Er sorgt dafür, dass die Web Components asynchron (lazy) nachgeladen werden, sobald sie in der Webseite verwendet werden.

Methode	Erläuterung
register	Setzt ein Theme und registriert anschließend den Loader
DEFAULT	Registriert den Loader für z.B. das DEFAULT-Theme
defineCustomElements	Registriert den Loader für die Web Components

3. Integration

import React from 'react';
import ReactDOM from 'react-dom';

import { AppComponent } from './components/app/component';

import { register } from '@public-ui/core';
import { defineCustomElements } from '@public-ui/components/dist/loader';
import { DEFAULT } from '@public-ui/themes';

register(DEFAULT, defineCustomElements)
 .then(() => {
  const htmlDivElement: HTMLDivElement | null = document.querySelector<HTMLDivElement>('div#app');
  if (htmlDivElement instanceof HTMLDivElement) {
   const root = createRoot(htmlDivElement);
   root.render(<AppComponent />);
  }
 })
 .catch(console.warn);

4. Beispiel

import React from 'react';
import { KolSpin } from '@public-ui/react';

export const AppComponent = () => {
 return (
  <div>
   <KolSpin _show />
  </div>
 );
};

IV Ohne Framework

npm i @public-ui/components @public-ui/themes

pnpm i @public-ui/components @public-ui/themes

yarn add @public-ui/components @public-ui/themes

<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/vite.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Title</title>
+ <script type="module" src="/node_modules/@public-ui/components/dist/kolibri/kolibri.esm.js"></script>
  </head>
  <body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Um Codevervollständigung zu erhalten kann es notwendig sein .vscode/settings.json zu erstellen und Folgendes einzufügen:

{
 "html.customData": ["./node_modules/@public-ui/components/vscode-custom-data.json"]
}

Hierbei ist die Web-Component Schreibweise (kebab-case) zu verwenden. (z.B.: <kol-heading _label="">)

V Statische Webseite

Um KoliBri in eine statische Webseite einzubauen muss lediglich das folgende Script-Tag eingebunden werden. Sofern Schriftarten und/oder Icons verwendet werden, müssen diese, wie oben beschrieben, eingebunden werden.

<script type="module">
 import { register } from 'https://unpkg.com/@public-ui/components/dist/esm/index.js';
 import { defineCustomElements } from 'https://unpkg.com/@public-ui/components/dist/loader/index.js';
 import { ITZBund } from 'https://unpkg.com/@public-ui/themes/dist/index.mjs';
 register(ITZBund, defineCustomElements).catch(console.warn);
</script>

Hierbei ist die Web-Component Schreibweise (kebab-case) zu verwenden. (z.B.: <kol-heading _label="">)

Weitere Optionen

Entwickler Werkzeuge

Mittels der folgenden Konfiguration in der HTML-Datei können die Entwickler-Werkzeuge von KoliBri aktiviert werden.

…
<html>
 <head>
  <meta name="kolibri" content="dev-mode=true" />
 </head>
 …
</html>

Experimenteller Modus

Mittels der folgenden Konfiguration in der HTML-Datei kann der experimentelle Modus aktiviert werden.

…
<html>
 <head>
  <meta name="kolibri" content="experimental-mode=true" />
 </head>
 …
</html>

Farbkontrastanalyse

Um Farbkontrastfehler innerhalb des DOMs zu erkennen, können Sie mittels der folgenden Konfiguration die Farbkontrastanalyse aktivieren.

…
<html>
 <head>
  <meta name="kolibri" content="color-constrast-analysis=true" />
 </head>
 …
</html>

Neues Projekt erstellen​

Einbinden in ein bestehendes Projekt​

Einbinden von Schriftarten​

Typescript​

I Vite + React​

1. Installieren der KoliBri-Bibliotheken​

2. Integration​

3. Modul einbinden​

4. Beispiel​

II Vite + Vue​

1. Installieren der KoliBri-Bibliotheken​

2. Plugin​

3. Modul einbinden​

4. Konfiguration anpassen​

5. Beispiel​

III React​

1. Installieren der KoliBri-Bibliotheken​

2. Registrieren des KoliBri-Loaders​

3. Integration​

4. Beispiel​

IV Ohne Framework​

V Statische Webseite​

Weitere Optionen​

Entwickler Werkzeuge​

Experimenteller Modus​

Farbkontrastanalyse​

Neues Projekt erstellen

Einbinden in ein bestehendes Projekt

Einbinden von Schriftarten

Typescript

I Vite + React

1. Installieren der KoliBri-Bibliotheken

2. Integration

3. Modul einbinden

4. Beispiel

II Vite + Vue

1. Installieren der KoliBri-Bibliotheken

2. Plugin

3. Modul einbinden

4. Konfiguration anpassen

5. Beispiel

III React

1. Installieren der KoliBri-Bibliotheken

2. Registrieren des KoliBri-Loaders

3. Integration

4. Beispiel

IV Ohne Framework

V Statische Webseite

Weitere Optionen

Entwickler Werkzeuge

Experimenteller Modus

Farbkontrastanalyse