Zum Hauptinhalt springen

Erste Schritte

Hinweis: 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
Zeigt wie man mit create-kolibri eine neue App anlegen kann.

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

MethodeErläuterung
registerSetzt ein Theme und registriert anschließend den Loader
DEFAULTRegistriert den Loader für z.B. das DEFAULT-Theme
defineCustomElementsRegistriert 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

Developer Tools

Mittels der folgenden Konfiguration in der HTML-Datei können die Developer-Tools 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>