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
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
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
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
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
<!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>