{t(
'Leerer Zustand — über Daten auf Voll oder Demo wechseln.',
'Empty state — switch Data to Full or Demo.',
'Estado vacío — cambia Datos a Completo o Demo.',
)}
);
}
```
Die Liste entsteht aus React-Daten. Ein Klick aktualisiert den lokalen State. Für Datenzugriff, Speicherung und Navigation nutzt du deine eigene API und die Komponenten deiner Anwendung.
## Die Bausteine
- `data` enthält die widgetspezifische Konfiguration.
- `id` identifiziert optional die Instanz.
- Callback-Props wie `onCellClick` melden Interaktionen.
- Inhaltsslots erlauben eigene React-Elemente und weitere Widgets.
[React einrichten](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components) · [Komponenten kombinieren](/docs/react/patterns/nested-widget-descriptors).
# Was ist ein Widget?
Ein **arcWidget** ist eine fertige Business-Oberfläche — Tabelle, Kalender, Kanban, Layout — die du über ein deklaratives **Datenobjekt** konfigurierst. Dieses plattformübergreifende Modell lässt dich beschreiben, *was* das Widget zeigen und tun soll, während die Engine sich um Architektur, Styling und Event-Routing kümmert.
Typische Bausteine: `uniqueId`, `data`, Slots, `actions`, `styles`.
In **Ninox** setzt du das Widget in ein Formelfeld. Einmal **Global Code** pro Team, dann der **Anwendungscode** dort, wo die Oberfläche erscheinen soll — ohne eigene App zu bauen.
🔧 Anpassbar im Formelfeld
✨ HTML/CSS-UI statt Ninox-Standardformulare
🚀 In wenigen Minuten eingebunden
Mehr zur Einrichtung: [Widget-Integration in Ninox](/docs/intro/aufbau-in-nx-db).
Beispiel: Aufgaben in einer Liste abhaken, ohne jeden Datensatz zu öffnen — [Custom Table](/docs/widgets/custom-table).
# Was ist ein Widget?
Ein **arcWidget** ist eine fertige Business-Oberfläche — Tabelle, Kalender, Kanban, Layout — die du über ein deklaratives **Datenobjekt** konfigurierst. Dieses plattformübergreifende Modell lässt dich beschreiben, *was* das Widget zeigen und tun soll, während die Engine sich um Architektur, Styling und Event-Routing kümmert.
Typische Bausteine: `uniqueId`, `data`, Slots, `actions`, `styles`.
In **Vue** gilt derselbe deklarative `data`-Vertrag. Der Widget-Core sorgt für die Performance; das öffentliche Paket `@arcrider/arcwidgets-vue` übernimmt die Vue-Integration via Props und Emits.
Einrichtung: [Vue einrichten](/docs/intro/setup-vue). Widget-Beispiel: [Custom Table](/docs/widgets/custom-table).
---
# Widgets und Mini-Widgets
Source: https://www.arc-rider.com/docs/intro/widgets-und-mini-widgets
# Widgets und Mini-Widgets in React
Das React-Paket enthält acht Premium-Widgets für größere Oberflächen und 14 Mini-Widgets für Eingabe, Darstellung und Layout. Beide Gruppen werden aus demselben Paket importiert.
## Premium-Widgets
Table, Kanban, drei Kalenderansichten, Drawing, Upload und Slideshow decken Listen, Planung, Zeichnungen, Dateiübernahme und Präsentation ab. Für produktive Nutzung gelten die Bedingungen der Projektlizenz.
## Mini-Widgets
Button, Badge, Input, Select, Signature, Icon, Text, Progress Bar, Layout, Numpad, Slider, Steps, KPI Bar und DevTools sind kleinere Bausteine. Du kannst sie eigenständig oder in den Inhaltsslots größerer Widgets verwenden.
## Widgets zusammensetzen
```tsx
import {
ArcWidgetBadge,
ArcWidgetButton,
ArcWidgetLayout,
ArcWidgetText,
} from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [count, setCount] = useState(pack === 'busy' ? 12 : 0);
const badges =
pack === 'empty'
? []
: [
{ value: t('Offen', 'Open', 'Abierto'), color: '#d97706' },
{ value: t('Live', 'Live', 'En vivo'), color: '#15803d' },
...(pack === 'busy'
? [
{
value: t('Priorität', 'Priority', 'Prioridad'),
color: '#be123c',
},
{ value: t('Messe', 'Fair', 'Feria'), color: '#7c3aed' },
]
: []),
];
return (
),
},
...(badges.length
? [
{
height: 'auto' as const,
value: (
({
width: 'auto',
height: 'auto',
value: (
),
})),
}}
/>
),
},
]
: []),
{
height: 'fraction',
value: (
setCount((value) => value + 1)}
/>
),
},
],
}}
/>
);
}
```
In React lassen sich unterstützte Slots direkt mit JSX befüllen. So bleiben die Callbacks verschachtelter Komponenten an deinem State. Die Slideshow ist eine Ausnahme: Ihre Slides verwenden aktuell String-Inhalte.
[Komponentenübersicht mit allen Referenzen](/docs/react/intro/react-components) · [JSX und Deskriptoren](/docs/react/patterns/nested-widget-descriptors) · [Lizenzierung](/docs/react/faq/react-paket-und-lizenzierung).
# Widgets und Mini-Widgets
**Widgets** sind eigenständige Business-Oberflächen. **Mini-Widgets** sind kleinere Bausteine — allein oder in einem größeren Widget.
## Widgets
Größerer Umfang, eigene Logik, oft der Kern einer Ansicht: Tabelle, Kalender, Kanban, Layout.
- mehr Parameter und Zustände
- eigener Use Case (Liste, Planung, Board)
- meist die Fläche, in der Mini-Widgets landen
Beispiel: [Custom Table](/docs/widgets/custom-table) — Zeilen, Filter, Zellen mit Mini-Widgets.
In Ninox heißt der Einstieg `arcCustomTable({ … })` im Formelfeld.
## Mini-Widgets
Schmaler Fokus: Button, Badge, Select, Fortschrittsbalken. Wenig Konfiguration, oft in Tabellen-Zellen oder Layout-Blöcken.
Beispiele:
- [Select](/docs/mini-widgets/select) — Dropdown mit Styling
- [Progress Bar](/docs/mini-widgets/progress-bar) — Fortschritt in einer Zelle oder einem Formular
In Ninox: `arcCustomSelect`, `arcCustomProgressBar`, `arcCustomButton`, …
## Widgets in Widgets
Mini-Widgets sitzen in Slots größerer Widgets — Zellen, Layout-Blöcke, Karten. Auch ein volles Widget kann in einem anderen landen, zum Beispiel [Custom Layout](/docs/widgets/custom-layout) in einer [Custom Table](/docs/widgets/custom-table)-Zelle (Text + Badge + Fortschritt).
Wie die verschachtelte Schreibweise aussieht: [Nested Widget Descriptors](/docs/patterns/nested-widget-descriptors).
# Widgets und Mini-Widgets
**Widgets** sind eigenständige Business-Oberflächen. **Mini-Widgets** sind kleinere Bausteine — allein oder in einem größeren Widget.
## Widgets
Größerer Umfang, eigene Logik, oft der Kern einer Ansicht: Tabelle, Kalender, Kanban, Layout.
- mehr Parameter und Zustände
- eigener Use Case (Liste, Planung, Board)
- meist die Fläche, in der Mini-Widgets landen
Beispiel: [Custom Table](/docs/widgets/custom-table) — Zeilen, Filter, Zellen mit Mini-Widgets.
In Vue heißt die Komponente `ArcWidgetTable`.
## Mini-Widgets
Schmaler Fokus: Button, Badge, Select, Fortschrittsbalken. Wenig Konfiguration, oft in Tabellen-Zellen oder Layout-Blöcken.
Beispiele:
- [Select](/docs/mini-widgets/select) — Dropdown mit Styling
- [Progress Bar](/docs/mini-widgets/progress-bar) — Fortschritt in einer Zelle oder einem Formular
In Vue dieselben Namen wie in React, als Komponenten oder als Nested Descriptor in einem Slot.
## Widgets in Widgets
Mini-Widgets sitzen in Slots größerer Widgets — Zellen, Layout-Blöcke, Karten. Auch ein volles Widget kann in einem anderen landen, zum Beispiel [Custom Layout](/docs/widgets/custom-layout) in einer [Custom Table](/docs/widgets/custom-table)-Zelle (Text + Badge + Fortschritt).
Wie die verschachtelte Schreibweise aussieht: [Nested Widget Descriptors](/docs/patterns/nested-widget-descriptors).
---
# React einrichten
Source: https://www.arc-rider.com/docs/intro/setup-react
# React einrichten
arcWidgets liefert 22 konfigurierbare Komponenten für Geschäftsanwendungen. Du beschreibst die Anzeige in `data` und verbindest Interaktionen über Callback-Props mit deinem State und deiner API.
## Installation
```bash
npm install --save-exact @arcrider/arcwidgets-react@0.1.0-alpha.5
```
Diese Dokumentation gehört zu `0.1.0-alpha.5`. Das Paket benötigt React und React DOM 18 oder 19 und läuft im Browser. Die Styles sind enthalten; ein separater CSS-Import ist nicht nötig. Die Version ist eine Alpha: Prüfe deine verwendeten Workflows vor einem Update.
## Erstes Widget
Dieses vollständige Beispiel kann als `App.tsx` in einer React-Browser-App verwendet werden:
```tsx
import { ArcWidgetBadge, ArcWidgetKanban } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const startLanes = [
{
id: 'open',
title: t('Offen', 'Open', 'Abierto'),
items: [
{
id: 'brief',
title: t('Angebot vorbereiten', 'Prepare quote', 'Preparar oferta'),
tag: t('Heute', 'Today', 'Hoy'),
color: '#d97706',
},
],
},
{
id: 'done',
title: t('Erledigt', 'Done', 'Hecho'),
items: [] as { id: string; title: string; tag: string; color: string }[],
},
];
export default function Example() {
const [lanes, setLanes] = useState(startLanes);
const [selected, setSelected] = useState(
t(
'Karte ziehen oder anklicken',
'Drag or click a card',
'Arrastra o pulsa una tarjeta',
),
);
return (
<>
({
...lane,
items: lane.items.map((item) => ({
id: item.id,
title: item.title,
subtitle: (
),
clickable: true,
draggable: true,
borderPosition: 'left',
borderColor: item.color,
borderWidth: '4px',
})),
})),
}}
onItemClick={(_event, { item_index }) =>
setSelected(`${t('Aufgabe', 'Task', 'Tarea')} ${item_index + 1}`)
}
onItemDrop={async (payload) => {
const next = lanes.map((lane) => ({
...lane,
items: [...lane.items],
}));
const [item] = next[payload.source_swimlane_index].items.splice(
payload.item_index_in_section,
1,
);
next[payload.target_swimlane_index].items.splice(
payload.target_index_in_section,
0,
item,
);
setLanes(next);
setSelected(t('Karte verschoben', 'Card moved', 'Tarjeta movida'));
}}
/>
{selected}
);
}
```
## Daten und Events
`data` enthält die widgetspezifische Konfiguration. Importiere bei Bedarf den zugehörigen Datentyp aus demselben Paket, etwa `ArcWidgetKanbanData`. `id` auf der Komponente ist optional und identifiziert die Widget-Instanz.
Callbacks liegen auf der Komponente. Beim Kanban meldet `onItemClick` ein Browser-Event und die Position der Karte. Für mehrere Spalten oder Gruppen nutzt du alle passenden Indizes des Payloads. Der allgemeine Fallback ist `onAction(type, ...args)`; ein konkreter Callback hat Vorrang.
Datenzugriff, Speicherung, Navigation und Fehlerbehandlung liegen in deiner Anwendung. Unterstützte Inhaltsslots erlauben JSX, sodass du eigene Komponenten und weitere Widgets kombinieren kannst.
## Vollständige Beispiele und KI-Kontext
Das Paket enthält die Quellen aller Widget- und Anwendungsbeispiele unter `examples/docs/`. Jede Datei exportiert eine vollständige React-Komponente.
Der Markdown-Link einer React-Seite liefert denselben React-Inhalt. Für KI-Assistenten gibt es den [React-Index](/docs/react/llms.txt) und den [vollständigen React-Export](/docs/react/llms-full.txt).
## Weiter
- [Alle 22 Komponenten](/docs/react/intro/react-components)
- [State und Events](/docs/react/patterns/react-state-events)
- [JSX und verschachtelte Widgets](/docs/react/patterns/nested-widget-descriptors)
- [Dashboard-Vorlage](/docs/react/templates/react-starter)
- [Server Rendering und Fehlerbehebung](/docs/react/faq/react-troubleshooting)
- [Paket und Lizenzierung](/docs/react/faq/react-paket-und-lizenzierung)
---
# Vue einrichten
Source: https://www.arc-rider.com/docs/intro/setup-vue
# Vue einrichten
Arc Rider Widgets bieten einen Vue 3 Support als direktes npm-Paket. Die deklarative Widget-Konfiguration (`data`-Objekt) wird als Prop an die Komponente übergeben, während Events sauber als Emits zurückkommen.
## Paket
```bash
npm install @arcrider/arcwidgets-vue
```
Das öffentliche Vue-Paket exportiert dieselben Widgets und folgt der standardisierten Arc Rider API.
## Erstes Widget
```vue
```
Stabile IDs (`id` auf der Komponente und `uniqueListId` / Zeilen-`id` im Objekt) sind Pflicht — sonst triggert die Engine einen vollen Re-Render.
## Weiter
- [Custom Table](/docs/widgets/custom-table) — Parameter-Referenz und Beispiele
- [Custom Layout](/docs/widgets/custom-layout)
- [Button](/docs/mini-widgets/buttons)
---
# Widget-Integration in deine Datenbank
Source: https://www.arc-rider.com/docs/intro/aufbau-in-nx-db
# Widget-Integration in deine Ninox-Datenbank
Damit ein arcWidget in deiner Datenbank funktioniert, sind zwei Elemente wichtig:
1. Ein **Global Code** – die technische Basis des Widgets (einmalig pro Ninox-Team)
2. Ein **Anwendungscode** – deine individuelle Konfiguration im Ninox-Funktionsfeld
---
## 1. Was ist der Global Code / Widget Code?
Der **Global Code** bildet das technische Fundament für deine Widgets. Er enthält die Kernfunktionen, die globale Steuerung und die Programmlogik, die die Widgets zum Leben erweckt.
Du musst diesen Code **nur einmal pro Ninox-Team** in den globalen Funktionen hinterlegen. So gehst du vor:
1. Öffne deine Ninox-Datenbank.
2. Klicke im Admin-Modus auf die **drei Punkte** (Zahnrad) neben dem Datenbanknamen.
3. Wähle **„Optionen“ > „Globale Funktionen“**.
4. Kopiere den **Build-Code aus deinem Universe-Projekt** und füge ihn ganz unten ein.
Der Global Code **ist** dieser Build: ein Paket mit allen Widgets des Projekts, einmal pro Ninox-Team.
💡 **Wichtig:** Ohne diesen Global Code können die Formelfelder das Widget nicht laden. Was ein Build ist und wie Updates laufen: [Ninox Builds einbauen und aktualisieren](/docs/faq/wie-man-builds-einbaut-und-updatet).
---
## 2. Was ist der Anwendungscode?
Der **Anwendungscode** ist deine Konfiguration, mit der du das Widget **in deiner Datenbank anzeigst und steuerst**. Diesen Code fügst du in ein normales **Ninox-Funktionsfeld** (Formelfeld) ein – genau dort, wo die Oberfläche erscheinen soll.
Im Anwendungscode bestimmst du:
- Welche Tabellen-Daten das Widget laden soll.
- Welche Filter, Farben, Abstände oder Optionen gelten.
- Wie das Widget auf Klicks und Änderungen reagiert (Event-Routing).
Du steuerst also über einfache Formel-Parameter, wie sich das Widget im konkreten Kontext verhält, während die Engine im Hintergrund das Zeichnen und die Performance übernimmt.
---
# React-Komponenten
Source: https://www.arc-rider.com/docs/intro/react-components
# React-Komponenten
Diese Komponenten sind in [@arcrider/arcwidgets-react auf npm](https://www.npmjs.com/package/@arcrider/arcwidgets-react), Version `0.1.0-alpha.5`, enthalten. Importiere sie direkt aus dem Paket. Styles und TypeScript-Typen werden mitgeliefert.
Neu hier? Beginne mit [Installation und erstem Widget](/docs/react/intro/setup-react).
## Business-Widgets
- `ArcWidgetTable` — [Table](/docs/react/widgets/custom-table)
- `ArcWidgetKanban` — [Kanban](/docs/react/widgets/custom-kanban)
- `ArcWidgetCalendarWeek` — [Calendar Week](/docs/react/widgets/custom-calendar-week)
- `ArcWidgetCalendarGrid` — [Calendar Grid](/docs/react/widgets/custom-calendar-grid)
- `ArcWidgetCalendarTimeline` — [Calendar Timeline](/docs/react/widgets/custom-calendar-timeline)
- `ArcWidgetDrawing` — [Drawing](/docs/react/widgets/custom-drawing)
- `ArcWidgetUpload` — [Upload](/docs/react/widgets/custom-upload)
- `ArcWidgetSlideshow` — [Slideshow](/docs/react/widgets/custom-slideshow)
## Mini-Widgets
- `ArcWidgetBadge` — [Badge](/docs/react/mini-widgets/badges)
- `ArcWidgetButton` — [Button](/docs/react/mini-widgets/buttons)
- `ArcWidgetDevTools` — [DevTools](/docs/react/widgets/custom-dev-tools)
- `ArcWidgetIcon` — [Icon](/docs/react/mini-widgets/custom-icon)
- `ArcWidgetInput` — [Input](/docs/react/mini-widgets/input)
- `ArcWidgetKpiBar` — [KPI Bar](/docs/react/widgets/custom-kpi-bar)
- `ArcWidgetLayout` — [Layout](/docs/react/widgets/custom-layout)
- `ArcWidgetNumpad` — [Numpad](/docs/react/widgets/custom-numpad)
- `ArcWidgetProgressBar` — [Progress Bar](/docs/react/mini-widgets/progress-bar)
- `ArcWidgetSelect` — [Select](/docs/react/mini-widgets/select)
- `ArcWidgetSignature` — [Signature](/docs/react/mini-widgets/signature)
- `ArcWidgetSlider` — [Slider](/docs/react/widgets/custom-slider)
- `ArcWidgetSteps` — [Steps](/docs/react/widgets/custom-steps)
- `ArcWidgetText` — [Text](/docs/react/mini-widgets/text)
## Konfiguration und Events
Jedes Widget hat ein eigenes `data`-Format und einen passenden TypeScript-Typ. Eine Tabelle verwendet `table`, ein Kanban-Board `swimlanes`. Verwende die mit deiner Paketversion ausgelieferten Typen zur Prüfung deiner Konfiguration.
Callback-Props verbinden Interaktionen mit deiner Anwendung. Beim Kanban sind das beispielsweise `onItemClick` und `onItemDrop`. Der allgemeine Fallback lautet `onAction(type, ...args)`; das erste Argument ist der Event-Name, kein Action-Objekt.
Die React-Referenzen enthalten vollständige Beispiele, Parameter, Callback-Signaturen und bekannte Grenzen. Datenzugriff und Speichern implementierst du mit deinem React-State und deiner API. Quellen aller Beispiele liegen im Paket unter `examples/docs/`.
## Lizenz und Updates
Mini-Widgets sind im Rahmen der Nutzungsbedingungen auch produktiv kostenlos. Premium-Widgets kannst du für Entwicklung und Evaluation nutzen; für den produktiven Einsatz benötigst du eine Projektlizenz. Details: [React-Paket und Lizenzierung](/docs/react/faq/react-paket-und-lizenzierung).
Der Release ist eine Alpha. Prüfe bei Updates die Typen, Callback-Namen und deine eigenen Workflows.
---
# Das Universe Portal
Source: https://www.arc-rider.com/docs/intro/user-cockpit
# Das Universe Portal
Das **Universe Portal** ist die Schaltzentrale für deine Arc-Rider-Projekte. Anmeldung: [universe.arc-rider.com](https://www.arc-rider.com/).
Im Portal verwaltest du:
- **Projekte:** Getrennte Projekte für Kunden oder eigene Apps — Lizenz, Build und Umgebungen bleiben sauber getrennt.
- **Widgets & Builds:** Katalog zusammenstellen. Universe bündelt das in **einen** Code-Build für dein Ninox-Team.
- **Lizenzen:** Free (Mini-Widgets) oder Ultimate (alle Premium-Widgets, einmalig).
- **Umgebungen:** Private-Cloud-URL, On-Premise-URL oder Public-Cloud-**Team-ID**. Nur hinterlegte Produktions-Umgebungen laufen ohne Lizenzhinweis.
## Wo finde ich den Widget-Code?
In der Projekt-Detailansicht liegen die Builds. Code kopieren oder als Datei laden, dann in Ninox einfügen.
Weiter: [Widget-Integration in deine Datenbank](/docs/intro/aufbau-in-nx-db).
Im Portal verwaltest du:
- **Projekte:** Eines pro React-App — Lizenz und Produktions-Domains bleiben getrennt.
- **Lizenzen:** Free für Mini-Widgets oder eine Ultimate-Projektlizenz für die produktive Nutzung der Premium-Widgets. Details stehen unter [Preise](/docs/react/faq/wie-sich-preise-zusammensetzen).
- **Produktions-Domains:** Die Domain-Zuordnung deines Projekts. Die technische Aktivierung des npm-Pakets ist im aktuellen Alpha-Stand ein zusätzlicher Schritt und wird nicht automatisch aus dem Portal übernommen. Prüfe auch öffentlich erreichbare Test-Domains.
Die Komponenten, Styles und Typen installierst du über das React-npm-Paket. Lokale Entwicklung auf `localhost` oder `127.0.0.1` zeigt keinen Lizenzhinweis.
Weiter: [React einrichten](/docs/react/intro/setup-react) · [Paket und technische Aktivierung](/docs/react/faq/react-paket-und-lizenzierung).
Im Portal verwaltest du:
- **Projekte:** Eines pro Vue-App — Lizenz und Produktions-Domains bleiben getrennt.
- **Lizenzen:** Free oder Ultimate, wie bei React.
- **Produktions-Domains:** Nur hinterlegte Live-Domains laufen ohne Lizenzhinweis.
Die Widgets kommen über `npm install @arcrider/arcwidgets-vue`.
Weiter: [Vue einrichten](/docs/intro/setup-vue).
---
# ADK Setup Guide
Source: https://www.arc-rider.com/docs/intro/adk-setup-guide
# ADK Setup Guide
## Dein AI-Editor kennt ab jetzt deine Ninox-Datenbank – Setup in 10 Minuten
Du baust Ninox-Oberflächen mit Arc Rider Widgets und wünschst dir, dass dir jemand beim Code schreiben hilft? Jemand, der deine Datenbank kennt, die richtige Syntax beherrscht und weiß, wie die Widgets funktionieren?
Genau das macht das Arc Rider Developer Kit (ADK). Es verbindet einen AI-Editor mit deiner Ninox-Datenbank und unserer Widget-Dokumentation. Du beschreibst auf Deutsch, was du willst – die AI schreibt den Code.
Keine Programmierkenntnisse nötig. Kein Terminal-Wissen vorausgesetzt. In diesem Guide gehen wir jeden Schritt gemeinsam durch. Der Weg hier ist Cursor. Dieselben Befehle gelten für Claude Code.
## Was du am Ende hast
Nach diesem Guide hast du auf deinem Computer einen Projektordner mit allem, was die AI braucht:
```text
mein-ninox-projekt/
├── .cursor/rules/ ← Regeln für die AI (NinoxScript-Syntax, Widget-Properties)
├── docs/ ← Widget-Dokumentation (Referenz für die AI)
├── ninox/ ← Dein Datenbankschema (Tabellen, Felder, Relationen)
├── spaces/ ← Hier landen deine Widget-Konfigurationen (.arc-Dateien)
└── package.json
```
Die AI liest diese Dateien automatisch im Hintergrund. Du beschreibst, was du bauen willst, und die AI nutzt den Kontext.
## Voraussetzungen
Bevor du loslegst, brauchst du:
- Ninox-Account mit aktiven Arc Rider Widgets – [Widgets bestellen](/widgets)
- [Node.js](https://nodejs.org) (Version 18+) – einmal installieren, danach läuft es im Hintergrund. Nimm die LTS-Version.
## Schritt 1: Cursor installieren
[Cursor](https://cursor.com) ist ein Code-Editor mit eingebauter AI. Du beschreibst, was du willst – die AI schreibt den Code.
- Die Dateien bleiben auf deinem Rechner.
- Liegt dein Ninox-Schema lokal, kennt die AI deine Tabellen und Felder.
- Die kostenlose Version reicht für den Einstieg.
So installierst du Cursor:
1. Gehe zu [cursor.com](https://cursor.com).
2. Lade die Version für dein Betriebssystem herunter.
3. Installiere das Programm.
4. Erstelle einen kostenlosen Account.
## Schritt 2: Projektordner anlegen
Erstelle einen neuen, leeren Ordner, zum Beispiel `mein-ninox-projekt`. Auf dem Mac eignet sich der Ordner `Sites`.
Öffne den Ordner in Cursor: **File → Open Folder**, oder ziehe den Ordner ins Fenster.
## Schritt 3: ADK installieren
Öffne das Terminal in Cursor (**Terminal → New Terminal**, oder `Ctrl` + `` ` ``).
```bash
npm install @arcrider/developer-kit
npx arc-rider-init
```
`npm install` lädt das ADK. Darin stecken die Widget-Dokumentation, die AI-Regeln und das Ninox-Werkzeug für dein Datenbankschema. Ein zweites Paket brauchst du nicht.
`arc-rider-init` legt danach die Projektstruktur an:
- `.cursor/rules/` – AI-Regeln für NinoxScript und Widget-Properties
- `docs/` – die Widget-Referenz
- `ninox/` – hier landet gleich dein Datenbankschema
- `spaces/` – hier landen deine Widget-Konfigurationen, zum Beispiel `spaces/dashboard/main.arc`
Danach siehst du die neuen Ordner in der Sidebar.
## Schritt 4: Ninox-Zugangsdaten eintragen
### API-Key erstellen
1. Öffne deine Ninox-Instanz im Browser.
2. Klicke oben rechts auf dein Profil-Icon.
3. Gehe zu **Einstellungen → API Keys**.
4. Erstelle einen neuen API-Key und kopiere ihn.
API-Keys geben vollen Zugriff auf deine Ninox-Daten. Teile sie nicht öffentlich. Die `config.yaml` bleibt lokal und wird nicht ins Git committed.
### Domain, Workspace-ID und Datenbank-ID
Die IDs stehen in der Browser-URL, wenn du die Datenbank öffnest.
**Public Cloud** (`app.ninox.com`):
- Beispiel: `https://app.ninox.com/#/teams/Xk7mNpQr2sT4wYz/database/a9b3c7d2e1f/`
- Workspace-ID: der Teil nach `teams/`
- Datenbank-ID: der Teil nach `database/`
- Domain in der Config: immer `https://api.ninox.com` (nicht `app.ninox.com`)
**Private Cloud:**
- Beispiel: `https://meinefirma.ninoxdb.com/#/teams/abc123/database/xyz789/`
- Domain: deine API-URL, zum Beispiel `https://meinefirma.ninoxdb.com`
- Workspace-ID und Datenbank-ID wie oben aus der URL
### Konfigurationsdatei
`arc-rider-init` hat `ninox/config.yaml` schon angelegt. Trage deine Daten unter `environments.dev` ein:
```yaml
environments:
dev:
domain: https://api.ninox.com
apiKey: dein-api-key
workspaceId: DEINE_WORKSPACE_ID
databases:
- id: "DEINE_DATENBANK_ID"
name: "Mein Projekt"
```
In der Browser-URL siehst du `app.ninox.com`. Das ist nur die Oberfläche. Für die API nimmst du `https://api.ninox.com`.
## Schritt 5: Datenbankschema laden
```bash
npm run ninox:download
```
Bei mehreren Datenbanken in der Config erscheint eine Auswahl. Bei einer Datenbank wird sie automatisch genommen. Optional: `--db=DEINE_DB_ID`.
Danach liegt unter `ninox/src/Objects/` für jede Tabelle eine Datei mit Feldern, Typen und Relationen. Die AI kennt ab dann die echten Namen aus deiner Datenbank.
## Dein erster Prompt
Öffne den Agent in Cursor (`Cmd+L` auf dem Mac, `Ctrl+L` unter Windows) und probiere zum Beispiel:
```text
Erstelle einen neuen Space "dashboard" und baue darin
ein Dashboard-Layout für die Tabelle "Aufträge".
Oben eine KPI-Bar mit: Anzahl offener Aufträge, Gesamtbetrag, Durchschnittsbetrag.
Darunter eine Tabelle mit den Spalten: Bezeichnung, Kunde, Betrag, Status als Badge.
```
Die AI legt `spaces/dashboard/main.arc` an. Jedes Feature bekommt einen eigenen Space. `shared/` ist für Farben, Schrift und Bausteine, die mehrere Spaces nutzen.
Die AI liest die Regeln, dein Schema und die Widget-Docs und schreibt den Code nach `spaces/`.
## Code in Ninox einfügen
1. Öffne `spaces/dashboard/main.arc`.
2. Kopiere den gesamten Code.
3. Füge ihn in Ninox in ein Funktionsfeld ein, dort wo das Widget erscheinen soll.
Wer das Terminal mag, kann den Code auch direkt schieben: Mapping in `ninox/ninox-mapping.yaml`, danach `npm run ninox:push`.
`ninox:upload` kann die Datenbankstruktur verändern. Für den normalen Widget-Workflow brauchst du das nicht. Es reichen `ninox:download` (lesen) und `ninox:push` (Code ins Formelfeld).
## Tipps für bessere Prompts
Nenne Tabellen und Felder:
```text
Nutze die Tabelle "Kontakte" und zeige
die Felder "Name", "E-Mail", "Telefon" und "Status".
```
Beschreibe das Design und ändere in kleinen Schritten nach:
```text
Füge der Tabelle eine Pagination mit 20 Einträgen pro Seite hinzu.
Die Spalte "Betrag" soll als formatierte Zahl mit € angezeigt werden.
```
## Häufige Fragen
**Muss ich programmieren können?**
Nein. Du beschreibst auf Deutsch, was du willst. Die AI schreibt den Code. Du fügst ihn in Ninox ein.
**Was ist npm?**
npm kommt mit Node.js. Es lädt Pakete herunter. Du brauchst es für die Einrichtung. Danach arbeitest du in Cursor.
**Brauche ich die kostenpflichtige Cursor-Version?**
Nein. Die kostenlose Version reicht für den Einstieg.
**Was, wenn sich mein Schema ändert?**
Führe `npm run ninox:download` erneut aus. Die AI kennt danach die neuen Felder.
**Geht das ohne Arc Rider Widgets?**
Nein. Ohne die Widgets fehlt der Global Code in Ninox, auf dem die Konfigurationen aufbauen. Du brauchst ein aktives Widget-Abo. Bestellen kannst du im [Widget Store](/widgets).
## Zusammenfassung
| Schritt | Was passiert | Dauer |
| --- | --- | --- |
| 1. Cursor installieren | AI-Editor herunterladen | 2 Min |
| 2. Ordner anlegen | Neuen Projektordner erstellen | 30 Sek |
| 3. ADK einrichten | Paket installieren und Struktur anlegen | 2 Min |
| 4. Zugangsdaten | API-Key, Domain, Workspace-ID | 3 Min |
| 5. Schema laden | Datenbankstruktur herunterladen | 1 Min |
| Erster Prompt | AI schreibt den Widget-Code | Sofort |
```bash
npm install @arcrider/developer-kit
npx arc-rider-init
npm run ninox:download
```
Dein AI-Editor kennt jetzt deine Datenbank, deine Widgets und die richtige Syntax.
---
# Component ProgressList
Source: https://www.arc-rider.com/docs/intro/component-progresslist
# Component ProgressList
```javascript
arcComponentProgressList({
items: [{
title: "Lagername",
valueTotal: 2000,
valueProgress: 100,
valueText: 100 + " / " + 2000
}, {
title: "Lagername 2",
valueTotal: 5000,
valueProgress: 2000,
valueText: 2000 + " / " + 5000
}]
})
```
```javascript
arcComponentProgressList({
items: list_Lager.[{
title: Lagername,
valueTotal: 'Lagerkapazität',
valueProgress: sum_lagerbestand,
valueText: sum_lagerbestand + " / " + 'Lagerkapazität'
}]
});
```
---
# Custom Calendar (Week)
Source: https://www.arc-rider.com/docs/widgets/custom-calendar-week
# CalendarWeek in React
Termine in einer Wochenansicht mit Stundenraster anzeigen. Das Beispiel hält Auswahl und Termine in der Anwendung.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetCalendarWeek } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const locale = lang === 'en' ? 'en-US' : lang === 'es' ? 'es-ES' : 'de-DE';
const day = (offset: number) => new Date(2026, 8, 14 + offset).getTime();
const hour = (value: number) => value * 3600000;
const chrome = {
backgroundColor: '#ffffff',
fontColor: '#18181b',
mutedColor: '#52525b',
borders: { color: '#e4e4e7', outer: true, columns: true, rows: true },
};
const look = (backgroundColor: string, color: string) => ({
backgroundColor,
color,
fontColor: color,
});
const teal = '#115e59';
const tealFill = '#ccfbf1';
const travelFill = '#99f6e4';
const pauseFill = '#f4f4f5';
const pauseInk = '#52525b';
type Entry = {
id: string;
title: string;
dateFrom: number;
dateTo: number;
timeFrom: number;
timeTo: number;
clickable: true;
draggable: true;
styles: ReturnType;
insetBorder: { enabled: true; color: string };
segments?: Array<{
title: string;
linked?: boolean;
dateFrom: number;
dateTo: number;
timeFrom: number;
timeTo: number;
styles: ReturnType;
insetBorder: { enabled: true; color: string };
splits?: Array<{
title: string;
timeFrom: number;
timeTo: number;
styles: ReturnType;
}>;
}>;
};
const event = (
id: string,
title: string,
offset: number,
from: number,
to: number,
backgroundColor: string,
color: string,
): Entry => ({
id,
title,
dateFrom: day(offset),
dateTo: day(offset),
timeFrom: hour(from),
timeTo: hour(to),
clickable: true,
draggable: true,
styles: look(backgroundColor, color),
insetBorder: { enabled: true, color },
});
const siteVisit = (): Entry => ({
id: 'visit',
title: t('Kundentermin', 'Site visit', 'Visita'),
dateFrom: day(3),
dateTo: day(3),
timeFrom: hour(11),
timeTo: hour(14),
clickable: true,
draggable: true,
styles: look(tealFill, teal),
insetBorder: { enabled: true, color: teal },
segments: [
{
title: t('Anfahrt', 'Travel there', 'Ida'),
linked: false,
dateFrom: day(2),
dateTo: day(2),
timeFrom: hour(16),
timeTo: hour(17),
styles: look(travelFill, teal),
insetBorder: { enabled: true, color: teal },
},
{
title: t('Hauptarbeit', 'On site', 'Trabajo principal'),
linked: true,
dateFrom: day(3),
dateTo: day(3),
timeFrom: hour(11),
timeTo: hour(14),
styles: look(tealFill, teal),
insetBorder: { enabled: true, color: teal },
splits: [
{
title: t('Pause', 'Break', 'Pausa'),
timeFrom: hour(12) + 30 * 60 * 1000,
timeTo: hour(13),
styles: look(pauseFill, pauseInk),
},
],
},
{
title: t('Abfahrt', 'Travel back', 'Vuelta'),
linked: false,
dateFrom: day(4),
dateTo: day(4),
timeFrom: hour(8),
timeTo: hour(9),
styles: look(travelFill, teal),
insetBorder: { enabled: true, color: teal },
},
],
});
const demoEntries: Entry[] = [
event(
'plan',
t('Planung', 'Planning', 'Planificación'),
0,
9,
10,
'#d1fae5',
'#065f46',
),
event(
'workshop',
t('Workshop', 'Workshop', 'Taller'),
1,
10,
12,
'#fef3c7',
'#92400e',
),
event(
'review',
t('Review', 'Review', 'Revisión'),
2,
14,
15,
'#ffe4e6',
'#9f1239',
),
siteVisit(),
];
const busyEntries: Entry[] = [
...demoEntries,
event(
'stand',
t('Standabnahme', 'Booth check', 'Revisión stand'),
4,
10,
12,
'#ede9fe',
'#5b21b6',
),
event('retro', t('Retro', 'Retro', 'Retro'), 4, 15, 16, '#e0f2fe', '#075985'),
];
export default function Example() {
const [entries, setEntries] = useState(
pack === 'empty' ? [] : pack === 'busy' ? busyEntries : demoEntries,
);
const [selected, setSelected] = useState(
t(
'Termin ziehen oder anklicken',
'Drag or click an event',
'Arrastra o pulsa un evento',
),
);
return (
<>
setSelected(
t('Termin ausgewählt', 'Event selected', 'Evento seleccionado'),
)
}
onDayClick={(date) =>
setSelected(new Date(date).toLocaleDateString(locale))
}
onEntryDragSave={(index, start) => {
setEntries((previous) => {
if (index >= previous.length || previous[index].segments)
return previous;
return previous.map((entry, i) =>
i === index
? {
...entry,
dateFrom: Number(start.dateFrom ?? entry.dateFrom),
dateTo: Number(start.dateTo ?? entry.dateTo),
timeFrom: Number(start.timeFrom ?? entry.timeFrom),
timeTo: Number(start.timeTo ?? entry.timeTo),
}
: entry,
);
});
setSelected(t('Termin verschoben', 'Event moved', 'Evento movido'));
}}
/>
{selected}
);
}
```
## Features ausprobieren
### Tagesansichten, Terminbearbeitung und JSX
Ein gemeinsamer State steuert die Zahl der Tage und den Terminbeginn. Die Bearbeitung nutzt bewusst den Regler, da Drag-Callbacks noch keine vollständigen Zielzeiten liefern.
```tsx
import { useState } from 'react';
import {
ArcWidgetCalendarWeek,
ArcWidgetBadge,
} from '@arcrider/arcwidgets-react';
export default function Example() {
const [days, setDays] = useState(7);
const [hour, setHour] = useState(10);
const [custom, setCustom] = useState(true);
const [selected, setSelected] = useState('Keine Auswahl');
return (
<>
Projektbesprechung
) : undefined,
dateFrom: new Date(2026, 8, 14).getTime(),
dateTo: new Date(2026, 8, 14).getTime(),
timeFrom: hour * 3600000,
timeTo: (hour + 1) * 3600000,
clickable: true,
draggable: false,
},
],
}}
onEntryClick={() => setSelected(`Termin um ${hour}:00`)}
onDayClick={(date) =>
setSelected(new Date(date).toLocaleDateString('de-DE'))
}
/>
{selected}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetCalendarWeekData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onEntryClick
Index des Termins, bei Timeline zusätzlich der Ressourcenzeile.
```typescript
onEntryClick?: (entry_index: number) => void;
```
### onDayClick
Datum des gewählten Tages als Millisekunden-Zeitstempel.
```typescript
onDayClick?: (date_millis: number) => void;
```
### onEntryDragSave
Drag-Ende mit ursprünglichen Daten. Keine vollständigen neuen Zielzeiten; siehe Hinweise zur Persistenz.
```typescript
onEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarWeekDragStart) => void;
```
### onDailyEntryDragSave
Drag-Ende eines ganztägigen Termins mit ursprünglichen Daten.
```typescript
onDailyEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarWeekDragStart) => void;
```
### onCreate
Neue Datum-/Zeitauswahl. Validieren und Speichern übernimmt die Anwendung.
```typescript
onCreate?: (values: {
dateFrom?: number;
dateTo?: number;
timeFrom?: number;
timeTo?: number;
[key: string]: unknown;
}) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### styles
Gemeinsame Farben, Abstände und Rahmen; die angebotenen Felder sind widgetspezifisch.
Typ: `ArcWidgetCalendarWeekStyles | string`.
### weekdaySettings
Auswahl einer Kalenderwoche und des Jahres.
Typ: `{ week?: number; year?: number; [key: string]: unknown }`.
### weekStart
Alternativer Wochenbeginn.
Typ: `unknown`.
### dateSettings
Datumsbereich, Kopfzeilen und Markierungen.
Typ: `ArcWidgetCalendarDateSettings`.
### timeZoneBalance
Korrektur in Stunden; die Beispiele verwenden `0` und lokal erzeugte Tageswerte.
Typ: `number | string`.
### timeSettings
Zeitbereich und Raster; Einheiten sind Millisekunden.
Typ: `ArcWidgetCalendarTimeSettings`.
### currentTime
Darstellung der aktuellen Zeit.
Typ: `string`.
### lang
Sprache der Kalenderbeschriftungen.
Typ: `string`.
### timeSlotWidth
Breite einer Tagesspalte.
Typ: `string`.
### timeSlotHeight
Höhe eines Zeitrasters.
Typ: `string`.
### allDayHeight
Höhe des Bereichs für ganztägige Termine.
Typ: `string`.
### createNew
Auswahl zum Erstellen neuer Termine. Speichern erfolgt über `onCreate`.
Typ: `ArcWidgetCalendarCreateNew`.
### timeEntries
Termine mit Datumswerten, Uhrzeiten und Inhalten.
Typ: `ArcWidgetCalendarTimeEntry[]`.
## Verhalten und Grenzen
- Für JSX in Terminen verwende `customLayout`. Die Standardfelder `title`, `subtitle` und `value` werden als Text oder HTML verarbeitet.
- Datumswerte sind Zeitstempel in Millisekunden; Uhrzeiten sind Millisekunden seit Tagesbeginn. Siehe [Datum und Zeit](/docs/react/patterns/react-dates).
- `clickable: true` aktiviert die Auswahl. Ein Callback-Index ist keine Datensatz-ID; löse ihn über deine aktuelle Eintragsliste auf.
- Die derzeitigen Drag-Callbacks enthalten den ursprünglichen Stand (`start_data`), jedoch keine vollständigen neuen Zielzeiten. Das Beispiel setzt deshalb `draggable: false`. Bearbeite Termine über React-State, bis ein vollständiger Persistenzvertrag für Drag & Drop vorliegt.
- Der sichtbare Uhrzeitbereich wird über `timeSettings.timeStart` und `timeSettings.duration` in Millisekunden konfiguriert. Die historischen Felder `from` und `to` haben hier keine Wirkung.
- `onCreate` liefert die Werte der Auswahl. Deine Anwendung validiert sie, vergibt eine ID und übernimmt den neuen Termin.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export type ArcWidgetCalendarWeekBorderLine = boolean | {
color?: string;
width?: string;
borderColor?: string;
borderWidth?: string;
borderSize?: string;
enabled?: boolean;
};
export interface ArcWidgetCalendarWeekBorders {
color?: string;
width?: string;
outer?: ArcWidgetCalendarWeekBorderLine;
columns?: ArcWidgetCalendarWeekBorderLine;
rows?: ArcWidgetCalendarWeekBorderLine;
}
export interface ArcWidgetCalendarWeekStyles extends ArcWidgetStyles {
borders?: ArcWidgetCalendarWeekBorders;
headerBackgroundColor?: string;
mutedColor?: string;
}
export interface ArcWidgetCalendarHighlight {
date?: unknown;
weekday?: number;
color?: string;
styles?: ArcWidgetCalendarWeekStyles | string;
[key: string]: unknown;
}
export interface ArcWidgetCalendarWeekDay {
clickable?: boolean;
[key: string]: unknown;
}
export interface ArcWidgetCalendarDateSettings {
startDate?: unknown;
endDate?: unknown;
duration?: number;
highlights?: ArcWidgetCalendarHighlight[];
day?: ArcWidgetCalendarWeekDay;
header?: {
days?: unknown;
months?: unknown;
weeks?: unknown;
[key: string]: unknown;
};
month?: number;
year?: number;
[key: string]: unknown;
}
export interface ArcWidgetCalendarTimeSettings {
from?: number;
to?: number;
timeStart?: number;
duration?: number;
[key: string]: unknown;
}
export interface ArcWidgetCalendarPlaceOffset {
days?: number;
time?: number;
}
export interface ArcWidgetCalendarPlaceSplit {
title?: string;
subtitle?: string;
value?: string;
styles?: ArcWidgetStyles | string;
timeFrom?: unknown;
timeTo?: unknown;
offset?: number;
duration?: number;
[key: string]: unknown;
}
export interface ArcWidgetCalendarPlaceSegment {
duration?: number;
linked?: boolean;
offset?: ArcWidgetCalendarPlaceOffset;
title?: string;
subtitle?: string;
value?: string;
customLayout?: ArcWidgetSlot;
styles?: ArcWidgetStyles | string;
insetBorder?: unknown;
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
splits?: ArcWidgetCalendarPlaceSplit[];
[key: string]: unknown;
}
export interface ArcWidgetCalendarPlaceItem {
active?: boolean;
offset?: ArcWidgetCalendarPlaceOffset;
splits?: ArcWidgetCalendarPlaceSplit[];
duration?: number;
title?: string;
subtitle?: string;
value?: string;
customLayout?: ArcWidgetSlot;
styles?: ArcWidgetStyles | string;
insetBorder?: unknown;
segments?: ArcWidgetCalendarPlaceSegment[];
[key: string]: unknown;
}
export interface ArcWidgetCalendarCreateNew {
item?: ArcWidgetCalendarPlaceItem | null;
[key: string]: unknown;
}
export interface ArcWidgetCalendarWeekDragStart {
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
}
export interface ArcWidgetCalendarTimeEntry {
id?: string | number;
title?: string;
subtitle?: string;
value?: string;
customLayout?: ArcWidgetSlot;
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
styles?: ArcWidgetStyles | string;
clickable?: boolean;
draggable?: boolean;
segments?: ArcWidgetCalendarPlaceSegment[];
tooltip?: {
value?: ArcWidgetSlot;
width?: string;
maxWidth?: string;
maxHeight?: string;
position?: string;
styles?: ArcWidgetStyles | string;
[key: string]: unknown;
};
[key: string]: unknown;
}
export interface ArcWidgetCalendarWeekData extends Omit {
height?: string;
styles?: ArcWidgetCalendarWeekStyles | string;
weekdaySettings?: { week?: number; year?: number; [key: string]: unknown };
weekStart?: unknown;
dateSettings?: ArcWidgetCalendarDateSettings;
timeZoneBalance?: number | string;
timeSettings?: ArcWidgetCalendarTimeSettings;
currentTime?: string;
lang?: string;
timeSlotWidth?: string;
timeSlotHeight?: string;
allDayHeight?: string;
createNew?: ArcWidgetCalendarCreateNew;
timeEntries?: ArcWidgetCalendarTimeEntry[];
}
export interface ArcWidgetCalendarWeekProps extends ArcReactWidgetProps {
onEntryClick?: (entry_index: number) => void;
onDayClick?: (date_millis: number) => void;
onEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarWeekDragStart) => void;
onDailyEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarWeekDragStart) => void;
onCreate?: (values: {
dateFrom?: number;
dateTo?: number;
timeFrom?: number;
timeTo?: number;
[key: string]: unknown;
}) => void;
}
```
## Einsatzbeispiele
- [Termine gestalten und bearbeiten](/docs/react/examples/individuelles-design-in-der-calendarweek)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Calendar (Week)
## AI Defaults (read first)
- **uniqueId**: Required, `"calendar-" + Nr`.
- **height**: Use `"100%"` when embedded in a layout.
- **timeZoneBalance**: Set `-1` for German timezone in `dateSettings`.
- **dateFrom/dateTo**: Must be actual date field values, not strings.
- **dragAction**: Requires `recordId: Nr` and field IDs via `fieldId(Nr, "Feldname")`. Optional `changeFieldValues` for extra field updates after a successful drag (cache/trigger fields).
- **createNew**: Needs `tableId` and field IDs via `fieldId(Nr, "Feldname")`. Optional `changeFieldValues` for extra fields on create. Optional `dataBag` after a successful create (same as Button create; `##newRecordId##`). Optional `item` for click-to-place (duration, clock, `offset: { days, time }`, `splits`, `linked`). `linked: false` + clock = satellite (does not pin the duration chain). Shift moves the whole ghost; release snaps satellites back. Create writes the same four date/time fields — overall span of the chain. Toggle with `item.active`. Empty selection: omit `item` (never `else ""`). Same-title pause: `splits`. Named leftover pieces (Teil 1 / Teil 2): three `segments`, not `splits`.
- **Persistence**: Drag/create go through the **Action Performer** (`type: "update"` / `type: "create"`). Ninox config (`dragAction` / `createNew`) is unchanged. React hosts: handle these via `onAction` — **no** global `database` stub.
- **timeSettings**: Omit for full 0–24h range. Set `from`/`to` in hours (integers) to restrict.
- **lang**: Set `lang: clientLang()` for localized weekdays/months.
# Custom Calendar (Week)
Mit dem Widget **Custom Calendar Week** bringst du eine leistungsstarke Kalenderansicht direkt in deine Ninox-Datenbank. Du kannst es nahtlos in beliebige Tabellen integrieren, flexibel gestalten und dynamisch mit deinen eigenen Daten befüllen. Ob Projektplanung, Ressourcenmanagement oder Terminübersicht – das Widget passt sich deinen Anforderungen an.
💡 **Was du mit Custom Calendar machen kannst:**
- **Individuelles Design:** Passe Farben, Icons und Layout an deinen Stil oder dein Branding an.
- **Flexible Einträge:** Gestalte die Darstellung deiner Termine, Aufgaben oder Ereignisse exakt so, wie du sie brauchst – mit beliebigen Feldern, Icons oder Tags.
- **Mehrtägige & ganztägige Events:** Plane übersichtlich und erkenne längere Zeiträume auf einen Blick.
- **Drag & Drop:** Verschiebe Termine direkt im Kalender – intuitiv und ohne Umwege.
- **Dynamische Filterung:** Zeige nur relevante Einträge an – per Ninox-Skript steuerbar.
- **Hervorhebung besonderer Tage:** Markiere Feiertage, Urlaub, Abwesenheiten oder individuelle Events.
- **Anpassbare Zeitachse:** Zeige nur die Stunden, die für deinen Anwendungsfall wichtig sind – z. B. 8–18 Uhr statt 0–24.
- **Integration aus mehreren Tabellen:** Verknüpfe Daten aus verschiedenen Quellen – ideal für verteilte Teams oder Projekte.
- **Offline-fähig:** Auch ohne Internet bleibt dein Kalender nutzbar.
📅 **Custom Calendar Week** macht deine Terminplanung in Ninox übersichtlicher, interaktiver und deutlich effizienter – perfekt für alle, die mehr aus ihrer Datenbank herausholen wollen.
## Anwendungscode
```javascript
let current := this;
arcCustomCalendarWeek({
uniqueId: "cal-39",
embedded: false,
weekdaySettings: {
week: 12,
year:2024
},
weekStart: "",
dateSettings: {
startDate: date(2025, 2, 2),
endDate: "",
duration: 7,
highlights: [{
date: date(2025, 2, 7),
color: "#F1B6CE"
}, {
weekday: 6,
color: "rgba(255,0,0,0.1)"
}, {
weekday: 7,
color: "rgba(255,0,0,0.1)"
}]
},
timeZoneBalance: "",
timeSettings: {
timeStart: time(6, 30),
duration: time(15, 0)
},
currentTime: "rgba(0,0,255,0.5)",
lang: clientLang(),
timeSlotWidth: "250px",
timeSlotHeight: "80px",
allDayHeight: "",
styles: {
backgroundColor: "rgba(0,0,255,0.01)"
},
createNew: {
tableId: "B",
dateFrom: "A",
timeFrom: "B",
dateTo: "C",
timeTo: "D",
changeFieldValues: [{
fieldId: fieldId(Nr, "CacheTrigger"),
value: now()
}]
},
timeEntries: (select 'Time Entries').[{
title: Kalendertitel,
subtitle: Description,
value: "",
customLayout: "",
dateFrom: 'Date From',
dateTo: 'Date To',
timeFrom: 'Time From',
timeTo: 'Time To',
styles: {
backgroundColor: color(Person),
color: "#fff",
borderRadius: "8px",
padding: "5px"
},
insetBorder: {
enabled: true,
stroke: "dotted"
},
dragAction: {
recordId: Nr,
dateFrom: "A",
timeFrom: "B",
dateTo: "C",
timeTo: "D",
changeFieldValues: [{
fieldId: fieldId(Nr, "CacheTrigger"),
value: now()
}]
},
clickAction: {
type: "popup",
recordId: Nr
},
segments: [{
title: "Anfahrt",
timeFrom: SegVon,
timeTo: SegBis,
dateFrom: 'Seg Date From',
dateTo: 'Seg Date To',
linked: false,
dragAction: {
recordId: Nr,
dateFrom: "E",
timeFrom: "F",
dateTo: "G",
timeTo: "H"
}
}]
}]
})
```
## Allgemeine Settings
### weekdaySettings– gezielte Steuerung der Kalenderwoche
Mit dem Parameter `**weekdaySettings**` kannst du genau festlegen, **welche Kalenderwoche aus welchem Jahr** im Kalender angezeigt werden soll.
In diesem Beispiel wird die **12. Kalenderwoche des Jahres 2025** angezeigt.
Statt feste Werte einzutragen, kannst du auch auf Ninox-Felder verweisen, um die Daten zu dynamisieren.
⚠️ **Wichtig: **Wenn sowohl `dateSettings` als auch `weekdaySettings` gesetzt sind, **haben **`dateSettings`** Vorrang** und überschreiben die Angaben aus `weekdaySettings`.
### dateSettings– Start, Dauer & Hervorhebung in der Wochenansicht
Mit der Parametergruppe `**dateSettings**` steuerst du, **wann dein Kalender beginnt, wie lange er angezeigt wird und welche Tage besonders hervorgehoben werden sollen**.
**Einzelne Parameter in dateSettings:**
- `**startDate**` *(Pflichtfeld)*
Definiert das Startdatum des Kalenders. Gib hier ein Datumsfeld an.
→ Kann dynamisch über Ninox-Felder gesteuert werden.
- `**endDate**` *(optional)*
Gibt das **Enddatum** des Kalenders an. Gib hier ein Datumsfeld an.
→ Hat Vorrang vor `duration`.
- `**duration**` *(optional)*
Bestimmt die **Anzahl der anzuzeigenden Tage** (Standard: 7).
→ Wird nur berücksichtigt, wenn `endDate` nicht gesetzt ist.
**Logik der Anzeige-Dauer:**
- Nur `startDate` gesetzt → zeigt **7 Tage** ab Startdatum
- `startDate` + `duration` → zeigt die definierte **Anzahl an Tagen**
- `startDate` + `endDate` → `**duration**`** wird ignoriert**
- `**highlights**` *(optional)*
Erlaubt das **farbliche Hervorheben bestimmter Tage** – ideal für Urlaube, Feiertage oder andere besondere Anlässe.
→ Du kannst sowohl **konkrete Daten** als auch **Wochentage** markieren (Details siehe unten).
- `**header**` *(optional)*
Steuert die Darstellung der Tagesköpfe (Wochentag, Datum). Ohne Angabe werden Standard-Labels verwendet.
```javascript
header: {
backgroundColor: "#F8FAFC",
title: {
label: "##weekDayShort##. ##day##.",
fontSize: "15px",
fontColor: "#000",
alignX: "center"
},
subtitle: {
label: "##weekdayName##",
fontSize: "12px",
fontColor: "#666"
}
}
```
**Platzhalter für label:** `##date##`, `##weekdayName##`, `##weekDayLong##`, `##weekDayShort##`, `##day##`, `##month##`, `##monthLong##`, `##monthShort##`, `##year##`
📌 **Hinweis:** `subtitle` ist optional. Wenn du nur `title` angibst (ohne `subtitle`), wird die zweite Zeile nicht angezeigt – der Titel erhält den vollen Platz.
- `**day**` *(optional)*
Steuert Aktionen beim Klick auf einen Tag (z. B. Datum auswählen, View wechseln).
```javascript
day: {
actions: [{
type: "update",
recordId: Nr,
field: fieldId(Nr, "helper_selectedDate"),
value: "##clickedDate##"
}]
}
```
**Platzhalter:** `##clickedDate##` wird durch den Millisekunden-Timestamp des geklickten Datums ersetzt (z. B. `1731369600000`).
```javascript
dateSettings: {
startDate: "",
endDate: "",
duration: 14,
highlights: [{
date: date(2024, 10, 31),
color: 'Color Highlights'
}, {
weekday: 6,
color: "rgba(255,0,0,0.1)"
}, {
weekday: 7,
color: "rgba(255,0,0,0.1)"
}]
}
```
### weekStart – Starttag der Kalenderwoche festlegen
Mit dem Parameter `**weekStart**` bestimmst du, **an welchem Wochentag dein Kalender beginnen soll**.
📌 **Typ:** Zahl (0–6)
📅 **Werte:**
- `0` = Sonntag *(z. B. in den USA üblich)*
- `1` = Montag *(Standard in Mitteleuropa)*
- `2` = Dienstag
- ...
- `6` = Samstag
💡 **Tipp: **Für die meisten Nutzer im deutschsprachigen Raum ist `1` (Montag) die passende Wahl.
```javascript
weekStart: 1,
```
### timeZoneBalance – manuelle Zeitzonenkorrektur für präzise Anzeige
**Typ:** Zahl (in Stunden)
Der Parameter `**timeZoneBalance**` hilft dir dabei, **Zeitzonenunterschiede auszugleichen**, die durch die Darstellung in Ninox entstehen können.
Hintergrund**: **Ninox verwendet intern eine andere Zeitzonen-Logik, was zu einer Verschiebung der Zeiten im Kalender führen kann.
Empfehlung für Deutschland: Setze den Wert auf `-1`, um die Anzeige an die mitteleuropäische Zeit (MEZ/MESZ) anzupassen.
```javascript
timeZoneBalance: -1,
timeZoneBalance: "" // default: Zeiten werden wie in Ninox gespeichert angezeigt, die Nutzer-Zeitzone wird nicht beachtet.
```
### timeSettings – individuelle Steuerung der Zeitachse
Mit der Parametergruppe `**timeSettings**` kannst du festlegen, **welcher Zeitraum pro Tag im Kalender angezeigt werden soll**. So lässt sich die Kalenderansicht besser an deinen Anwendungsfall anpassen – z. B. für typische Bürozeiten oder Schichtmodelle.
```javascript
timeSettings: {
timeStart: time(6, 30), // Zeitfeld oder Milisekunden
duration: time(6, 30), // Duration in Milisekunden angeben. hier: 8 Stunden
},
```
In diesem Beispiel startet der Kalender-Tag um **06:00 Uhr** und endet um **22:00 Uhr**.
🧠 **Wichtig zu wissen:**
- Es werden **nur volle Stunden** unterstützt.
- Gibt man z. B. `6.5` (für 06:30 Uhr) an, **rundet das System auf 06:00 Uhr** ab.
- Der Standardbereich ohne eigene Konfiguration ist **0–24 Uhr** (also ein kompletter Tag).
💡 **Tipp: **Weniger sichtbare Stunden = kompaktere Darstellung = bessere Übersicht bei vielen Einträgen.
### currentTime – farbliche Markierung der aktuellen Uhrzeit
Der Parameter `**currentTime**` steuert die Darstellung eines schmalen Balkens, der dir **die aktuelle Uhrzeit im Kalender anzeigt** – ähnlich wie in bekannten Kalender-Apps.
🎨 Funktion: Mit diesem Parameter legst du die Farbe des Balkens fest, der die aktuelle Position im Tagesverlauf markiert.
```javascript
currentTime: "rgba(0,0,255,0.5)", // RGB Codes
currentTime: "#f95757" // HEX Codes
```
### lang
Diese Funktion wird standardmäßig eingestellt und muss nicht angepasst werden.
```javascript
lang: clientLang(),
```
### timeSlotWidth – Breite der einzelnen Wochentage
Mit dem Parameter `**timeSlotWidth**` legst du fest, **wie breit die einzelnen Tages-Spalten im Wochenkalender dargestellt werden**.
`timeSlotWidth: "250px" ,`
→ Jeder Wochentag wird mit **250 Pixeln Breite** angezeigt.
📌 **Hinweis:**
- Der Standardwert liegt bei ca. **100 px**, kann aber je nach Layout-Anforderungen angepasst werden.
- Eine höhere Zahl sorgt für **mehr Platz pro Tag**, besonders hilfreich bei vielen Einträgen.
### timeSlotHeight – Höhe der Stundenzeilen festlegen
Mit dem Parameter `**timeSlotHeight**` bestimmst du, **wie hoch jede einzelne Stunde im Kalender dargestellt wird**.
`timeSlotHeight: "80px",`
→ Jede Stunde erhält eine **Höhe von 50 Pixeln** in der vertikalen Zeitachse.
📌 **Hinweis:**
- Der Standardwert liegt bei etwa **40 px**.
- Ein höherer Wert sorgt für **mehr Raum pro Stunde.**
### allDayHeight – Höhe der Zeile für Ganztagseinträge
Mit dem Parameter `allDayHeight` legst du fest, wie hoch die obere Zeile für Ganztagseinträge dargestellt wird.
→ Die Zeile für Ganztagseinträge wird mit 60 Pixeln Höhe angezeigt.
📌 Hinweis:
- Standardmäßig liegt die Höhe bei ca. 40 px.
- Ein höherer Wert schafft mehr Platz für mehrere Ganztagseinträge oder größere Textdarstellungen.
### styles – individuelles Styling für deinen Kalender
Mit `**styles**` kannst du das **Aussehen deines Kalenders anpassen** – hier kannst du aktuell die Hintergrundfarbe deines Kalenders individualisieren.
### createNew – neue Termine durch Ziehen erstellen
Mit dem Parameter `**createNew**` aktivierst du die Möglichkeit, **neue Termine direkt durch Aufziehen eines Zeitbereichs im Kalender zu erstellen**.
🖱️ **So funktioniert’s:**
- Du klickst in einen freien Bereich des Kalenders, **ziehst mit gedrückter Maustaste**, und lässt wieder los.
- Dabei wird automatisch ein neuer Termin erstellt – inklusive **Startzeit und Dauer**.
📌 **Hinweis:**
- Alle Feldbezüge (`dateFrom`, `dateTo`, `timeFrom`, `timeTo`) müssen mit den **Field IDs** der entsprechenden Felder aus deiner **Kalendereintrags-Tabelle (**`**tableId**`**)** übereinstimmen.
- Du kannst die Field IDs ganz einfach mit der Ninox-Funktion `fieldId()` herausfinden und direkt in die Konfiguration übernehmen.
**💡 **Tipp: Ideal für eine schnelle und intuitive Terminplanung – z. B. bei Schichten, Buchungen oder Raumvergabe.
Optional kannst du mit **`changeFieldValues`** Zusatzfelder im neuen Datensatz setzen – z. B. Cache- oder Trigger-Felder:
```javascript
createNew: {
tableId: "B",
dateFrom: fieldId(Nr, "Datum von"),
timeFrom: fieldId(Nr, "Von"),
dateTo: fieldId(Nr, "Datum bis"),
timeTo: fieldId(Nr, "Bis"),
changeFieldValues: [{
fieldId: fieldId(Nr, "CacheTrigger"),
value: now()
}]
}
```
Optional **`dataBag`**: nach erfolgreichem Anlegen denselben JSON-State-Topf patchen wie bei Button-Create. Läuft nur, wenn der Datensatz wirklich angelegt wurde. `##newRecordId##` wird durch die ID des neuen Termins ersetzt. Typisch: Auswahl leeren, damit der Ghost verschwindet.
```javascript
createNew: {
tableId: "B",
dateFrom: fieldId(Nr, "Datum von"),
timeFrom: fieldId(Nr, "Von"),
dateTo: fieldId(Nr, "Datum bis"),
timeTo: fieldId(Nr, "Bis"),
item: if Auswahl then {
/* Ghost */
},
dataBag: {
recordId: Nr,
fieldId: fieldId(Nr, "helper_uiState"),
base: helper_uiState,
patch: { auswahlId: null }
}
}
```
`null` im Patch löscht den Key. Die neue Termin-ID mit ablegen: `patch: { auswahlId: null, lastTerminId: "##newRecordId##" }`. Syntax: [`data-bag-actions`](../patterns/data-bag-actions.md).
📌 **Persistenz / React:** Create läuft über `{ type: "create", tableId, changeFieldValues, setNewRecordId?, dataBag?, popup?, fullscreen? }`. React: dieselbe Action über `onAction` verarbeiten.
### createNew.item – vorgebauten Termin per Klick setzen
Mit **`createNew.item`** legst du einen **fertigen Termin** in den Kalender, statt einen Zeitraum aufzuziehen. Typischer Fall: Auswahl in einer Seitenleiste (Typ, Dauer, Phasen) schreibt ins Formelfeld — der Kalender zeigt einen **Ghost**, der der Maus folgt. Ein Klick setzt ihn.
Ohne `item` bleibt das heutige Aufziehen. Mit `item` (und gesetzter `duration` oder Segment-Dauern) ist Aufziehen aus — außer **`active`** ist `false`.
Den Platzieren-Modus schaltest du **außerhalb** des Kalenders: ein Ja/Nein-Feld, eine Checkbox in der Seitenleiste oder die Auswahl selbst.
```javascript
createNew: {
tableId: "B",
dateFrom: fieldId(first(Termine), "Datum von"),
timeFrom: fieldId(first(Termine), "Von"),
dateTo: fieldId(first(Termine), "Datum bis"),
timeTo: fieldId(first(Termine), "Bis"),
changeFieldValues: if Auswahl then [{
fieldId: fieldId(first(Termine), "Typ"),
value: number(Auswahl)
}] else [{
fieldId: fieldId(first(Termine), "CacheTrigger"),
value: now()
}],
item: if Auswahl then {
active: Platzieren,
title: Auswahl.Name,
styles: {
backgroundColor: color(Auswahl),
color: "#fff",
borderRadius: "8px"
},
segments: [{
title: "Anfahrt",
linked: false,
offset: { days: -1 },
timeFrom: time(16, 0),
timeTo: time(17, 0)
}, {
title: "Kernarbeit",
timeFrom: time(11, 0),
timeTo: time(14, 0),
splits: [{
title: "Pause",
timeFrom: time(12, 30),
timeTo: time(13, 0)
}]
}, {
title: "Abfahrt",
linked: false,
offset: { days: 1 },
timeFrom: time(8, 0),
timeTo: time(9, 0)
}]
}
}
```
**Felder in `item`:**
- **`active`** — optional. `true` oder weggelassen: Ghost an, Klick setzt. `false` / leer: Ghost aus, Aufziehen wieder an. Bindet an ein Feld außerhalb des Widgets (z. B. `Platzieren`).
- **`duration`** — relative Länge. Reine Duration-Phasen hängen sich an die vorherige Follow-Phase (erste: an die Maus).
- **`timeFrom` / `timeTo`** — Uhr auf dem Anker-Tag (Tag unter der Maus). Pinnt **diese** Phase. Mit `linked: false` bleibt sie Satellit — der Follow-Strang folgt weiter der Maus. Ohne `linked: false` hängt die Kette an dieser Uhr.
- **`linked`** — wie bei gespeicherten Segmenten. `false` = Satellit (Anfahrt/Abfahrt). Standard `true`.
- **`offset`** — `{ days, time }`, beide optional und signed. `days: -1` Vortag, `days: 1` Folgetag. `time: -time(1, 0)` eine Stunde früher (Maus / vorige Phase). Kombinierbar: `{ days: -1, time: -time(1, 0) }`. Mit fester Uhr wählt `days` den Kalendertag; `time` schiebt die Uhr mit. `days: 0` hält die Phase auf dem Anker-Tag, wenn die Phase davor auf einem anderen Tag lag. Nicht verwechseln mit dem flachen `offset: time(…)` in **`splits`**.
- **`dateFrom` / `dateTo`** — echte Datumswerte (wie bei `timeEntries`), wenn die Phase fest auf einem Kalendertag liegt.
- **`splits`** — eine Ebene Unterbrechungen in dieser Phase (typisch Pause). Beide Kern-Stücke behalten den Phasen-Titel. Siehe unten.
- **`title` / `subtitle` / `value` / `customLayout` / `styles` / `insetBorder`** — wie ein `timeEntry`.
Auflösung pro Phase, erste passende Regel: festes Datum + Uhr → Uhr (`timeFrom`/`timeTo`, optional `offset.days` / `offset.time`) → `offset` + `duration` → nur `duration`. `linked: false` + Uhr aktualisiert den Follow-Cursor nicht.
**Umschalttaste** beim Ghost: ganze Kette inkl. Satelliten mitverschieben. Loslassen: Satelliten zurück auf ihre Uhr. Klick speichert das, was du siehst.
Kern unter die Maus, Satellit mit fester Uhr:
```javascript
segments: [{
title: "Anfahrt",
linked: false,
offset: { days: -1 },
timeFrom: time(16, 0),
timeTo: time(17, 0)
}, {
title: "Vorarbeit",
offset: { days: 0 },
duration: time(0, 30)
}, {
title: "Kern",
duration: time(3, 0)
}, {
title: "Abfahrt",
offset: { days: 1 },
duration: time(1, 0)
}]
```
Ohne feste Uhren (folgt der Maus):
```javascript
segments: [{
title: "Anfahrt",
offset: { days: -1, time: -time(1, 0) },
duration: time(1, 0)
}, {
title: "Kernarbeit",
offset: { days: 0 },
duration: time(3, 0),
splits: [{
title: "Pause",
offset: time(1, 30),
duration: time(0, 30)
}]
}, {
title: "Abfahrt",
offset: { days: 1 },
duration: time(1, 0)
}]
```
Sollen die Stücke **anders heißen** (Teil 1 / Pause / Teil 2): drei `segments` mit `duration`, kein `splits`.
Der Ghost darf über mehrere Tage gehen. Pro Phase läuft die Uhrzeit mit (`##entrytime##`).
Der Ghost nimmt eine **eigene Spur** ein — bestehende Termine zur gleichen Zeit rücken zur Seite, wie bei zwei echten Einträgen. Maus weg: die anderen gehen wieder auf volle Breite.
Ausblenden: **Auge** in der Toolbar oder **Esc**. Wieder einblenden nur über das Auge. Die Seitenleisten-Auswahl bleibt.
Gespeichert wird **ein** neuer Datensatz auf dieselben vier `createNew`-Felder: Von der ersten Phase bis Bis der letzten. `changeFieldValues` und `dataBag` wie bei Aufziehen.
Leere Auswahl: `item` weglassen (kein `else ""`). Dann gilt wieder Aufziehen.
## timeEntries – deine Kalendereinträge im Detail
Der `timeEntries`-Block legt fest, welche konkreten Zeiteinträge im Kalender angezeigt werden.
Hier bestimmst du, wie jeder einzelne Eintrag dargestellt wird – von Titel über Farbe bis hin zu eigenen Layouts. So kannst du deine Kalenderkarten ganz individuell gestalten und an deinen Anwendungsfall anpassen. Dabei wird automatisch ein neuer Termin erstellt – inklusive Startzeit und Dauer.
📌 **Hinweis:**
Für die Darstellung der **Echtzeit-Veränderung** der Termindaten (beim Erstellen oder auch beim Verschieben eines Termins) kann der Platzhalter **"##entrytime##"** überall in `timeEntries` eingesetzt werden, wo die **Terminzeit** angezeigt werden soll, also im title, subtitle, value, aber auch in allen Widgets, die hier eingesetzt werden. Wie zB. wenn ein `customLayout` für das Design des timeEntries genutzt wird oder in Buttons, Inputs usw.
Zum Beispiel innerhalb eines Layout-Blocks im Text Widget:
```javascript
...
value: arcCustomText({
alignY: "top",
fontSize: typo.paragraph3.fontSize,
fontWeight: "400",
fontColor: appointmentType.colorShade,
value: "##entrytime##"
}),
...
```
➡️ Alle Parameter für die timeEntries findest du im **folgenden Abschnitt**.
### title – Titel des Kalendereintrags
Mit dem Parameter `title` legst du fest, was in der ersten Zeile des Kalendereintrags angezeigt wird.
🔧 Zwei Optionen:
- Eigener Titel:
Gib ein Feld oder einen Text an, der als Titel im Eintrag angezeigt werden soll.
- Keine Angabe (`"`):
Lässt du das Feld leer (`"`), wird stattdessen die Uhrzeit des Termins angezeigt.
title: Kalendertitel, // Ninox Feld
title: "", // Default: Gibt die Uhrzeit des Kalendereintrages an
📌 Hinweis:
- Wenn du keinen Titel vergibst und stattdessen die Uhrzeit angezeigt wird, wird diese Uhrzeit bei Änderungen live aktualisiert, z. B. beim Ziehen oder Verlängern eines Eintrags.
- **Leerer Wert:** Wenn `title` leer oder nur Leerzeichen enthält, wird die Titel-Zeile ausgeblendet – der Platz geht an `subtitle` oder `##entrytime##`.
### subtitle – Beschreibung unter dem Titel
Mit dem Parameter `subtitle` kannst du eine zusätzliche Zeile unter dem Titel im Kalendereintrag anzeigen lassen.
Typischerweise wird hier eine kurze Beschreibung oder ein ergänzender Hinweis wie z. B. der Grund des Termins oder ein Status hinterlegt.
→ Zeigt z. B. den Inhalt des Feldes *„Description“* unter dem Titel im Kalendereintrag an.
📌 **Hinweis:**
- Der `subtitle` ist optional und wird **nur angezeigt, wenn ein entsprechender Feldwert vorhanden ist**.
- **Leerer Wert:** Wenn `subtitle` leer oder nur Leerzeichen enthält, wird die Subtitle-Zeile ausgeblendet – der Platz geht an den Titel. Titel und Subtitle werden symmetrisch behandelt: Wenn beide leer sind, wird nur `##entrytime##` angezeigt.
### value – Zusatzinformationen oder interaktive Felder
Der Parameter `value` steht für die dritte Zeile deines Kalendereintrags. Hier kannst du weitere Informationen anzeigen oder sogar interaktive Elemente wie Eingabefelder oder Auswahllisten integrieren.
🔧 Einsatzmöglichkeiten:
- Zusätzliche Informationen wie z. B. Ort, Status, Verantwortlicher
- Interaktive Widgets direkt im Kalendereintrag – z. B.:
Ein Select-Feld, um den zuständigen Mitarbeiter auszuwählen
- Ein Input-Feld für kurze Notizen oder Rückmeldungen
value: "",
value: Kommentar,
→ Zeigt den Inhalt des Feldes *„Kommentar“* in der dritten Zeile an.
📌 **Hinweis:**
- `value` ist **optional**, erweitert aber die Darstellung deiner Einträge um eine zusätzliche Ebene.
- In Verbindung mit eingebetteten Widgets entsteht ein **interaktives Kalendererlebnis direkt im Eintrag**.
💡 **Tipp: **Nutze `value`, um wichtige Zusatzinfos sofort sichtbar zu machen – oder um deine Nutzer direkt im Kalender arbeiten zu lassen.
### customLayout – vollständiges individuelles Layout für Kalendereinträge
Mit dem Parameter `**customLayout**` kannst du ein **komplett eigenes Layout** für deine Kalendereinträge definieren.
Wenn du diesen Parameter nutzt, werden die Standardfelder `**title**`, `**subtitle**` und `**value**` **nicht mehr angezeigt**. Stattdessen kannst du frei gestalten, wie dein Kalendereintrag aussieht – mit beliebigen Widgets.
`customLayout: "",`
💡 Tipp: Nutze `customLayout`, wenn du eine komplett individuelle Darstellung brauchst, z. B. mit eigenen Farben, Icons, Struktur oder logischen Bedingungen.
### dateFrom, dateTo, timeFrom, timeTo – Start- und Endzeit je Eintrag
Mit diesen vier Parametern gibst du an, **welche Felder aus deinem Zeiteintrags-Datensatz** für **Datum und Uhrzeit** verwendet werden sollen.
```javascript
dateFrom: 'Date From',
dateTo: 'Date To',
timeFrom: 'Time From',
timeTo: 'Time To',
```
📌 Hinweis:
- Es müssen echte Datums- und Zeitfelder aus Ninox angegeben werden.
- Die Kombination aus Datum + Uhrzeit bestimmt die Position und Länge des Kalendereintrags.
⚠️ Wichtig zu wissen:
- Fehlt `dateTo`, wird automatisch der Tag aus `dateFrom` verwendet (und umgekehrt).
- Fehlen beide Datumsfelder, wird der Eintrag nicht angezeigt.
- Fehlt `timeTo`, wird automatisch `timeFrom + 5 Minuten` verwendet.
- Fehlt `timeFrom`, wird `timeTo - 5 Minuten` angenommen.
→ So ist eine minimale Anzeige trotzdem möglich.
💡 Tipp: Wenn du nur Tages-Einträge ohne genaue Uhrzeiten darstellen willst, kannst du auch nur mit Datumsfeldern arbeiten – der Kalender stellt den Eintrag dann als Ganztagstermin dar.
### styles – individuelles Styling für Kalendereinträge
Mit dem Parameter `**styles**` kannst du das **Aussehen einzelner Kalendereinträge** anpassen – z. B. Farben, Innenabstand (Padding) oder abgerundete Ecken (Border-Radius).
📌 **Unterstützte Eigenschaften:**
- `backgroundColor`: Hintergrundfarbe der Karte
- `color`: Schriftfarbe
- `padding`: Innenabstand (z. B. `"6px"`)
- `borderRadius`: Abrundung der Ecken (z. B. `"8px"`)
💡 Tipp: Mit `styles` kannst du deine Einträge **visuell voneinander abheben**, etwa nach Status, Typ oder Priorität – auch dynamisch, wenn du Felder deiner Datenquelle als Wert verwendest.
### dragAction – Felder für das Verschieben von Einträgen festlegen
Mit dem Parameter `**dragAction**` definierst du, **welche Datums- und Zeitfelder beim Ziehen oder Verschieben eines Eintrags aktualisiert werden sollen**.
So wird sichergestellt, dass der neue Zeitpunkt im **Datensatz gespeichert** wird, wenn ein Eintrag im Kalender bewegt wird.
```javascript
dragAction: {
recordId: Nr,
dateFrom: fieldId(Nr, "Datum von"),
timeFrom: fieldId(Nr, "Von"),
dateTo: fieldId(Nr, "Datum bis"),
timeTo: fieldId(Nr, "Bis"),
changeFieldValues: [{
fieldId: fieldId(Nr, "CacheTrigger"),
value: now()
}]
}
```
📌 Hinweis:
- Gib hier die korrekten Feld-IDs der einzelnen Felder in der Zeiteintrags-Tabelle an.
- Du kannst hier die Ninox Funktion `fieldId()` benutzen.
- **changeFieldValues**: Optional. Array von `{ fieldId, value }` – wird **nach** einem erfolgreichen Drag geschrieben (Datum/Zeit haben sich geändert). Typischer Einsatz: Cache- oder Trigger-Felder aktualisieren. Aufbau wie bei `createNew.changeFieldValues` und wie in der Timeline.
⚠️ Wichtig: `recordId` und die Datums-/Zeitfelder sind zwingend erforderlich, wenn du möchtest, dass Einträge per Drag & Drop verschoben oder in ihrer Dauer verändert werden können.
📌 **Persistenz / React:** Beim Speichern nach Drag sendet das Widget Action-Performer-Actions `{ type: "update", recordId, field, value }` (ein Action pro geändertes Feld). In Ninox mappt der Adapter das auf `database.update`. Im React-Adapter landet das in `onAction` — ohne globales `database`.
### clickAction – Einträge per Klick in Ninox öffnen
Mit dem Parameter `**clickAction**` ermöglichst du es, dass der Nutzer durch einen Klick auf einen Kalendereintrag direkt den **zugehörigen Datensatz in Ninox öffnen** kann.
clickAction: {
type: "popup",
recordId: Nr
}
📌 Bedeutung der Parameter:
- `type: "popup"` – Öffnet den Datensatz in einem Popup-Fenster (weitere Typen können ggf. folgen).
- `recordId`: Das Feld im Kalendereintrag, das den Primärschlüssel (Record ID) enthält – meist `"Nr"`.
⚠️ Wichtig:
- Das angegebene Feld bei `recordId` muss die echte Ninox-Datensatz-ID enthalten.
- Wird kein gültiger Wert gefunden, passiert beim Klick nichts.
### insetBorder – vertikale Inset-Linie im Kalendereintrag
Mit `**insetBorder**` kannst du eine **dezente vertikale Linie** am linken (oder rechten) Rand jedes Kalendereintrags anzeigen lassen – ähnlich dem Stil des Apple Kalenders. Das Feature ist **standardmäßig aktiv** und muss nur deaktiviert werden, wenn du es nicht möchtest.
```javascript
insetBorder: {
enabled: true, // Standard: true – false blendet die Linie aus
position: "left", // "left" (Standard) oder "right"
width: "2px", // Breite der Linie
stroke: "dotted", // "solid", "dashed" oder "dotted"
color: "#ffffff" // Farbe (Standard: Schriftfarbe des Eintrags)
}
```
📌 **Hinweis:**
- Die Linie reagiert automatisch auf den `borderRadius` des Eintrags und wird kürzer, je höher der Radius ist.
- Bei zusammenhängenden Segmenten (Kette) wird sie an Übergängen nahtlos fortgesetzt.
- Du kannst `insetBorder` sowohl auf Ebene des `timeEntry` als auch pro Segment definieren – das Segment-Level überschreibt das Entry-Level.
### segments – Termine in Phasen unterteilen
Mit dem Parameter `**segments**` kannst du einen Termin in mehrere **zusammengehörige Zeitphasen** aufteilen – z. B. Anfahrt, Vorarbeit, Kernarbeit, Pause, Nacharbeit und Abfahrt.
Jedes Segment ist ein eigenständiger Eintrag mit eigener Zeit und eigenem Design, kann aber mit anderen Segmenten **verknüpft** werden, sodass sie beim Verschieben gemeinsam bewegt werden.
```javascript
timeEntries: (select Termine).[{
title: Bezeichnung,
dateFrom: 'Datum von',
dateTo: 'Datum bis',
timeFrom: Von,
timeTo: Bis,
styles: {
backgroundColor: "#5b6af0",
color: "#fff",
borderRadius: "8px"
},
dragAction: {
recordId: Nr,
dateFrom: fieldId(Nr, "Datum von"),
timeFrom: fieldId(Nr, "Von"),
dateTo: fieldId(Nr, "Datum bis"),
timeTo: fieldId(Nr, "Bis")
},
segmentSettings: {
dayJump: {
threshold: time(22, 0),
startTime: time(7, 0)
}
},
segments: [{
title: "Anfahrt",
dateFrom: 'Seg Datum von',
dateTo: 'Seg Datum bis',
timeFrom: SegVon,
timeTo: SegBis,
styles: {
backgroundColor: "#3b4fd0",
color: "#fff"
},
linked: false,
segmentType: "travel",
dragAction: {
recordId: Nr,
dateFrom: fieldId(Nr, "Seg Datum von"),
timeFrom: fieldId(Nr, "SegVon"),
dateTo: fieldId(Nr, "Seg Datum bis"),
timeTo: fieldId(Nr, "SegBis")
}
}, {
title: "Kernarbeit",
dateFrom: 'Kern Datum von',
dateTo: 'Kern Datum bis',
timeFrom: KernVon,
timeTo: KernBis,
styles: {
backgroundColor: "#5b6af0",
color: "#fff"
},
linked: true
}]
}]
```
#### Felder je Segment
| Parameter | Typ | Beschreibung |
|---|---|---|
| `title` | Text | Titel des Segments |
| `subtitle` | Text | Untertitel (optional) |
| `value` | Text/Widget | Zusatzzeile oder eingebettetes Widget |
| `dateFrom`, `dateTo` | Datum | Start- und Enddatum |
| `timeFrom`, `timeTo` | Zeit | Start- und Endzeit |
| `styles` | Objekt | Wie beim `timeEntry` – überschreibt Parent-Styles |
| `linked` | Boolean | `true` = Segment wird mit anderen `linked`-Segmenten gemeinsam verschoben (Standard: `true`) |
| `segmentType` | Text | Frei wählbarer Typ-Bezeichner (z. B. `"travel"`, `"core"`) |
| `insetBorder` | Objekt | Inset-Linie für dieses Segment (überschreibt Entry-Level) |
| `dragAction` | Objekt | Felder für Drag & Drop – Aufbau identisch mit `timeEntry.dragAction` |
| `segmentSettings` | Objekt | Segment-Einstellungen für dieses einzelne Segment (z. B. `dayJump`) |
| `splits` | Array | Eine Ebene Unterbrechungen in dieser Phase (z. B. Pause). Das Widget macht daraus: Teil 1 → Pause → Teil 2. |
💡 **Tipp:** Felder die nicht im Segment gesetzt werden, erben den Wert des übergeordneten `timeEntry`. So reicht es, nur die Unterschiede pro Segment zu definieren.
#### splits – Pause in einer Phase
`splits` teilt **eine** Phase (meist Kernarbeit), ohne dass du in Ninox „Kern Teil 1 / Kern Teil 2“ anlegen musst. Keine weitere Verschachtelung — nur diese eine Ebene.
```javascript
{
title: "Kernarbeit",
dateFrom: 'Datum von',
dateTo: 'Datum bis',
timeFrom: time(11, 0),
timeTo: time(14, 0),
splits: [{
title: "Pause",
timeFrom: time(12, 30),
timeTo: time(13, 0),
styles: {
backgroundColor: "#94a3b8"
}
}]
}
```
Oder relativ zum Phasen-Start: `offset: time(1, 30)`, `duration: time(0, 30)`.
Mehrere Splits sind erlaubt; sie werden nach Startzeit sortiert und auf den Phasen-Zeitraum begrenzt. Kern-Stücke behalten Look und Titel der Phase, die Pause ihren eigenen.
Unterschiedliche Titel für die Kern-Stücke (Teil 1 / Teil 2): **drei `segments`**, kein `splits` — z. B. `duration: time(1, 30)`, Pause, `duration: time(1, 30)`.
#### linked – Segmente verknüpfen oder entkoppeln
Mit `linked: true` (Standard) wird ein Segment Teil der **verbundenen Kette**. Beim Verschieben im Kalender bewegen sich alle verknüpften Segmente gemeinsam.
Mit `linked: false` wird ein Segment **entkoppelt** – z. B. Anfahrt und Abfahrt, die auf einem anderen Tag liegen können und unabhängig verschoben werden sollen. Im **Placement-Ghost** (`createNew.item`) gilt dasselbe: eine Uhr auf einem `linked: false`-Satelliten nagelt den Kern nicht fest.
#### Toolbar
Unten rechts sitzt eine **kleine Toolbar**. Sie ist **immer sichtbar**, außer `segmentSettings.toolbar` ist `false`.
**Schloss** — Segmente gemeinsam oder einzeln verschieben:
- **Gesperrt** (Schloss zu): Alle Segmente des `timeEntry` werden gemeinsam verschoben
- **Einzeln** (Schloss offen): `linked`-Segmente bilden eine Gruppe, `linked: false`-Segmente können unabhängig verschoben werden
Ohne Segmente ist das Schloss inaktiv. Hover zeigt einen kurzen Hinweis.
**Auge** — nur bei `createNew.item`: Ghost ein- und ausblenden. **Esc** blendet aus. Wieder einblenden nur über das Auge. Ausgeblendet gilt wieder Aufziehen, ohne die Auswahl in der Seitenleiste zu ändern.
💡 **Shift-Taste:** Während eines Drags oder beim **Placement-Ghost** hältst du **Shift**, um den Lock umzukehren: gespeicherte Satelliten bzw. Ghost-Satelliten wandern mit. Loslassen setzt Ghost-Satelliten auf ihre Uhr zurück. Das Schloss-Icon zeigt den Zustand live.
💡 **Shift + Resize:** Wenn du die Shift-Taste hältst und an einem Segment-Rand ziehst (oben/unten), verschieben sich alle angrenzenden Segmente mit – der **Gesamtblock wird größer**, statt dem Folge-Segment Zeit wegzunehmen.
## segmentSettings – Globale Einstellungen für Segmente
Der optionale Parameter `**segmentSettings**` auf Ebene des gesamten Widgets steuert das **Standardverhalten aller Segmente** – z. B. ob Gruppen standardmäßig gesperrt sind oder ob die Toolbar angezeigt wird.
```javascript
arcCustomCalendarWeek({
// ...
segmentSettings: {
lockGroups: true,
edgeMagnetism: true,
toolbar: true,
dayJump: {
threshold: time(22, 0),
startTime: time(7, 0)
}
},
timeEntries: [...]
})
```
📌 **Parameter im Überblick:**
| Parameter | Typ | Beschreibung |
|---|---|---|
| `lockGroups` | Boolean | `true` = Segmente werden standardmäßig gemeinsam verschoben (Standard: `true`) |
| `edgeMagnetism` | Boolean | `true` = Beim Resize bleibt die gemeinsame Grenze angrenzender Segmente synchron (Standard: `true`) |
| `toolbar` | Boolean | `false` = Toolbar ausblenden. Sonst immer sichtbar (Schloss + Auge bei `createNew.item`) |
| `dayJump.threshold` | Zeit | Ab dieser Uhrzeit springt ein Segment beim Drag auf den nächsten Tag |
| `dayJump.startTime` | Zeit | Startzeit am neuen Tag nach dem Sprung |
⚠️ **Priorität:** Einstellungen auf `timeEntry`-Ebene (`segmentSettings` innerhalb eines Eintrags) überschreiben die globalen `segmentSettings`. Einstellungen auf Segment-Ebene überschreiben wiederum die Entry-Ebene.
---
Mit dem Custom Calendar Week bringst du strukturierte Planung und volle Flexibilität in deine Ninox-Datenbank – individuell anpassbar, intuitiv bedienbar und bereit für deinen Alltag.
Happy Widgeting 🥳
---
# Custom Calendar Grid
Source: https://www.arc-rider.com/docs/widgets/custom-calendar-grid
# CalendarGrid in React
Termine in einer Monatsübersicht anzeigen und Tage oder Einträge auswählen.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetCalendarGrid } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const locale = lang === 'en' ? 'en-US' : lang === 'es' ? 'es-ES' : 'de-DE';
const chrome = {
backgroundColor: '#ffffff',
fontColor: '#18181b',
mutedColor: '#52525b',
subtleColor: '#71717a',
borders: { color: '#e4e4e7', outer: true, columns: true, rows: true },
};
const look = (backgroundColor: string, color: string) => ({
backgroundColor,
color,
fontColor: color,
});
type Entry = {
id: string;
title: string;
dateFrom: number;
dateTo: number;
timeFrom: number;
timeTo: number;
clickable: true;
draggable: true;
styles: ReturnType;
};
const event = (
id: string,
title: string,
day: number,
backgroundColor: string,
color: string,
): Entry => ({
id,
title,
dateFrom: new Date(2026, 8, day).getTime(),
dateTo: new Date(2026, 8, day).getTime(),
timeFrom: 9 * 3600000,
timeTo: 11 * 3600000,
clickable: true,
draggable: true,
styles: look(backgroundColor, color),
});
const demoEntries: Entry[] = [
event(
'travel-out',
t('Anfahrt', 'Travel there', 'Ida'),
16,
'#99f6e4',
'#115e59',
),
event(
'visit',
t('Hauptarbeit', 'On site', 'Trabajo principal'),
17,
'#ccfbf1',
'#115e59',
),
event(
'travel-back',
t('Abfahrt', 'Travel back', 'Vuelta'),
18,
'#99f6e4',
'#115e59',
),
event(
'review',
t('Projekt-Review', 'Project review', 'Revisión'),
21,
'#ede9fe',
'#5b21b6',
),
event(
'ship',
t('Lieferung', 'Delivery', 'Entrega'),
24,
'#fef3c7',
'#92400e',
),
];
const busyEntries: Entry[] = [
...demoEntries,
event('kickoff', t('Kickoff', 'Kickoff', 'Kickoff'), 3, '#d1fae5', '#065f46'),
event('fair', t('Messe', 'Fair', 'Feria'), 8, '#ffe4e6', '#9f1239'),
event('retro', t('Retro', 'Retro', 'Retro'), 28, '#e0f2fe', '#075985'),
];
export default function Example() {
const [month, setMonth] = useState(9);
const [entries, setEntries] = useState(
pack === 'empty' ? [] : pack === 'busy' ? busyEntries : demoEntries,
);
const [selected, setSelected] = useState(
t(
'Termin ziehen oder anklicken',
'Drag or click an event',
'Arrastra o pulsa un evento',
),
);
return (
<>
setSelected(new Date(date).toLocaleDateString(locale))
}
onEntryClick={(index) => setSelected(entries[index]?.title ?? selected)}
onEntryDragSave={(index, start) => {
setEntries((previous) =>
previous.map((entry, i) =>
i === index
? {
...entry,
dateFrom: Number(start.dateFrom ?? entry.dateFrom),
dateTo: Number(start.dateTo ?? entry.dateTo),
}
: entry,
),
);
setSelected(t('Termin verschoben', 'Event moved', 'Evento movido'));
}}
/>
{selected}
);
}
```
## Features ausprobieren
### Monatsnavigation, Tagesauswahl und JSX
Wechsle auch über den Jahreswechsel und wähle einen Tag aus. Der Beispieltermin bleibt am 17. September 2026; andere Monate sind bewusst leer.
```tsx
import { useState } from 'react';
import {
ArcWidgetCalendarGrid,
ArcWidgetBadge,
} from '@arcrider/arcwidgets-react';
export default function Example() {
const [offset, setOffset] = useState(0);
const [custom, setCustom] = useState(false);
const [selected, setSelected] = useState('Keine Auswahl');
const month = new Date(2026, 8 + offset, 1);
return (
<>
) : undefined,
dateFrom: new Date(2026, 8, 17).getTime(),
dateTo: new Date(2026, 8, 17).getTime(),
timeFrom: 10 * 3600000,
timeTo: 11 * 3600000,
clickable: true,
draggable: false,
},
],
}}
onDayClick={(date) =>
setSelected(new Date(date).toLocaleDateString('de-DE'))
}
onEntryClick={() => setSelected('Projekt-Review')}
/>
Auswahl: {selected}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetCalendarGridData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onEntryClick
Index des Termins, bei Timeline zusätzlich der Ressourcenzeile.
```typescript
onEntryClick?: (entry_index: number) => void;
```
### onDayClick
Datum des gewählten Tages als Millisekunden-Zeitstempel.
```typescript
onDayClick?: (date_millis: number) => void;
```
### onEntryDragSave
Drag-Ende mit ursprünglichen Daten. Keine vollständigen neuen Zielzeiten; siehe Hinweise zur Persistenz.
```typescript
onEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarGridDragStart) => void;
```
### onDailyEntryDragSave
Drag-Ende eines ganztägigen Termins mit ursprünglichen Daten.
```typescript
onDailyEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarGridDragStart) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### timeZoneBalance
Korrektur in Stunden; die Beispiele verwenden `0` und lokal erzeugte Tageswerte.
Typ: `number | string`.
### styles
Gemeinsame Farben, Abstände und Rahmen; die angebotenen Felder sind widgetspezifisch.
Typ: `ArcWidgetCalendarGridStyles | string`.
### dateSettings
Datumsbereich, Kopfzeilen und Markierungen.
Typ und verschachtelte Felder stehen in `ArcWidgetCalendarGridData` unter Datentypen.
### timeSettings
Zeitbereich und Raster; Einheiten sind Millisekunden.
Typ: `Record`.
### lang
Sprache der Kalenderbeschriftungen.
Typ: `string`.
### timeEntries
Termine mit Datumswerten, Uhrzeiten und Inhalten.
Typ und verschachtelte Felder stehen in `ArcWidgetCalendarGridData` unter Datentypen.
## Verhalten und Grenzen
- Für JSX in Terminen verwende `customLayout`. Die Standardfelder `title`, `subtitle` und `value` werden als Text oder HTML verarbeitet.
- Datumswerte sind Zeitstempel in Millisekunden; Uhrzeiten sind Millisekunden seit Tagesbeginn. Siehe [Datum und Zeit](/docs/react/patterns/react-dates).
- `clickable: true` aktiviert die Auswahl. Ein Callback-Index ist keine Datensatz-ID; löse ihn über deine aktuelle Eintragsliste auf.
- Die derzeitigen Drag-Callbacks enthalten den ursprünglichen Stand (`start_data`), jedoch keine vollständigen neuen Zielzeiten. Das Beispiel setzt deshalb `draggable: false`. Bearbeite Termine über React-State, bis ein vollständiger Persistenzvertrag für Drag & Drop vorliegt.
- `dateSettings.month` ist einsbasiert: Januar ist `1`. Markierungen liegen in `dateSettings.highlights`.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetCalendarGridDay {
clickable?: boolean;
height?: string;
alignX?: string;
backgroundColor?: string;
hoverBackgroundColor?: string;
padding?: string;
[key: string]: unknown;
}
export interface ArcWidgetCalendarGridDragStart {
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
}
export type ArcWidgetCalendarGridBorderLine = boolean | {
color?: string;
width?: string;
borderColor?: string;
borderWidth?: string;
borderSize?: string;
enabled?: boolean;
};
export interface ArcWidgetCalendarGridBorders {
color?: string;
width?: string;
outer?: ArcWidgetCalendarGridBorderLine;
columns?: ArcWidgetCalendarGridBorderLine;
rows?: ArcWidgetCalendarGridBorderLine;
}
export interface ArcWidgetCalendarGridStyles extends ArcWidgetStyles {
borders?: ArcWidgetCalendarGridBorders;
headerBackgroundColor?: string;
mutedColor?: string;
subtleColor?: string;
}
export interface ArcWidgetCalendarGridData extends Omit {
height?: string;
timeZoneBalance?: number | string;
styles?: ArcWidgetCalendarGridStyles | string;
dateSettings?: {
month?: number;
year?: number;
day?: ArcWidgetCalendarGridDay;
highlights?: Array<{ date?: unknown; color?: string; [key: string]: unknown }>;
[key: string]: unknown;
};
timeSettings?: Record;
lang?: string;
timeEntries?: Array<{
id?: string | number;
title?: string;
subtitle?: string;
value?: string;
customLayout?: ArcWidgetSlot;
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
styles?: ArcWidgetStyles | string;
clickable?: boolean;
draggable?: boolean;
[key: string]: unknown;
}>;
}
export interface ArcWidgetCalendarGridProps extends ArcReactWidgetProps {
onEntryClick?: (entry_index: number) => void;
onDayClick?: (date_millis: number) => void;
onEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarGridDragStart) => void;
onDailyEntryDragSave?: (entry_index: number, start_data: ArcWidgetCalendarGridDragStart) => void;
}
```
## Einsatzbeispiele
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Calendar Grid
## AI Defaults (read first)
- **uniqueId**: Required, `"cal-grid-" + Nr`.
- **height**: Use `"100%"` when embedded in a layout.
- **timeZoneBalance**: Set `-1` for German timezone.
- **dateSettings.month/year**: 1–12 für Monat, Jahr für die Monatsansicht.
- **dateFrom/dateTo**: Must be actual date field values in timeEntries.
- **dragAction**: Requires `recordId` and field IDs via `fieldId(Nr, "Feldname")`.
- **createNew**: Needs `tableId`, field IDs for target fields.
- **Persistence**: Drag saves go through the **Action Performer** (`type: "update"`). Ninox `dragAction` config is unchanged. React hosts: handle via `onAction` — **no** global `database` stub.
- **day.actions**: Array of actions with `##clickedDate##` placeholder – use instead of clickAction.
# Custom Calendar Grid
Mit dem Widget **Custom Calendar Grid** bringst du eine Monats-Grid-Kalenderansicht in deine Ninox-Datenbank. Es zeigt einen klassischen Kalendermonat mit Wochenzeilen und Tageszellen – ideal für Monatsübersichten, Urlaubsplanung oder Terminübersicht.
💡 **Was du mit Custom Calendar Grid machen kannst:**
- **Monatsansicht:** Klassisches 6-Wochen-Grid mit Wochentagen und Kalenderwochen.
- **Zeit- und ganztägige Einträge:** Zeige Termine mit Uhrzeit und mehrtägige Events.
- **Drag & Drop:** Verschiebe Termine direkt im Kalender.
- **Klick auf Tag:** Führe Aktionen aus mit dem geklickten Datum als Platzhalter.
- **Hervorhebung:** Markiere Wochenenden, Feiertage oder besondere Tage.
- **Individuelles Styling:** Passe Header, Wochentage und Tageszellen an.
## Anwendungscode
```javascript
let current := this;
arcCustomCalendarGrid({
uniqueId: "cal-grid-" + Nr,
embedded: false,
height: "100%",
timeZoneBalance: -1,
lang: clientLang(),
dateSettings: {
month: month(today()),
year: year(today()),
header: {
title: { label: "##monthLong## ##year##", fontSize: "18px", fontColor: "#333" }
},
weekdays: { label: "##weekDayShort##", fontSize: "13px" },
week: { show: true },
day: {
height: "120px",
alignX: "left",
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "helper_ui_state_backoffice"),
dataBag: {
base: helper_ui_state_backoffice,
patch: { cal_view: "1", cal_date: "##clickedDate##" }
}
}]
},
highlights: [
{ weekday: 6, day: { backgroundColor: "#fafafa" } },
{ weekday: 0, day: { backgroundColor: "#fafafa" } }
]
},
timeEntries: (select Termine where month(Termin) = month(today()) and year(Termin) = year(today())).[{
title: Bezeichnung,
dateFrom: Termin,
dateTo: Termin,
timeFrom: von,
timeTo: bis,
styles: { backgroundColor: "#3388FF", color: "#fff", borderRadius: "6px" },
dragAction: { recordId: Nr, dateFrom: "A", timeFrom: "B", dateTo: "C", timeTo: "D" },
clickAction: { type: "popup", recordId: Nr }
}]
})
```
## dateSettings – Zeitraum & Darstellung
### month / year
Definiert den anzuzeigenden Monat. `month` ist 1–12 (Januar = 1), `year` ist die Jahreszahl.
```javascript
dateSettings: {
month: 11,
year: 2024
}
```
### startDate / endDate / duration (optional)
Alternativ zu `month`/`year` kannst du einen expliziten Zeitraum definieren:
- **startDate**: Startdatum (Millisekunden oder Ninox-Datum)
- **endDate**: *(optional)* Enddatum. Hat Vorrang vor `duration`.
- **duration**: *(optional)* Anzahl der anzuzeigenden Tage. Wird nur berücksichtigt, wenn `endDate` nicht gesetzt ist.
```javascript
dateSettings: {
startDate: date(2024, 11, 1),
endDate: date(2024, 11, 30)
}
```
Oder mit `duration` statt `endDate`:
```javascript
dateSettings: {
startDate: date(2024, 11, 1),
duration: 42
}
```
### day – Tageszellen & Klick-Aktionen
Unter `dateSettings.day` steuerst du das Aussehen der Tageszellen und die Aktionen beim Klick auf einen Tag.
#### day.actions – Aktionen beim Klick auf einen Tag
Mit `day.actions` definierst du ein **Array von Aktionen**, die beim Klick auf eine Tageszelle ausgeführt werden. Der Platzhalter `##clickedDate##` wird durch den **Millisekunden-Timestamp** des geklickten Datums ersetzt.
```javascript
day: {
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "helper_ui_state_backoffice"),
dataBag: {
base: helper_ui_state_backoffice,
patch: { cal_view: "1", cal_date: "##clickedDate##" }
}
}]
}
```
**Platzhalter:**
| Platzhalter | Ersetzt durch |
|-------------|---------------|
| `##clickedDate##` | Millisekunden-Timestamp des geklickten Datums (z. B. `1731369600000`) |
**Action-Typen:** Wie bei `arcCustomInput` und anderen Widgets – `update`, `popup`, `openUrl`, etc. Siehe `action_performer` für alle unterstützten Typen.
**Wichtig:** Der Platzhalter wird rekursiv in allen String-Werten der Action ersetzt – auch in verschachtelten Objekten (z. B. in `value` bei JSON-State-Updates).
#### Weitere day-Eigenschaften
- `height`: Mindesthöhe der Tageszelle (z. B. `"120px"`)
- `alignX`: `"left"`, `"center"`, `"right"` für die Ausrichtung der Tagesnummer
- `backgroundColor`, `hoverBackgroundColor`: Hintergrundfarben
- `padding`: Innenabstand
- `number`: Styling für die Tagesnummer (fontSize, fontColor, containerSize, etc.)
- `maxTimeEntries`: Begrenzt die sichtbaren Einträge pro Tag (siehe unten)
#### maxTimeEntries – Begrenzung sichtbarer Einträge pro Tag
Wenn ein Tag mehr Einträge hat als `amount`, werden nur die ersten angezeigt. Ein Hinweis „+ X weitere“ erscheint; Klick darauf löst dieselbe Aktion aus wie ein Klick auf die Tageszelle (`day.actions`).
```javascript
maxTimeEntries: {
amount: 5,
suffix: "weitere"
}
```
| Eigenschaft | Bedeutung |
|-------------|-----------|
| `amount` | Maximale Anzahl sichtbarer Einträge. Ab dem (amount+1). Eintrag wird gekürzt. |
| `suffix` | Text für „+ X suffix“ (z. B. `"weitere"` → „+ 3 weitere“). Standard: `"more"`. |
### week – Kalenderwochennummer
Mit `week.show` zeigst du die ISO-Kalenderwoche am ersten Tag jeder Woche an:
```javascript
week: {
show: true,
number: {
fontSize: "12px",
fontColor: "#999",
fontWeight: "normal"
}
}
```
### header – Monats-/Jahres-Header
- `backgroundColor`: Hintergrundfarbe
- `title`: `label`, `fontSize`, `fontColor`, `fontWeight`, `alignX`
- `subtitle`: *(optional)* Zweite Zeile mit `label`, `fontSize`, `fontColor`, `fontWeight`, `alignX`
Platzhalter für `label`: `##monthLong##`, `##year##`, `##weekDayShort##` etc. Siehe `custom-calendar-week` für alle Platzhalter.
### weekdays – Wochentagszeile
- `label`: Platzhalter (z. B. `"##weekDayShort##"`)
- `backgroundColor`, `fontSize`, `fontColor`, `fontWeight`, `padding`, `alignX`
### highlights – Hervorhebung von Tagen
Hervorhebung nach Wochentag oder konkretem Datum:
```javascript
highlights: [
{ weekday: 6, day: { backgroundColor: "#fafafa" } },
{ weekday: 0, day: { backgroundColor: "#fafafa" } },
{ date: 1731369600000, day: { number: { containerSize: "32px", backgroundColor: "#4970ff", borderRadius: "50%", fontColor: "#fff" } } }
]
```
- `weekday`: 0–6 (Sonntag = 0, Samstag = 6)
- `date`: Millisekunden-Timestamp für ein bestimmtes Datum
- `day`: Styling für die Tageszelle (backgroundColor, number, padding, etc.)
## styles – Gesamtkalender-Styling
Über `styles` kannst du den **äußersten** Kalender-Container gestalten. Alle Einstellungen (z. B. `borderRadius`, `border`, `borderColor`, `backgroundColor`) werden direkt auf den äußersten Container angewendet. Standard-Border-Radius ist `8px`. Wenn `borderRadius` gesetzt ist, erhält der Container automatisch `overflow: hidden`, damit abgerundete Ecken sauber dargestellt werden.
```javascript
styles: {
borderRadius: "8px",
borderColor: "#ddd",
backgroundColor: "#fff"
}
```
## timeEntries – Kalendereinträge
Jeder Eintrag benötigt:
- `dateFrom`, `dateTo`: Datum (Millisekunden)
- `timeFrom`, `timeTo`: Optional – Uhrzeit in Millisekunden (0 = Mitternacht). Ohne Zeit = ganztägiger Eintrag
- `title`, `subtitle`, `value`: Anzeige (oder `customLayout` für eigene HTML-Struktur)
- `styles`: CSS-ähnliche Styles (backgroundColor, color, borderRadius, padding)
- `dragAction`: Für Drag & Drop; `recordId`, `dateFrom`, `timeFrom`, `dateTo`, `timeTo` als Feld-IDs. Persistenz über Action Performer (`type: "update"`); React: `onAction`, kein globales `database`.
- `clickAction`: Für Klick auf den Eintrag (z. B. `{ type: "popup", recordId: Nr }`)
**customLayout:** HTML-String für individuelle Darstellung statt `title`/`subtitle`/`value`. Bei Ganztagseinträgen ersetzt der Platzhalter `##entrytime##` die Zeitspanne (z. B. „00:00 - 23:59“ bei eintägigen Events).
## createNew – Erstellen neuer Einträge
Definiert, wie neue Einträge erstellt werden (z. B. beim Klick auf einen leeren Tag):
```javascript
createNew: {
tableId: "B",
dateFrom: "A",
timeFrom: "B",
dateTo: "C",
timeTo: "D"
}
```
---
# Custom Calendar Timeline
Source: https://www.arc-rider.com/docs/widgets/custom-calendar-timeline
# CalendarTimeline in React
Zeiträume pro Ressource oder Objekt auf einer gemeinsamen Zeitachse anzeigen.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetCalendarTimeline } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const day = (value: number) => new Date(2026, 8, value).getTime();
const chrome = {
backgroundColor: '#ffffff',
fontColor: '#18181b',
mutedColor: '#52525b',
subtleColor: '#71717a',
headerBackgroundColor: '#fafafa',
groupBackgroundColor: '#f4f4f5',
rowBackgroundColor: '#ffffff',
borders: { outer: true, rows: true, columns: false, color: '#e4e4e7' },
dayStripes: { odd: '#ffffff', even: '#f4f4f5' },
};
const look = (backgroundColor: string, color: string) => ({
backgroundColor,
color,
fontColor: color,
});
type Bar = {
id: string;
title: string;
dateFrom: number;
dateTo: number;
clickable: true;
draggable: true;
styles: ReturnType;
};
type Row = {
id: string;
title: string;
timeEntries: Bar[];
};
const bar = (
id: string,
title: string,
from: number,
to: number,
backgroundColor: string,
color: string,
): Bar => ({
id,
title,
dateFrom: day(from),
dateTo: day(to),
clickable: true,
draggable: true,
styles: look(backgroundColor, color),
});
const demoRows: Row[] = [
{
id: 'team-a',
title: t('Team Montage', 'Install team', 'Equipo montaje'),
timeEntries: [
bar(
'job-a',
t('Installation', 'Installation', 'Instalación'),
16,
18,
'#d1fae5',
'#065f46',
),
],
},
{
id: 'team-b',
title: t('Kundentermin', 'Site visit', 'Visita'),
timeEntries: [
bar(
'job-b-out',
t('Anfahrt', 'Travel there', 'Ida'),
16,
16,
'#99f6e4',
'#115e59',
),
bar(
'job-b',
t('Hauptarbeit', 'On site', 'Trabajo principal'),
17,
17,
'#ccfbf1',
'#115e59',
),
bar(
'job-b-back',
t('Abfahrt', 'Travel back', 'Vuelta'),
18,
18,
'#99f6e4',
'#115e59',
),
],
},
];
const busyRows: Row[] = [
...demoRows,
{
id: 'team-c',
title: t('Team Messe', 'Fair team', 'Equipo feria'),
timeEntries: [
bar(
'job-c',
t('Aufbau', 'Setup', 'Montaje'),
15,
17,
'#ede9fe',
'#5b21b6',
),
bar(
'job-d',
t('Abbau', 'Teardown', 'Desmontaje'),
22,
24,
'#ffe4e6',
'#9f1239',
),
],
},
];
const emptyRows: Row[] = demoRows.map((row) => ({ ...row, timeEntries: [] }));
export default function Example() {
const [rows, setRows] = useState(
pack === 'empty' ? emptyRows : pack === 'busy' ? busyRows : demoRows,
);
const [selected, setSelected] = useState(
t(
'Balken ziehen oder zoomen',
'Drag bars or zoom days',
'Arrastra barras o haz zoom',
),
);
return (
<>
({
id: row.id,
columns: [{ title: row.title, clickable: true }],
timeEntries: row.timeEntries,
})),
}}
onEntryClick={(rowIndex, entryIndex) =>
setSelected(
rows[rowIndex]?.timeEntries[entryIndex]?.title ?? selected,
)
}
onLabelClick={(rowIndex) =>
setSelected(rows[rowIndex]?.title ?? selected)
}
onEntryDragSave={(rowIndex, entryIndex, start, rowChange) => {
setRows((previous) => {
const next = previous.map((row) => ({
...row,
timeEntries: [...row.timeEntries],
}));
const [item] = next[rowIndex].timeEntries.splice(entryIndex, 1);
next[rowChange.row_index ?? rowIndex].timeEntries.push({
...item,
dateFrom: Number(start.dateFrom ?? item.dateFrom),
dateTo: Number(start.dateTo ?? item.dateTo),
});
return next;
});
setSelected(t('Balken verschoben', 'Bar moved', 'Barra movida'));
}}
/>
{selected}
);
}
```
## Features ausprobieren
### Zeitraum, Zoom, Unterressourcen und Gestaltung
Nutze die Zoom-Tasten im Widget, ändere den Zeitraum und blende die Unterressource ein. Die Balken verwenden JSX; die Klick-Callbacks zeigen die tatsächlichen Zeilenindizes.
```tsx
import { useState } from 'react';
import {
ArcWidgetCalendarTimeline,
ArcWidgetBadge,
} from '@arcrider/arcwidgets-react';
export default function Example() {
const [days, setDays] = useState(14);
const [nested, setNested] = useState(true);
const [stripes, setStripes] = useState(true);
const [selected, setSelected] = useState('Ressource oder Balken anklicken');
const entry = (id: string, title: string, from: number, to: number) => ({
id,
title,
dateFrom: new Date(2026, 8, from).getTime(),
dateTo: new Date(2026, 8, to).getTime(),
clickable: true,
draggable: false,
customLayout: (
),
});
return (
<>
setSelected(`Balken ${index + 1}, Ressourcenzeile ${row + 1}`)
}
onLabelClick={(row) => setSelected(`Ressourcenzeile ${row + 1}`)}
/>
{selected}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetCalendarTimelineData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onEntryClick
Index des Termins, bei Timeline zusätzlich der Ressourcenzeile.
```typescript
onEntryClick?: (row_index: number, entry_index: number) => void;
```
### onEntryDragSave
Drag-Ende mit ursprünglichen Daten. Keine vollständigen neuen Zielzeiten; siehe Hinweise zur Persistenz.
```typescript
onEntryDragSave?: (
row_index: number,
entry_index: number,
start_data: ArcWidgetCalendarTimelineDragStart,
row_change: ArcWidgetCalendarTimelineRowChange
) => void;
```
### onLabelClick
Indizes der geklickten Ressourcenzeile und Beschriftungsspalte.
```typescript
onLabelClick?: (row_index: number, column_index: number) => void;
```
### onGhostClick
Position des angeklickten freien Bereichs.
```typescript
onGhostClick?: (row_index: number, column_value: number) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### timeZoneBalance
Korrektur in Stunden; die Beispiele verwenden `0` und lokal erzeugte Tageswerte.
Typ: `number | string`.
### dateSettings
Datumsbereich, Kopfzeilen und Markierungen.
Typ und verschachtelte Felder stehen in `ArcWidgetCalendarTimelineData` unter Datentypen.
### columns
Linke Beschriftungsspalten der Ressourcen.
Typ: `ArcWidgetCalendarTimelineColumn[]`.
### items
Einträge der Auswahl oder der Darstellung; siehe den zugehörigen Datentyp.
Typ: `ArcWidgetCalendarTimelineItem[]`.
### dayWidth
Breite eines Tages auf der Zeitachse.
Typ: `string`.
### zoomSettings
Zoomgrenzen und Bedienelemente.
Typ und verschachtelte Felder stehen in `ArcWidgetCalendarTimelineData` unter Datentypen.
### timeSettings
Zeitbereich und Raster; Einheiten sind Millisekunden.
Typ: `Record`.
### columnWidth
Breite des linken Spaltenbereichs.
Typ: `string`.
### lang
Sprache der Kalenderbeschriftungen.
Typ: `string`.
### styles
Gemeinsame Farben, Abstände und Rahmen; die angebotenen Felder sind widgetspezifisch.
Typ: `ArcWidgetCalendarTimelineStyles | string`.
### borders
Historische Rahmenkonfiguration. Bevorzuge `styles.borders`, sofern vom Widget angeboten.
Typ: `ArcWidgetCalendarTimelineBorders`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
## Verhalten und Grenzen
- Für JSX in Terminen verwende `customLayout`. Die Standardfelder `title`, `subtitle` und `value` werden als Text oder HTML verarbeitet.
- Datumswerte sind Zeitstempel in Millisekunden; Uhrzeiten sind Millisekunden seit Tagesbeginn. Siehe [Datum und Zeit](/docs/react/patterns/react-dates).
- `clickable: true` aktiviert die Auswahl. Ein Callback-Index ist keine Datensatz-ID; löse ihn über deine aktuelle Eintragsliste auf.
- Die derzeitigen Drag-Callbacks enthalten den ursprünglichen Stand (`start_data`), jedoch keine vollständigen neuen Zielzeiten. Das Beispiel setzt deshalb `draggable: false`. Bearbeite Termine über React-State, bis ein vollständiger Persistenzvertrag für Drag & Drop vorliegt.
- `items` enthält Ressourcenzeilen, darin liegen die `timeEntries`. `columns` definiert die linken Beschriftungsspalten.
- `onEntryClick(rowIndex, entryIndex)` verwendet zwei Indizes. `dayWidth` und `zoomSettings` steuern die Skalierung.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export type ArcWidgetCalendarTimelineBorderLine = boolean | {
color?: string;
width?: string;
borderColor?: string;
borderWidth?: string;
borderSize?: string;
enabled?: boolean;
};
export interface ArcWidgetCalendarTimelineBorders {
color?: string;
width?: string;
outer?: ArcWidgetCalendarTimelineBorderLine;
columns?: ArcWidgetCalendarTimelineBorderLine;
rows?: ArcWidgetCalendarTimelineBorderLine;
}
export interface ArcWidgetCalendarTimelineStyles extends ArcWidgetStyles {
borders?: ArcWidgetCalendarTimelineBorders;
headerBackgroundColor?: string;
groupBackgroundColor?: string;
rowBackgroundColor?: string;
mutedColor?: string;
subtleColor?: string;
dayStripes?: boolean | {
enabled?: boolean;
odd?: string;
even?: string;
oddColor?: string;
evenColor?: string;
};
}
export interface ArcWidgetCalendarTimelineColumn {
title?: ArcWidgetSlot;
width?: string;
backgroundColor?: string;
fontColor?: string;
fontSize?: string;
fontWeight?: string | number;
[key: string]: unknown;
}
export interface ArcWidgetCalendarTimelineItemColumn {
title?: ArcWidgetSlot;
subtitle?: ArcWidgetSlot;
clickable?: boolean;
alignX?: string;
alignY?: string;
fontSize?: string;
fontWeight?: string | number;
[key: string]: unknown;
}
export interface ArcWidgetCalendarTimelineGhost {
title?: ArcWidgetSlot;
clickable?: boolean;
position?: 'bottomRight' | 'timeEntry' | string;
styles?: ArcWidgetStyles | string;
[key: string]: unknown;
}
export interface ArcWidgetCalendarTimelineEntryLabel {
value?: string | number;
width?: string | number;
}
export interface ArcWidgetCalendarTimelineTimeEntry {
id?: string | number;
title?: string | ArcWidgetCalendarTimelineEntryLabel;
subtitle?: string | ArcWidgetCalendarTimelineEntryLabel;
value?: string;
customLayout?: ArcWidgetSlot;
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
styles?: ArcWidgetStyles | string;
clickable?: boolean;
draggable?: boolean;
tooltip?: {
value?: ArcWidgetSlot;
width?: string;
maxWidth?: string;
maxHeight?: string;
position?: string;
styles?: ArcWidgetStyles | string;
[key: string]: unknown;
};
[key: string]: unknown;
}
export interface ArcWidgetCalendarTimelineItem {
id: string | number;
title?: ArcWidgetSlot;
subtitle?: ArcWidgetSlot;
columns?: ArcWidgetCalendarTimelineItemColumn[];
timeEntries?: ArcWidgetCalendarTimelineTimeEntry[];
items?: ArcWidgetCalendarTimelineItem[];
highlights?: Array<{
date?: unknown;
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
color?: string;
[key: string]: unknown;
}>;
ghost?: ArcWidgetCalendarTimelineGhost;
[key: string]: unknown;
}
export interface ArcWidgetCalendarTimelineDragStart {
dateFrom?: unknown;
dateTo?: unknown;
timeFrom?: unknown;
timeTo?: unknown;
}
export interface ArcWidgetCalendarTimelineRowChange {
start_row_index: number;
row_index: number;
}
export interface ArcWidgetCalendarTimelineData extends Omit {
height?: string;
timeZoneBalance?: number | string;
dateSettings?: {
header?: {
title?: ArcWidgetSlot | {
value?: ArcWidgetSlot;
customLayout?: unknown;
alignX?: string;
fontSize?: string;
fontColor?: string;
fontWeight?: string | number;
backgroundColor?: string;
[key: string]: unknown;
};
days?: {
compactRanges?: boolean;
monthCompactBelow?: number;
[key: string]: unknown;
};
months?: unknown;
weeks?: unknown;
alignX?: string;
sticky?: string;
stickyPadding?: string;
[key: string]: unknown;
};
highlights?: Array<{
date?: unknown;
weekday?: number;
color?: string;
applyToRows?: boolean;
styles?: ArcWidgetCalendarTimelineStyles | string;
[key: string]: unknown;
}>;
[key: string]: unknown;
};
columns?: ArcWidgetCalendarTimelineColumn[];
items?: ArcWidgetCalendarTimelineItem[];
dayWidth?: string;
zoomSettings?: {
enabled?: boolean;
defaultDayWidth?: string;
minDayWidth?: string;
maxDayWidth?: string;
step?: number | string;
persist?: boolean;
controls?: { enabled?: boolean; [key: string]: unknown };
[key: string]: unknown;
};
timeSettings?: Record;
columnWidth?: string;
lang?: string;
styles?: ArcWidgetCalendarTimelineStyles | string;
borders?: ArcWidgetCalendarTimelineBorders;
borderRadius?: string;
}
export interface ArcWidgetCalendarTimelineProps extends ArcReactWidgetProps {
onEntryClick?: (row_index: number, entry_index: number) => void;
onEntryDragSave?: (
row_index: number,
entry_index: number,
start_data: ArcWidgetCalendarTimelineDragStart,
row_change: ArcWidgetCalendarTimelineRowChange
) => void;
onLabelClick?: (row_index: number, column_index: number) => void;
onGhostClick?: (row_index: number, column_value: number) => void;
}
```
## Einsatzbeispiele
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Calendar Timeline
## AI Defaults (read first)
- **uniqueId**: Required, `"timeline-" + Nr`.
- **height**: Use `"700px"` or `"100%"` when embedded; `"auto"` lets the widget grow with content (Ninox form scrolls).
- **timeZoneBalance**: Set `-1` for German timezone.
- **header**: `dateSettings.header.days` (Tages-Labels). Optional `header.months` / `header.weeks`. **`header.title`**: Titel/Layout oben links über den Spaltennamen (Text, HTML oder Widget) — nicht mehr die Tageszeile. Reiner Text ohne Extra-Typo: **16px / Schriftstärke 400**. Alte Configs mit `header.title.label` (`##day##` …) ohne `value`/`customLayout` gelten weiter als Tageszeile.
- **columns**: Label-Spalten links (Titel im Header, optional `width`); mindestens eine Spalte. Header-Farbe default = `dateSettings.header.days` (`backgroundColor` / `fontColor`); pro Spalte überschreibbar.
- **items**: Ressourcen-Zeilen; jedes Item braucht `id` (eindeutig pro Zeile) und `timeEntries`. Verschachtelung über `items` (max. eine Ebene unterhalb des Parents).
- **dateFrom/dateTo**: Actual date values in timeEntries, not strings.
- **dayWidth**: Default `"120px"`, increase for detailed timelines. Startbreite, wenn kein gespeicherter Zoom existiert; überschreibbar via `zoomSettings.defaultDayWidth`.
- **zoomSettings**: Optional. Zoom ist standardmäßig aktiv (`enabled: false` zum Abschalten). `defaultDayWidth`, `minDayWidth`, `maxDayWidth`, `step`, `persist` (LocalStorage pro `uniqueId`), `controls.enabled` für +/- unten rechts.
- **dragAction**: `recordId` + optional `resourceField` für vertikal; nur **gleiche Verschachtelungstiefe** (`_depth`, z. B. Mitarbeiter ↔ Mitarbeiter auch **über Teams hinweg**). Optional `enabled: false` schaltet Drag für diesen Balken aus. Optional `changeFieldValues` für Zusatzfelder nach erfolgreichem Drag (z. B. Cache-/Trigger-Felder).
- **Uhrzeit mode**: Activated by `timeSettings`, uses `columnWidth` instead of `dayWidth`. `timeFrom`/`timeTo` in milliseconds.
- **styles.borders**: Gleicher Vertrag wie Table (`outer` / `columns` / `rows`). Default: Rahmen an, Zeilenlinien an, **Spaltenlinien aus**. `outer: false` für bündig im Layout. Dark Mode über `backgroundColor`, `headerBackgroundColor`, `fontColor`, `borderColor`.
- **styles.dayStripes**: Default **an** — Tagesspalten abwechselnd Weiß / sehr helles Grau. `false` schaltet aus; `{ odd, even }` setzt eigene Farben. Wochenend-Highlights liegen darüber.
- **Zellen-Hintergrund**: `dateSettings.highlights[]` mit optional `applyToRows: true`; optional `items[].highlights` pro Zeile (`date`, `dateFrom`/`dateTo` bzw. `timeFrom`/`timeTo`).
- **Ghost (Neueinträge)**: Optional **pro Zeile** `items[].ghost` mit **`title`**, **`actions`**, optional **`position`** (Default **`bottomRight`**: kleiner Plus-Button unten rechts in der Spalte), optional **`styles`**. Klick führt `ghost.actions` aus. **Positionen außer `timeEntry`**: Plus erscheint erst bei **Maus über der Spalte** (Spalte wird per Zeilen-`mousemove` erkannt); **Touch**: Ghost bleibt sichtbar. **`timeEntry`**: siehe Abschnitt ghost (Idle nur in leeren Spalten). Details im Abschnitt **ghost**.
- **tooltip** *(pro Balken)*: Optional. Hover-Tooltip mit `value` (Text **oder** Widget-Deskriptor `{ widget, uid, data }`), optional `width` / `maxWidth` / `maxHeight` / `position` / `styles`. Portaliert an `document.body` (kein Clipping). Details im Abschnitt **tooltip**.
Mit dem Widget **Custom Calendar Timeline** bringst du eine ressourcenbasierte Kalenderansicht in deine Ninox-Datenbank. Ressourcen (z. B. Mitarbeiter, Räume, Fahrzeuge) werden als Zeilen dargestellt, die Tage oder Uhrzeiten als Spalten. Termine erscheinen als horizontale Balken – ideal für Einsatzplanung, Kapazitätsübersicht oder Ressourcenplanung.
💡 **Was du mit Custom Calendar Timeline machen kannst:**
- **Ressourcen als Zeilen:** Jede Zeile steht für eine Ressource (Person, Raum, Team, Fahrzeug).
- **Termine als Balken:** Einträge werden horizontal über die Tage gespannt – mit oder ohne Uhrzeit.
- **Uhrzeitmodus:** Zeige statt Tagen Uhrzeitspalten an – ideal für Flottendiagramme und Tageseinsatzplanung.
- **Hierarchische Einträge:** `items` mit Unter-`items` (eine Ebene), flache Zeilen mit Einrückung – Datenmodell wie Gantt.
- **Drag & Drop:** Verschiebe Termine horizontal (Datum/Uhrzeit ändern) oder vertikal (Ressource/Zeile wechseln).
- **Mehrtägige Einträge:** Zeige Projekte, Urlaub oder längere Blöcke über mehrere Tage.
- **Hervorhebung:** Markiere Wochenenden, bestimmte Stunden oder besondere Tage farblich.
- **Individuelles Styling:** Passe Farben, Breiten und Höhen an dein Design an.
📅 **Custom Calendar Timeline** eignet sich besonders für Einsatzplanung, Schichtpläne, Kapazitätsübersichten und **Flottendiagramme** – überall dort, wo du Ressourcen und Termine im Zeitverlauf im Blick behalten willst.
## Anwendungscode
```javascript
let current := this;
arcCustomCalendarTimeline({
uniqueId: "timeline-1",
timeZoneBalance: 0,
lang: "de",
dateSettings: {
startDate: today(),
duration: 30,
highlights: [
{ weekday: 6, color: "rgba(59,130,246,0.06)" },
{ weekday: 0, color: "rgba(59,130,246,0.06)" }
],
header: {
days: {
label: "##weekDayShort## ##day##.",
fontSize: "12px",
fontColor: "#52525b",
fontWeight: "600",
backgroundColor: "#fafafa"
}
}
},
dayWidth: "120px",
rowHeight: "auto",
currentTime: "rgba(59,130,246,0.5)",
height: "700px",
styles: {
backgroundColor: "#ffffff"
},
columns: [
{ title: "Name", width: "200px" },
{ title: "Abteilung", width: "130px" }
],
items: (select Mitarbeiter).[{
id: Nr,
title: Name,
subtitle: Abteilung,
columns: [
{ title: text(Name) },
{ title: text(Abteilung) }
],
timeEntries: (select Termine where Bearbeiter = Nr).[{
title: Bezeichnung,
subtitle: Kunde,
dateFrom: Datum_von,
dateTo: Datum_bis,
timeFrom: Zeit_von,
timeTo: Zeit_bis,
styles: {
backgroundColor: text(Farbe),
color: "#fff",
borderRadius: "6px",
padding: "4px 8px"
},
dragAction: {
recordId: Nr,
dateFrom: fieldId(Nr, "Datum_von"),
dateTo: fieldId(Nr, "Datum_bis"),
resourceField: fieldId(Nr, "Bearbeiter"),
changeFieldValues: [{
fieldId: fieldId(Nr, "CacheTrigger"),
value: now()
}]
},
actions: [{
type: "popup",
recordId: Nr
}]
}]
}]
})
```
## Allgemeine Settings
### uniqueId
Eindeutige Kennung des Widgets. Wichtig, wenn mehrere Timeline-Widgets auf einer Seite verwendet werden.
```javascript
uniqueId: "timeline-1",
```
### timeZoneBalance
Zeitzonenkorrektur in Stunden. Für Deutschland oft `-1`, um die Anzeige an MEZ/MESZ anzupassen.
```javascript
timeZoneBalance: 0,
timeZoneBalance: -1,
```
### lang
Sprache für Datumsformatierung (z. B. Wochentagsnamen).
```javascript
lang: "de",
lang: clientLang(),
```
### height
Höhe des Widget-Containers.
- `"700px"` oder `"100%"` — feste Höhe mit internem Scroll (Standard in Ninox-Embeds).
- `"auto"` — die Timeline wächst mit dem Inhalt; das Ninox-Formular scrollt vertikal (kein innerer Vertikal-Scroll). Horizontal scrollt die Timeline weiterhin innerhalb des Widgets.
- Mit `maxHeight` kann die automatische Höhe begrenzt werden; dann scrollt die Timeline intern vertikal.
```javascript
height: "700px",
height: "100%",
height: "auto",
maxHeight: "600px",
minHeight: "200px",
```
### styles
Rahmen und Gitterlinien leben in **`styles`** — zusammen mit Hintergrund, Radius und Linienfarbe. Gleicher Vertrag wie Custom Table.
Default: abgerundeter Außenrahmen, Zeilenlinien, **keine vertikalen Spaltenlinien** — wie Table.
Jedes Linienfeld ist `true` / `false` **oder** `{ color, width }`.
| Prop | Default | Bedeutung |
|---|---|---|
| `styles.backgroundColor` | — | Fläche inkl. Label-Spalten links |
| `styles.headerBackgroundColor` | = `backgroundColor` | Name/Abteilung + Ecken |
| `styles.groupBackgroundColor` | = Header | Monats-/KW-Zeile |
| `styles.rowBackgroundColor` | = `backgroundColor` | Tagesraster-Zeilen |
| `styles.fontColor` | — | Text links und Fallback für Header |
| `styles.mutedColor` / `subtleColor` | = `fontColor` | Sekundärtext / Untertitel |
| `styles.borderColor` | `#e4e4e7` | Farbe für alle angeschalteten Linien |
| `styles.borderRadius` | `12px` | Eckenradius (nur wenn `outer` an) |
| `styles.borders.outer` | `true` | Außenrahmen. `false` = bündig im Layout |
| `styles.borders.columns` | `false` | Vertikale Linien im Tagesgitter und zwischen Label-Spalten. Die Kante Labels → Raster bleibt an. |
| `styles.borders.rows` | `true` | Horizontale Ressourcenlinien |
| `styles.dayStripes` | `true` | Tagesspalten abwechselnd Weiß / sehr helles Grau. `false` = aus. `{ odd, even }` = eigene Farben. |
```javascript
styles: {
backgroundColor: "#ffffff",
borderRadius: "12px",
borderColor: "#e4e4e7",
borders: {
outer: true,
columns: false,
rows: true
}
}
// In einem Layout / Card:
styles: { borders: { outer: false } }
// Tagesgitter wieder an:
styles: { borders: { columns: true } }
// Tagesspalten-Zebra aus:
styles: { dayStripes: false }
// Dunkler Hintergrund:
styles: {
backgroundColor: "#18181b",
borderColor: "#3f3f46",
borders: {
outer: true,
rows: { color: "#27272a" }
}
}
```
## dateSettings – Zeitraum & Darstellung
### startDate
Startdatum der Timeline. Ab diesem Tag werden die Spalten angezeigt.
```javascript
startDate: today(),
startDate: date(2025, 2, 1),
```
### duration
Anzahl der angezeigten Tage. Wird ignoriert, wenn `endDate` gesetzt ist.
```javascript
duration: 30,
duration: 14,
```
### endDate
*(Optional)* Enddatum der Timeline. Hat Vorrang vor `duration`.
```javascript
dateSettings: {
startDate: date(2025, 2, 1),
endDate: date(2025, 2, 28)
}
```
### highlights
Farbliche Hervorhebung bestimmter Tage – z. B. Wochenenden oder Feiertage.
```javascript
highlights: [
{ weekday: 6, color: "rgba(59,130,246,0.06)" },
{ weekday: 0, color: "rgba(59,130,246,0.06)" },
{ date: date(2025, 12, 24), color: "rgba(239,68,68,0.1)" }
],
```
- `weekday`: 0 = Sonntag, 6 = Samstag
- `date`: Konkretes Datum
- `dateFrom` / `dateTo`: Datumsbereich (optional statt einzelnem `date`)
- `color`: CSS-Farbe (HEX oder rgba)
- **`applyToRows`** *(optional)*: `true` – dieselbe Hervorhebung wird **in der Zeilenfläche** (hinter den Termin-Balken) für **alle** Ressourcen-Zeilen gezeichnet, nicht nur in der Kopfzeile. Ohne dieses Flag bleibt das Verhalten wie bisher (nur Header).
**Im Uhrzeitmodus** zusätzlich:
- `hour`: Stunde (0–23) für Hervorhebung bestimmter Stunden-Spalten
- `timeFrom` / `timeTo`: Zeitbereich in Millisekunden (wie bei `timeEntries`), z. B. Mittagspause
```javascript
highlights: [
{ hour: 12, color: "rgba(239,68,68,0.1)" }
]
```
```javascript
highlights: [
{ weekday: 6, color: "rgba(59,130,246,0.06)", applyToRows: true },
{ date: date(2025, 12, 24), color: "rgba(239,68,68,0.1)", applyToRows: true },
{ timeFrom: time(12, 0), timeTo: time(13, 0), color: "rgba(156,163,175,0.15)", applyToRows: true }
],
```
### highlights pro Zeile (`items[].highlights`)
Neben den globalen `dateSettings.highlights` kann jede Ressourcen-Zeile ein eigenes Array **`highlights`** haben – z. B. Urlaub oder Krankenstand nur für einen Mitarbeiter. Die gleichen Felder wie oben gelten; **`applyToRows` ist hier nicht nötig** (gilt immer nur für diese Zeile).
```javascript
items: (select Mitarbeiter).[{
id: Nr,
title: Name,
highlights: [
{ dateFrom: Urlaub_von, dateTo: Urlaub_bis, color: "rgba(34,197,94,0.15)" },
{ date: Krank_Tag, color: "rgba(239,68,68,0.12)" }
],
timeEntries: [...]
}]
```
**Uhrzeitmodus:** z. B. Sperr- oder Wartungsfenster mit `timeFrom` / `timeTo`.
### header
Der `header`-Block steuert alle Kopfzeilen der Timeline. Er besteht aus drei optionalen Unterblöcken: `months`, `weeks` und `days`. Alle drei haben dieselbe Struktur und können unabhängig voneinander aktiviert werden. Die Reihenfolge im Widget ist immer: **Monate → Kalenderwochen → Tage** (von oben nach unten).
```javascript
header: {
months: {
visible: true,
label: "##monthLong## ##year##",
fontSize: "11px",
fontColor: "#555",
fontWeight: "600",
backgroundColor: "#ececec",
highlights: [
{ month: 5, color: "rgba(59,130,246,0.12)" }
]
},
weeks: {
visible: true,
label: "KW ##week##",
fontSize: "11px",
fontColor: "#555",
backgroundColor: "#f2f2f2",
highlights: [
{ week: 18, color: "rgba(239,68,68,0.1)" }
]
},
days: {
visible: true,
label: "##weekDayShort## ##day##.",
fontSize: "12px",
fontColor: "#333",
fontWeight: "600",
backgroundColor: "#f9f9f9"
}
}
```
`header.title` sitzt **oben links** über den Spaltennamen (Name, Abteilung), in einer Fläche so hoch wie Monat- + KW-Zeile. Spaltennamen stehen in **derselben Zeile wie die Tage**, mit Linie nach oben. Reiner Text ohne `fontSize` / `fontWeight` / Custom-Layout: **16px, Schriftstärke 400**.
```javascript
header: {
title: {
value: "Teamplanung",
alignX: "left"
}
}
```
| Property | Beschreibung |
|---|---|
| `value` | Text oder HTML. Alternativ ein Widget-Deskriptor `{ widget, uid, data }`. |
| `customLayout` | HTML oder Widget-Deskriptor (wie in Label-Zellen). Hat Vorrang vor `value`. |
| `alignX` | `"left"` \| `"center"` \| `"right"` |
| `fontSize` / `fontColor` / `fontWeight` / `backgroundColor` | Typo und Fläche des Slots |
Ohne Monat/KW gibt es den Slot nicht (keine extra Zeile). **Legacy:** Nur `header.title` mit `label` (`##day##` …) und ohne `value`/`customLayout` steuert weiter die **Tageszeile**, wenn `header.days` fehlt.
Alle drei Zeilen-Blöcke (`months` / `weeks` / `days`) sind optional. Wird ein Block weggelassen, ist er nicht aktiv.
**Gemeinsame Properties (je Unterblock):**
| Property | Beschreibung |
|---|---|
| `visible` | `false` blendet die Zeile aus (Standard: `true`) |
| `label` | Anzeigetext mit Platzhaltern (s. u.) |
| `alignX` | `"left"` \| `"center"` \| `"right"` – horizontale Ausrichtung in der Zelle bzw. Gruppe. Standard: **`"left"`** (Monat/KW-Gruppen und Tage). |
| `fontSize` | Schriftgröße, z. B. `"12px"` |
| `fontColor` | Schriftfarbe |
| `fontWeight` | Schriftstärke, z. B. `"600"` |
| `backgroundColor` | Hintergrund der gesamten Zeile bzw. Monats-/KW-Gruppe. **`days`**: färbt u. a. die Tages-Headerzeile; bei **`days.sticky: "left"`** hat der **Beschriftungs-`span` kein eigenes** undurchsichtiges `backgroundColor`, damit **`dateSettings.highlights`** (Farb-Overlay pro Tages-**`div`**) hinter dem Text sichtbar bleibt. |
| `highlights` | Hervorhebungen pro Monats- bzw. KW-Gruppe (s. u.) – **nur** für `months` / `weeks` |
| `sticky` | Optional für **`months`**, **`weeks`** und **`days`**: `sticky: "left"` hält die Bezeichnung bei horizontalem Scrollen sichtbar (CSS `position: sticky`); der horizontale Abstand setzt an den linken sichtbaren Rand des Zeitbereichs, berechnet als **Summe aller linken `columns`-Breiten** + `stickyPadding`. Ohne `sticky` steuert nur `alignX` die Ausrichtung. |
| `stickyPadding` | Zusätzlicher Abstand in px (Zahl) oder z. B. `"12px"`, addiert auf die Labelspalten-Breite für `sticky: "left"`. Wenn weggelassen, wird **+8** px addiert. |
| `hideBelow` | Optional. **`days`**: Spaltenbreite in px — darunter verschwindet der Tages-Text; die Zeile bleibt als Trenner. **Default:** pro Tag eine vertikale Linie (`data-arc-day-ticks`). Mit **`compactRanges: true`** stattdessen KW- bzw. Monats-Ranges (`01.09. - 07.09.`). Default-Schwelle: 36. **`weeks`/`months`**: minimale **Gruppenbreite** in px, unter der der Label-Text ausgeblendet wird — die Zeile bleibt. Defaults: `weeks` 44, `months` 72. |
| `compactRanges` | Optional, nur **`days`**. `true` = beim Rauszoomen Tage zu KW-/Monats-Ranges zusammenfassen. Default: aus (Tick-Linien). |
| `monthCompactBelow` | Optional, nur **`days`**, nur mit `compactRanges`. Spaltenbreite in px — darunter wechselt die Range von KW auf Monat. Default: 14. |
| `labelBreakpoints` | Optional, nur **`days`**: Array `{ below, label }` — bei mittlerer Spaltenbreite kürzeres Tages-Label (bevor der Text ganz verschwindet). |
**Hinweis:** `dateSettings.highlights` färben pro Tag die **Tages-Headerzelle** (`div`, optional mit `applyToRows` auch die Zeilenfläche). In Kombination mit `header.days.sticky: "left"` bitte `backgroundColor`-Hinweis in der Tabelle beachten.
**Platzhalter für `days.label`:**
- `##weekDayShort##` – Kurzer Wochentag (Mo, Di, …)
- `##weekDayLong##` – Langer Wochentag (Montag, Dienstag, …)
- `##day##` – Tag (1–31)
- `##monthShort##` – Kurzer Monat (Jan, Feb, …)
- `##monthLong##` – Langer Monat (Januar, Februar, …)
- `##year##` – Jahr
**Platzhalter für `weeks.label`:**
- `##week##` – Kalenderwochennummer (01–53, zweistellig mit führender Null)
- `##year##` – Jahr
**Platzhalter für `months.label`:**
- `##monthLong##` – Langer Monatsname (Januar, Februar, …)
- `##monthShort##` – Kurzer Monatsname (Jan, Feb, …)
- `##year##` – Jahr
**`highlights` pro Unterblock:**
```javascript
months: {
highlights: [
{ month: 5, color: "rgba(59,130,246,0.12)" } // Mai hervorheben (1 = Januar)
]
},
weeks: {
highlights: [
{ week: 18, color: "rgba(239,68,68,0.1)" } // KW 18 hervorheben
]
}
```
- `months.highlights`: `{ month: N }` – N = 1 (Januar) bis 12 (Dezember)
- `weeks.highlights`: `{ week: N }` – N = ISO-Kalenderwochennummer
## Layout-Parameter
### dayWidth
Breite einer Tages-Spalte (Startwert). Wenn Zoom aktiv ist und der Nutzer noch keine Zoomstufe gespeichert hat, gilt `zoomSettings.defaultDayWidth` — sonst dieser Wert.
```javascript
dayWidth: "120px",
dayWidth: "90px",
```
### zoomSettings
Steuert interaktiven Zoom und die initiale Spaltenbreite. Die gewählte Zoomstufe wird pro `uniqueId` im LocalStorage gespeichert (zusammen mit Scroll-Position), sofern `persist` nicht `false` ist.
```javascript
zoomSettings: {
enabled: true,
defaultDayWidth: 48,
minDayWidth: 16,
maxDayWidth: 200,
step: 8,
persist: true,
controls: {
enabled: true,
position: "bottomRight"
}
}
```
- **enabled**: `false` deaktiviert Zoom komplett — nur statisches `dayWidth`, keine Controls.
- **defaultDayWidth**: Initiale Breite in px, wenn kein gespeicherter Wert existiert.
- **minDayWidth** / **maxDayWidth**: Unter- und Obergrenze der Spaltenbreite.
- **step**: px-Schritt pro Klick auf +/−.
- **persist**: Zoomstufe in LocalStorage merken (Standard: `true`).
- **controls**: Floating-Buttons unten rechts im Widget.
Mausrad/Pinch-Zoom ist in v1 nicht enthalten (geplant).
### rowHeight
Höhe einer Ressourcen-Zeile. `"auto"` passt sich dem Inhalt an.
```javascript
rowHeight: "auto",
rowHeight: "36px",
```
### labelWidth
Standard-Breite für **eine** Label-Spalte, wenn `columns` fehlt oder wenn in `columns[i]` kein `width` gesetzt ist. Standard: `"120px"`.
```javascript
labelWidth: "150px",
```
### currentTime
Farbe des Balkens, der die aktuelle Uhrzeit markiert. Leer oder `false` blendet ihn aus.
```javascript
currentTime: "rgba(59,130,246,0.5)",
currentTime: "",
```
## items – Ressourcen und Termine
`items` ist ein Array von Ressourcen-Zeilen. Jede Zeile hat `timeEntries` (Balken). Optional: `items` (Kinder, eine Ebene) und `columns` (Zelltexte pro Label-Spalte).
### Struktur einer Zeile
```javascript
{
id: Nr,
title: Name,
subtitle: Abteilung,
fontSize: "13px",
fontWeight: "normal",
columns: [
{ title: text(Name) },
{ title: text(Abteilung) }
],
styles: {},
highlights: [],
timeEntries: [...],
items: [...]
}
```
- **id** *(Pflicht)*: Eindeutige ID (z. B. Record-Nr). Wird für Drag & Drop (`resourceField`) und **collapsible** benötigt.
- **title** / **subtitle**: Fallback für die **erste** Label-Spalte, wenn `columns` fehlt oder die erste Zelle leer ist.
- **fontSize** / **fontWeight** *(optional, Item-Ebene)*: Standard-Typo für alle Label-Zellen dieser Zeile, sofern weder Top-Level-Spalte noch `columns[i]` etwas setzen. Reihenfolge der Priorität (höher zuerst): **`columns[i]`** → **Item** `fontSize`/`fontWeight` → **`styles.fontSize`/`styles.fontWeight`**.
- **columns** *(pro Zeile)*: Ein Objekt pro Label-Spalte (gleiche Anzahl wie Top-Level `columns`): `title`, `subtitle`, optional **`customLayout`** (HTML für diese Zelle), `actions`, optional `alignX`, `alignY`, `fontSize`, `fontWeight`.
- **styles**: Optional (z. B. Zeilen-Hintergrund; `fontSize`/`fontWeight` hier wirken als letzte Typo-Fallbacks).
- **highlights** *(optional)*: Zellen-Hintergrund für diese Zeile (Abwesenheiten, Sperrzeiten); siehe Abschnitt **highlights pro Zeile**.
- **timeEntries**: Termine/Balken in dieser Zeile. **Horizontaler Abstand:** fest **4px** zur Spaltenkante (wie das Zeilen-Padding oben/unten); bei **mehrspaltigen** Balken nur am **äußeren** Anfang und Ende, nicht zwischen den Tagen (nicht über `timeEntries[].styles` änderbar).
- **items**: Optional. Unterzeilen (eine Ebene).
### Struktur eines timeEntry (Termin/Balken)
```javascript
{
title: Bezeichnung,
subtitle: Kunde,
dateFrom: Datum_von,
dateTo: Datum_bis,
timeFrom: Zeit_von,
timeTo: Zeit_bis,
styles: {},
dragAction: {},
actions: [],
tooltip: {},
customLayout: "",
value: ""
}
```
- **title**: Text im Balken, oder Objekt `{ value: …, width: … }` (siehe unten). Bei Zeitangaben kann `##entrytime##` verwendet werden.
- **subtitle**: Optional. Zweiter Textblock im Balken (String oder Objekt wie bei **title**).
- **direction** *(optional)*: `"vertical"` oder `"horizontal"` – Titel und Subtitle **untereinander** oder **nebeneinander**.
- **Default bei Plain-Strings** (ohne Objekt-Form): `"vertical"` — Subtitle bleibt sichtbar, auch wenn der Titel lang ist.
- **Default bei Objekt-Form** (`{ value, width }`): `"horizontal"` — sinnvoll für Breite-Paarung (z. B. Titel + Uhrzeit nebeneinander).
- Explizit setzen überschreibt den Default immer.
- **dateFrom**, **dateTo**: Start- und Enddatum (Pflicht).
- **timeFrom**, **timeTo**: Optional. Uhrzeit in Millisekunden (0 = Mitternacht). Ohne Angabe wird der Eintrag als ganztägig dargestellt.
- **styles**: CSS-ähnliche Eigenschaften (backgroundColor, color, borderRadius, padding).
- **dragAction**: Konfiguration für Drag & Drop.
- **actions**: Array von Aktionen beim Klick auf den Balken (wie bei anderen Widgets). Das frühere einzelne Feld **`clickAction`** wird weiterhin unterstützt und wie ein Eintrag in `actions` ausgeführt.
- **tooltip**: Optional. Hover-Overlay mit zusätzlichen Infos (siehe unten).
- **customLayout**: Optional. Eigenes Layout statt title/subtitle/value.
- **value**: Optional. Zusätzlicher HTML-Inhalt im Balken (nach dem Titel/Subtitle-Block).
**Objekt-Form für `title` / `subtitle`:** `{ value: TextOderHtml, width: "fraction" | "auto" | CSS-Länge }`
- **`value`**: Anzuzeigender Text oder HTML (wie bisher); `##entrytime##` möglich.
- **`width`** *(optional, Default `"fraction"`)**:
- **`"fraction"`** – nutzt den **verbleibenden** Platz in der Zeile; langer Text wird mit Ellipsis gekürzt.
- **`"auto"`** – **Inhaltsbreite**; schrumpft nicht zugunsten des Partners (z. B. für Uhrzeiten, die voll sichtbar bleiben sollen). Sehr langer Text kann am Balkenrand trotzdem mit Ellipsis enden.
- **CSS-Länge** (z. B. `"72px"`, `"4.5rem"`) – feste Basisbreite (`flex-basis`) für diesen Block.
Sind **title** und **subtitle** nur **Strings** (ohne Objekt) und ist **direction** nicht gesetzt, stehen sie **untereinander**. Nutzt mindestens ein Feld die Objekt-Form (ohne `direction`), stehen sie **nebeneinander** (Flex + `width`). Mit **`direction: "horizontal"`** bzw. **`"vertical"`** erzwingst du die Ausrichtung.
```javascript
title: { value: text(Bezeichnung), width: "fraction" },
subtitle: { value: "##entrytime##", width: "auto" },
```
### tooltip – Hover-Info am Balken
Optionaler Hover-Tooltip pro `timeEntry`. Der Overlay hängt an `document.body` (Pfeil + Schatten), wird nicht vom Balken abgeschnitten und bleibt beim Hovern stabil offen — auch wenn Ninox im Hintergrund neu rendert. Mit der Maus in den Tooltip fahren ist möglich (interaktive Widgets/Buttons).
```javascript
tooltip: {
value: "Kunde: Meier GmbH" + newline() + "Status: geplant",
width: "280px",
maxWidth: "360px",
maxHeight: "300px",
position: "auto",
styles: {
backgroundColor: "#1f2937",
color: "#fff"
},
trigger: "hover"
}
```
- **value** *(Pflicht)*: Inhalt — **Text/HTML-String** **oder** Next-Gen-Deskriptor `{ widget: "arc-widget-layout", uid: "tt-" + Nr, data: { … } }`. Volle Registry-ID (`arc-widget-…`), Config unter **`data`**, eigene `uid`. Nested Widgets inkl. Actions funktionieren.
- **width** / **maxWidth** / **maxHeight**: Optional. CSS-Längen; bei `maxHeight` scrollt der Inhalt intern.
- **position**: `"top"` | `"bottom"` | `"left"` | `"right"` | `"auto"` (Default `"auto"` — bevorzugt oben, kippt bei Platzmangel).
- **styles**: Optional. u. a. `backgroundColor`, `color`, `borderRadius`, `padding`, `boxShadow`. Für eine durchgehende Kontur um Box **und** Pfeil: `borderWidth` + `borderColor` (SVG-`stroke` auf der Bubble-Shape).
- **trigger**: v1 nur `"hover"` (reserviert für spätere `"click"`).
Technisch: der Tooltip ist eine **SVG-Bubble** (ein Path für abgerundetes Rechteck + integrierten Pfeil), portaliert an `document.body`. Fill und Stroke gelten für die ganze Form — kein separates CSS-Dreieck.
Klick auf den Balken führt weiterhin `actions` aus. Ohne `tooltip` ändert sich nichts.
#### Beispiele
**1) Dark + Border (Text)**
```javascript
tooltip: {
value: "Kunde: Meier GmbH" + newline() +
"Status: geplant" + newline() +
"Notiz: Parkplatz hinter dem Gebäude",
width: "280px",
position: "auto",
styles: {
backgroundColor: "#1f2937",
color: "#fff",
borderWidth: "1px",
borderColor: "rgba(255,255,255,0.28)"
}
}
```
**2) Light Soft (hell + Border)**
```javascript
tooltip: {
value: html("Wartung Anlage Nord Dauer: 3 Tage Ersatzteil: Filterkit #442"),
maxWidth: "300px",
position: "bottom",
styles: {
backgroundColor: "#ffffff",
color: "#1f2937",
borderWidth: "1px",
borderColor: "rgba(15,23,42,0.14)",
borderRadius: "10px",
boxShadow: "0 10px 28px rgba(15, 23, 42, 0.12)"
}
}
```
**3) Light + Widget (vertikal, Button volle Breite)**
```javascript
tooltip: {
value: {
widget: "arc-widget-layout",
uid: "tt-" + Nr,
data: {
direction: "vertical",
gap: "8px",
width: "100%",
blocks: [
{
width: "100%",
value: html("
Termin-Details
")
},
{
width: "100%",
value: html("
Kunde: Schmidt AG Thema: Angebot Q3
")
},
{
width: "100%",
value: {
widget: "arc-widget-button",
uid: "tt-btn-" + Nr,
data: {
title: "Öffnen",
width: "100%",
height: "30px",
fontSize: "12px",
backgroundColor: "#3b82f6",
fontColor: "#fff",
borderRadius: "6px",
actions: [{ type: "popup", recordId: Nr }]
}
}
}
]
}
},
width: "240px",
position: "top",
styles: {
backgroundColor: "#ffffff",
color: "#0f172a",
borderWidth: "1px",
borderColor: "rgba(15,23,42,0.16)",
borderRadius: "12px",
padding: "12px"
}
}
```
**4) Position links / rechts**
```javascript
tooltip: {
value: "Zusatzinfo neben dem Balken",
width: "240px",
position: "right", // oder "left"
styles: {
backgroundColor: "#ffffff",
color: "#0f172a",
borderWidth: "1px",
borderColor: "rgba(15,23,42,0.16)"
}
}
```
Tipp: Am Balken oft `direction: "vertical"` setzen, damit Titel und Subtitle untereinander stehen und der Subtitle sichtbar bleibt.
### styles – Styling der Termin-Balken
```javascript
styles: {
backgroundColor: "#3b82f6",
color: "#fff",
borderRadius: "6px",
padding: "4px 8px"
},
```
### dragAction – Verschieben von Terminen
Definiert, welche Felder beim Ziehen aktualisiert werden.
```javascript
dragAction: {
recordId: Nr,
dateFrom: fieldId(Nr, "Datum_von"),
dateTo: fieldId(Nr, "Datum_bis"),
resourceField: fieldId(Nr, "Bearbeiter"),
enabled: true,
changeFieldValues: [{
fieldId: fieldId(Nr, "CacheTrigger"),
value: now()
}]
},
```
- **recordId**: Record-ID des Termins (meist `Nr`).
- **dateFrom**, **dateTo**: Feld-IDs für Start- und Enddatum. Werden beim horizontalen Verschieben aktualisiert.
- **resourceField**: Optional. Feld-ID für die Ressource (z. B. Bearbeiter). Wird beim vertikalen Verschieben (Zeilenwechsel) mit der `id` der Ziel-Zeile aktualisiert – **nur wenn** Start- und Zielzeile dieselbe **Tiefe** in der `items`-Hierarchie haben (`_depth` gleich). Erforderlich z. B., damit kein Termin von einer Team-Zeile auf eine Mitarbeiter-Zeile (oder umgekehrt) gezogen wird; **Mitarbeiter unter Team A → Mitarbeiter unter Team B** ist erlaubt.
- **enabled**: Optional. `false`: kein Drag für diesen Balken (z. B. Parent-Summen). Wenn weggelassen, ist Drag aktiv, sobald `dragAction` gesetzt ist.
- **changeFieldValues**: Optional. Array von `{ fieldId, value }` – wird **nach** einem erfolgreichen Drag geschrieben (Datum/Zeit und/oder Ressource haben sich geändert). Typischer Einsatz: Cache- oder Trigger-Felder aktualisieren. Aufbau wie bei Create-Actions (`ghost.actions`).
⚠️ **Hinweis:** Ohne `dragAction` ist Drag & Drop deaktiviert. Vertikales Ziehen zwischen **verschiedenen Tiefen** (z. B. Team-Zeile ↔ Mitarbeiter-Zeile) ist nicht möglich; innerhalb derselben Tiefe (z. B. nur Mitarbeiter-Zeilen) auch **über verschiedene Parents** (Teams).
### actions – Klick auf Termin
```javascript
actions: [{
type: "popup",
recordId: Nr
}],
```
- **type**: `"popup"` öffnet den Datensatz in einem Popup.
- **recordId**: Record-ID des angeklickten Termins.
Mehrere Einträge im Array werden nacheinander ausgeführt. **Legacy:** Ein einzelnes **`clickAction`**-Objekt (ohne Array) funktioniert weiterhin.
### actions – Klick auf Label-Zelle
In **`items[].columns[i]`** kann optional **`actions`** gesetzt werden. Ist das Array nicht leer, löst ein Klick auf die Zelle dieselben Ninox-Aktionen aus. **Hinweis:** In der **ersten** Label-Spalte hat bei **eingeklappten Gruppen** (`collapsible`) der Klick Vorrang zum Auf-/Zuklappen; dort werden keine zusätzlichen `actions` auf der Zelle ausgeführt.
```javascript
items: (select Fahrzeuge).[{
id: Nr,
columns: [
{ title: text(Bezeichnung), subtitle: "Fahrzeug" },
{
title: "⌂",
actions: [{
type: "popup",
recordId: Nr
}]
}
],
timeEntries: [...]
}]
```
`columns` gehört zur jeweiligen Zeile unter **`items`**. Ein Klick auf die zweite Spalte (hier **⌂**) öffnet den Datensatz der Zeile (`Nr`). Beliebig viele Einträge im `actions`-Array werden nacheinander ausgeführt.
### ghost – Zeilen-Balken für Neueinträge (Wrapper)
Auf **Ebene jedes Eintrags in `items[]`** (nicht in `columns[]`) kann optional ein Objekt **`ghost`** gesetzt werden – **unabhängig pro Zeile** (Ressource). Eine Zeile ohne `ghost` hat keinen Anlege-Streifen.
**Felder:**
- **`title`** – optional, wird als **Browser-Tooltip** (`title`-Attribut) auf dem Plus-Button genutzt (z. B. „Termin anlegen“).
- **`position`** – optional, steuert Anzeige und Layout des Ghost-**Buttons** pro Spalte:
- **`bottomRight`** (Default, kann weggelassen werden) – kleiner quadratischer Button (**28×28 px**), **absolut** in der jeweiligen Spalte unten rechts; nimmt **keine** volle Spaltenbreite ein. Der Button sitzt **außerhalb des CSS-Grids** der Zeile (absolut zur Zeile), damit **timeEntries** in derselben Grid-Zeile bleiben wie ohne Ghost. **Stacking:** der Button liegt knapp **über** normalen Balken (`z-index` **11**), **unter** Balken-Hover (**10**) und **aktivem/Drag**-Balken (**100**).
- **`bottomLeft`**, **`topRight`**, **`topLeft`** – gleicher Button, andere Ecke der Spalte.
- **`timeEntry`** – **klassisches Verhalten**: volle Spaltenbreite in der **ersten Grid-Zeile** (mit **4px** horizontalem Abstand wie die Termin-Balken), schiebt sichtbare Termin-Balken in die nächste Zeile (`align-content: start` auf der Zeile).
- **`actions`** – Pflicht, mindestens eine Ninox-Aktion; typischerweise **`type: "create"`** mit vorbefüllten Feldern. Ein Klick auf den **Plus-Button** führt diese Aktionen mit dem **Wert dieser Spalte** aus (siehe Platzhalter).
- **`styles`** – optional, Objekt mit **CSS-Eigenschaften in camelCase** (wie bei **`timeEntries[].styles`**), z. B. `backgroundColor`, **`fontColor`** (Textfarbe inkl. Plus-Icon über `currentColor`), `fontSize`, `fontWeight`, `borderRadius`, **`paddingX`** / **`paddingY`** (werden zu `padding` zusammengesetzt) oder **`padding`** (Shorthand), `border`, `boxShadow`. Legacy-**`color`** wird wie **`fontColor`** auf die Schriftfarbe gemappt; ist **`fontColor`** gesetzt, hat es Vorrang. Werden auf den Button gelegt; **`gridColumn` / `gridRow`** setzt das Widget für die Rasterplatzierung (überschreibt ggf. eigene Werte in `styles`).
**Darstellung (Default `bottomRight` u. a.):** Pro Spalte ein **absolut positionierter, klick-durchlässiger Bereich** über der Zeile (kein Grid-Item – verhindert Verschiebung der Balken). Der **Plus-Button** ist **weiß**, mit **leichtem Schatten**, Ecke per `position`. **Spalten-Hover (Maus in der Spalte):** Button wird sichtbar mit **halbtransparentem weißem Hintergrund** und **`backdrop-filter`-Weichzeichnung** (Frosted-Glass). **Direkt über dem Button:** undurchsichtiges **Weiß**, kein Blur – volle Lesbarkeit. Über **`styles`** kannst du z. B. `backgroundColor` setzen (überschreibt die Standardfarben).
**Darstellung (`timeEntry`):** Wie ein schmaler **Balken** über die Spaltenbreite in Zeile 1 (mit **4px** Rand links/rechts wie die Termin-Balken); **timeEntries** der Zeile beginnen darunter.
**Sichtbarkeit / Hover:**
- **Alle Positionen außer `timeEntry`:** Der Plus-Button ist **standardmäßig unsichtbar** und erscheint erst, wenn die **Maus irgendwo in dieser Tag-/Zeitspalte** ist (auch über einem Balken); die Spalte wird anhand der Mausposition auf der **Zeile** ermittelt. Auf **Touch-Geräten** (kein präzises Hover) bleiben die Ghost-Buttons **sichtbar**.
- **`timeEntry`:** Für jede Spalte wird getrennt geprüft, ob ein **sichtbarer** Termin-Balken in die Spalte reicht. **Ohne** Balken: bei **`@media (hover: hover)`** ist der Ghost-Balken zunächst per Opacity verborgen, bis die Maus über die **Ghost-Zelle** fährt. **Mit** Balken in der Spalte: der Ghost-Balken bleibt sichtbar. Auf **Touch** bleiben Ghost-Elemente sichtbar.
**Platzhalter** (in beliebigen String-Werten innerhalb der Action, rekursiv):
- **`##columnValue##`** – Millisekundenwert der **Spalte unter dem Klick**: im **Tag-Modus** Tagesbeginn (`startDate` + Spaltenindex), im **Uhrzeit-Modus** Beginn des Zeitslots (`startTime` + Index × `amount`).
- **`##clickedDate##`** – Alias mit gleicher Semantik (Kompatibilität zu Calendar Grid / Week).
```javascript
items: (select Mitarbeiter).[{
id: Nr,
ghost: {
position: "bottomRight",
title: "Termin anlegen",
styles: {
backgroundColor: "rgba(0, 0, 0, 0.08)",
fontColor: "#333333",
borderRadius: "6px",
paddingY: "4px",
paddingX: "8px"
},
actions: [{
type: "create",
tableId: "B",
popup: true,
changeFieldValues: [
{ fieldId: fieldId(Nr, "Datum"), value: "##columnValue##" },
{ fieldId: fieldId(Nr, "Bearbeiter"), value: number(Nr) }
]
}]
},
timeEntries: [...]
}]
```
Klicks auf **Termin-Balken** (timeEntries) lösen weiterhin nur die **`actions`** des jeweiligen Balkens aus, nicht `ghost.actions`.
**Beispiel – Uhrzeitmodus:** `##columnValue##` ist der **Beginn des geklickten Zeitslots** in Millisekunden (wie bei `timeFrom` in den Balken).
```javascript
arcCustomCalendarTimeline({
uniqueId: "timeline-fleet-neu",
mode: "time",
timeSettings: {
startTime: 6,
duration: 12,
amount: 0.25
},
columnWidth: "60px",
rowHeight: "36px",
height: "700px",
dateSettings: {
header: {
title: {
label: "##hour##:##minute##",
fontSize: "11px",
fontColor: "#333"
}
}
},
columns: [
{ title: "Fahrzeug", width: "160px" },
{ title: "Info", width: "80px" }
],
items: (select Fahrzeuge).[{
id: Nr,
ghost: {
title: "Neue Fahrt",
actions: [{
type: "create",
tableId: "B",
popup: true,
changeFieldValues: [
{ fieldId: fieldId(Nr, "Startzeit"), value: "##columnValue##" },
{ fieldId: fieldId(Nr, "Fahrzeug"), value: number(Nr) }
]
}]
},
timeEntries: [...]
}]
})
```
Alternativ kannst du **`##clickedDate##`** statt `##columnValue##` verwenden – beide werden gleich aufgelöst.
## weekStart
Starttag der Woche (0 = Sonntag, 1 = Montag, …). Beeinflusst die Sortierung der Tage.
```javascript
weekStart: 1,
```
## timeSettings – Uhrzeitmodus (Time Mode)
Wenn du statt Tagen **Uhrzeiten** als Spalten anzeigen möchtest, kannst du den Uhrzeitmodus aktivieren. Das ist ideal für **Flottendiagramme**, **Schichtpläne** oder **Tageseinsatzplanung**, bei denen die X-Achse einen einzelnen Tag darstellt.
Der Uhrzeitmodus wird automatisch aktiviert, sobald `timeSettings` gesetzt ist – oder explizit mit `mode: "time"`.
```javascript
arcCustomCalendarTimeline({
uniqueId: "fleet-timeline",
mode: "time",
timeSettings: {
startTime: 6,
duration: 12,
amount: 0.25
},
columnWidth: "60px",
rowHeight: "36px",
height: "700px",
dateSettings: {
header: {
title: {
label: "##hour##:##minute##",
fontSize: "11px",
fontColor: "#333"
}
}
},
columns: [
{ title: "Fahrzeug / Tag", width: "160px" },
{ title: "Info", width: "80px" }
],
items: (select Fahrzeuge).[{
id: Nr,
title: Bezeichnung,
fontSize: "12px",
fontWeight: "600",
columns: [
{ title: text(Bezeichnung), subtitle: "Fahrzeug" },
{ title: "⌂" }
],
items: (select Einsatztage where Fahrzeug = Nr).[{
id: Nr,
title: Wochentag,
fontSize: "11px",
columns: [
{ title: text(Wochentag) },
{ title: "" }
],
timeEntries: (select Fahrten where Einsatztag = Nr).[{
title: Route,
timeFrom: Startzeit,
timeTo: Endzeit,
styles: {
backgroundColor: text(Farbe),
color: "#fff"
}
}]
}]
}]
})
```
### startTime
Ab welcher Stunde die Zeitleiste beginnt (z. B. `6` = 06:00 Uhr).
```javascript
startTime: 6,
startTime: 8,
```
### duration
Wie viele Stunden angezeigt werden (z. B. `12` = 12 Stunden ab `startTime`).
```javascript
duration: 12,
duration: 8,
```
### amount
Spaltenintervall in Stunden. Bestimmt die Feinheit der Zeiteinteilung.
```javascript
amount: 1,
amount: 0.5,
amount: 0.25,
```
- `1` = Stundenspalten (08:00, 09:00, …)
- `0.5` = 30-Minuten-Spalten (08:00, 08:30, 09:00, …)
- `0.25` = 15-Minuten-Spalten (08:00, 08:15, 08:30, …)
### Header-Platzhalter im Uhrzeitmodus
Im Uhrzeitmodus stehen zusätzliche Platzhalter für `dateSettings.header.days.label` zur Verfügung:
- `##hour##` – Stunde mit führender Null (06, 07, …)
- `##minute##` – Minute mit führender Null (00, 15, 30, …)
- `##time##` – Vollständige Uhrzeit (06:00, 08:15, …)
### columnWidth
Breite einer Zeitspalte (Alias für `dayWidth` im Uhrzeitmodus).
```javascript
columnWidth: "60px",
columnWidth: "80px",
```
### timeEntries im Uhrzeitmodus
Im Uhrzeitmodus verwenden `timeEntries` statt `dateFrom`/`dateTo` die Felder `timeFrom`/`timeTo` (in Millisekunden ab Mitternacht):
```javascript
timeEntries: [{
title: "RVS GZ-NU-KE",
timeFrom: 27000000,
timeTo: 41400000,
styles: {
backgroundColor: "#0066cc"
}
}]
```
💡 Umrechnung: `Stunden × 3600000` (z. B. 07:30 = 7.5 × 3600000 = 27000000)
### Drag & Drop im Uhrzeitmodus
Im Uhrzeitmodus werden beim Drag & Drop `timeFrom`/`timeTo` statt `dateFrom`/`dateTo` aktualisiert:
```javascript
dragAction: {
recordId: Nr,
timeFrom: fieldId(Nr, "Startzeit"),
timeTo: fieldId(Nr, "Endzeit"),
resourceField: fieldId(Nr, "Einsatztag")
}
```
## columns (Top-Level)
Definiert die **linken Label-Spalten** (neben dem Zeitbereich). Pro Eintrag im Array: `title` (erscheint in der Zeile mit den Tageslabels), optional `subtitle`, optional `width` (CSS-Breite, z. B. `"200px"`). Fehlt `width`, gilt `labelWidth` (Standard `120px`).
Optional: **`alignX`**: `"left"` \| `"center"` \| `"right"` (Standard `left`), **`alignY`**: `"top"` \| `"center"` \| `"bottom"` (Standard `center`) – Ausrichtung von Header und Zellinhalt in dieser Spalte. **`fontSize`** und **`fontWeight`** (CSS-Werte, z. B. `"13px"`, `"600"` oder `"bold"`) gelten für Header und Zellen dieser Spalte, sofern weder **`items[].columns[i]`** noch **Item-**`fontSize`/`fontWeight` gesetzt sind. Pro Zelle kann in `items[].columns[i]` jeweils `alignX`, `alignY`, `fontSize`, `fontWeight` überschrieben werden.
**Kopfzeile der Label-Spalten** (Name, Abteilung): Standardfarbe kommt von **`dateSettings.header.days`** (`backgroundColor`, `fontColor`). Pro Spalte überschreibbar mit `columns[n].backgroundColor` und `columns[n].fontColor`.
Ohne `columns` oder leeres Array: **eine** Spalte mit `labelWidth`.
## items – Datenzeilen und Verschachtelung
Alle Ressourcen werden einheitlich **`items`** genannt. Flache Liste: `items: [{ id, title, subtitle, timeEntries, … }]`.
**Verschachtelung (eine Ebene):** Ein Item kann `items: [...]` enthalten. Parent und Kinder werden als **eigene Zeilen** untereinander gerendert; die erste Label-Spalte ist bei Kindern **eingerückt**. Tiefer als eine Ebene ist in der Timeline aktuell nicht vorgesehen (Datenstruktur kann später erweitert werden).
**`items[].columns`** (pro Zeile): Array mit **einem Eintrag pro Label-Spalte** (gleiche Länge wie Top-Level `columns`). Felder pro Zelle: `title`, `subtitle`, optional `customLayout`, optional `actions`, optional `alignX` / `alignY`, optional `fontSize` / `fontWeight` (höchste Priorität für Typo). Danach greifen **Item-**`fontSize`/`fontWeight`, dann Top-Level-Spalte, dann **`styles`**. Fehlende Einträge → leere Zelle. **Fallback:** Fehlt `columns` oder die erste Zelle hat keinen Inhalt, werden `title`/`subtitle` des Items **nur für die erste Spalte** verwendet.
**Parent mit Unterzeilen:** Die Parent-Zeile hat `timeEntries` wie jede andere Zeile (z. B. Summen-Balken). Kinder stehen in `items` und haben eigene `columns`-Werte.
```javascript
columns: [
{ title: "Fahrzeug / Tag", width: "160px" },
{ title: "Info", width: "80px" }
],
items: [{
id: "v1",
title: "A-MS 419",
subtitle: "GPS",
columns: [
{ title: "A-MS 419", subtitle: "GPS" },
{ title: "⌂", subtitle: "Fzg." }
],
timeEntries: [{ title: "Tagesblock", timeFrom: ... }],
items: [{
id: "v1-mo",
title: "Mo",
columns: [{ title: "Mo" }, { title: "" }],
timeEntries: [...]
}]
}]
```
## collapsible – Gruppen ein- und ausklappen
Wenn du hierarchische Einträge (`items` mit Unter-`items`) nutzt, kannst du die **Parent-Zeile** (z. B. Team- oder Fahrzeugname) per Widget-Prop **ein- und ausklappen**. Der Zustand wird **pro `uniqueId` im Browser** persistiert (`localStorage`).
### Konfiguration
```javascript
arcCustomCalendarTimeline({
uniqueId: "timeline-teams-" + Nr,
collapsible: {
enabled: true,
iconPosition: "left",
iconCollapse: "",
iconExpand: ""
},
columns: [ { title: "Team / Person", width: "200px" }, { title: "Termine", width: "120px" } ],
items: [ /* Parent mit items */ ]
})
```
| Property | Bedeutung |
|----------|-----------|
| `enabled` | `true`: Toggle-Icon in der **ersten Label-Spalte** der Parent-Zeile; Klick klappt alle Unterzeilen ein/aus. |
| `iconPosition` | *(Optional)* `"left"` oder `"right"` – Icon vor/neben dem Text (Standard: `left`). |
| `iconCollapse` | *(Optional)* HTML/SVG für **aufgeklappt** (Standard: Chevron unten). |
| `iconExpand` | *(Optional)* HTML/SVG für **eingeklappt** (Standard: Chevron rechts). |
- Gilt für Zeilen mit `items` (Kinder). **`id` des Parent-Items** muss eindeutig sein (Klappzustand).
- `styles` am Parent/Kind wirken auf die gesamte Label-Zeile (Hintergrund der Zellen).
---
Mit dem Custom Calendar Timeline bringst du ressourcenbasierte Planung und volle Flexibilität in deine Ninox-Datenbank – ideal für Einsatzplanung, Kapazitätsübersicht, Ressourcenmanagement und Flottendiagramme.
Happy Widgeting 🥳
---
# Custom Dev Tools
Source: https://www.arc-rider.com/docs/widgets/custom-dev-tools
# DevTools in React
Ein frei positionierbares Diagnosepanel anzeigen. Es sammelt vorhandene Editor-Fehlermarkierungen und zeigt eigene Debug-Werte; es ist keine React Error Boundary.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetDevTools } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [enabled, setEnabled] = useState(true);
return (
<>
{enabled && (
setEnabled(false)}
/>
)}
);
}
```
## Features ausprobieren
### Debug-Werte und Panel-Lebenszyklus
Ändere den State und blende das Panel ein und aus. Es bleibt innerhalb der Live-Vorschau und verändert die Docs-Oberfläche nicht.
```tsx
import { useState } from 'react';
import { ArcWidgetDevTools, ArcWidgetButton } from '@arcrider/arcwidgets-react';
export default function Example() {
const [visible, setVisible] = useState(true);
const [count, setCount] = useState(0);
return (
<>
setCount((n) => n + 1)}
/>
setVisible(false)}
/>
Aktueller Zähler: {count}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetDevToolsData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onFooterClick
Nullbasierter Index des Footer-Buttons.
```typescript
onFooterClick?: (index: number) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### errorPanel
Meldungstexte und optionale Footer-Buttons.
Typ: `ArcWidgetDevToolsErrorPanel`.
## Verhalten und Grenzen
- Das Panel wird am Dokumentkörper angehängt. Fehler-Scanning benötigt einen passenden CodeMirror-Editor im Dokument. Ohne Editor zeigt es keine Anwendungsfehler an; `debug` zeigt die von dir übergebenen Werte. Zum Schließen entfernt das Beispiel die Komponente aus dem React-Baum.
- Konfiguriere `errorPanel` mit Meldungen und optionalen Footer-Buttons. Nur als `clickable` markierte Buttons lösen `onFooterClick` aus.
- Zeige nur Diagnosedaten, die für die jeweiligen Nutzer bestimmt sind. Schließen wird im Beispiel durch React-State umgesetzt.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetDevToolsErrorPanel {
visible?: boolean;
maxErrors?: number;
debug?: Record;
footerButtons?: Array<{ title?: string; clickable?: boolean; [key: string]: unknown }>;
[key: string]: unknown;
}
export interface ArcWidgetDevToolsData extends ArcWidgetBaseData {
errorPanel?: ArcWidgetDevToolsErrorPanel;
}
export interface ArcWidgetDevToolsProps extends ArcReactWidgetProps {
onFooterClick?: (index: number) => void;
}
```
## Einsatzbeispiele
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Dev Tools
## AI Defaults (read first)
- **uniqueId**: Required, e.g. `"dev-tools-" + Nr`.
- **errorPanel.visible**: Only show when `isAdminMode()` – Dev-Tools sind für Entwickler gedacht.
- **errorPanel.footerButtons**: Nutze `type: "update"` für Feld-Updates, `type: "customJS"` nur für spezielle UI-Aktionen. Core emits `footer_click` (index); Ninox runs `actions`. React: `onFooterClick(index)` / `onAction`. Set `clickable: true` on React hosts.
# Custom Dev Tools
Dev-Helper-Widget für Ninox mit erweiterbarer Sektionen-Struktur. Erste Sektion: **Error Panel** mit CodeMirror-Fehlerliste, Debug-Ausgabe und optionalen Footer-Buttons.
## Anwendungscode
```javascript
if isAdminMode() then
arcCustomDevTools({
uniqueId: "dev-tools-" + Nr,
errorPanel: {
visible: true,
maxErrors: 50,
debug: {
activeTab: activeTab,
filter: filterStatus,
selectedRecord: selectedRecord
},
footerButtons: [
{
title: "State zurücksetzen",
actions: [{
type: "update",
recordId: Nr,
field: fieldId(Nr, "helper_mainContentState"),
value: ""
}]
}
]
}
})
end
```
## Parameter
| Parameter | Typ | Beschreibung |
|----------|-----|--------------|
| `uniqueId` | string | Erforderlich, eindeutige ID |
| `errorPanel` | object | Konfiguration des Error-Panels |
| `errorPanel.visible` | boolean | Error-Panel ein/aus |
| `errorPanel.maxErrors` | number | Max. Anzahl angezeigter Fehler (Default: 50) |
| `errorPanel.debug` | object | Debug-Variablen (key: value), z.B. `{ activeTab: activeTab, filter: filterStatus }` |
| `errorPanel.footerButtons` | array | Custom Buttons im Footer, siehe unten |
### errorPanel.footerButtons
Array von Button-Objekten mit:
| Eigenschaft | Typ | Beschreibung |
|-------------|-----|--------------|
| `title` | string | Button-Label |
| `actions` | array | Ninox-Actions wie bei arcCustomButton: `[{ type: "update", recordId: Nr, field: ..., value: ... }]` |
```javascript
footerButtons: [
{
title: "Editor fokussieren",
actions: [{ type: "customJS", value: "document.querySelector('.cm-editor')?.focus()" }]
},
{
title: "State zurücksetzen",
actions: [{
type: "update",
recordId: Nr,
field: fieldId(Nr, "helper_mainContentState"),
value: ""
}]
}
]
```
## Verhalten
- **Editor geschlossen:** Zeigt „Editor nicht geöffnet“. Kein MutationObserver, nur leichtes Polling (1 s).
- **Editor geöffnet:** Sammelt Fehler aus dem CodeMirror-Gutter und aktualisiert die Liste.
- **Scan-Button:** Scrollt den Editor einmal durch und sammelt alle Fehler (auch außerhalb des sichtbaren Bereichs). Behebt das Virtualisierungs-Problem von CodeMirror.
- **Klick auf Fehler:** Scrollt zur Zeile im Editor. Zwei-Phasen-Ansatz: Erst scrollt das Panel den Editor zum Zielbereich, dann wird die Zeile nach dem Render gesucht und zentriert.
- **Position:** Panel wird unten rechts angezeigt. Position kann per Drag verschoben werden und wird in localStorage gespeichert.
## Erweiterbarkeit
Später können weitere Sektionen ergänzt werden, z.B. `aiHelper: { visible: true }`.
---
# Custom Drawing
Source: https://www.arc-rider.com/docs/widgets/custom-drawing
# Drawing in React
Formen und Zeichnungen auf einer Zeichenfläche bearbeiten. Die Anwendung vergibt IDs, speichert Änderungen und verarbeitet Exporte.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetDrawing } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
import type { ArcWidgetDrawingShape } from '@arcrider/arcwidgets-react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const demoShapes: ArcWidgetDrawingShape[] = [
{
id: 'mark-1',
clickable: true,
shapeDataValue: {
type: 'circle',
cx: 140,
cy: 120,
r: 36,
stroke: '#059669',
strokeWidth: 3,
fill: 'rgba(16,185,129,0.18)',
},
},
{
id: 'mark-2',
clickable: true,
shapeDataValue: {
type: 'rect',
x: 240,
y: 80,
width: 170,
height: 100,
rx: 12,
stroke: '#d97706',
strokeWidth: 3,
fill: 'rgba(245,158,11,0.2)',
},
},
];
const busyShapes: ArcWidgetDrawingShape[] = [
...demoShapes,
{
id: 'mark-3',
clickable: true,
shapeDataValue: {
type: 'circle',
cx: 460,
cy: 250,
r: 48,
stroke: '#e11d48',
strokeWidth: 3,
fill: 'rgba(244,63,94,0.16)',
},
},
{
id: 'mark-4',
clickable: true,
shapeDataValue: {
type: 'rect',
x: 80,
y: 230,
width: 120,
height: 70,
rx: 10,
stroke: '#7c3aed',
strokeWidth: 3,
fill: 'rgba(139,92,246,0.16)',
},
},
];
export default function Example() {
const [shapes, setShapes] = useState(
pack === 'empty' ? [] : pack === 'busy' ? busyShapes : demoShapes,
);
const [selected, setSelected] = useState(
t(
'Form ziehen oder skalieren',
'Drag or resize a shape',
'Arrastra o escala una forma',
),
);
return (
<>
setSelected(String(shape_id))}
onShapeCreate={(payload, completion) => {
const id = crypto.randomUUID();
setShapes((previous) => [
...previous,
{ id, shapeDataValue: payload.shape_data_value },
]);
completion.promise = Promise.resolve(id);
}}
onShapeUpdate={(payload) =>
setShapes((previous) =>
previous.map((shape) =>
shape.id === payload.shape_id
? { ...shape, shapeDataValue: payload.shape_data_value }
: shape,
),
)
}
/>
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetDrawingData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onShapeCreate
Neue Form und ein veränderliches Completion-Objekt. Setze dessen `promise` auf die vergebene ID.
```typescript
onShapeCreate?: (payload: ArcWidgetDrawingCreatePayload, completion: { promise?: Promise }) => void;
```
### onShapeUpdate
Geänderte Form und ihre ID.
```typescript
onShapeUpdate?: (payload: { shape_id: string | number; shape_data_value: Record; bag?: unknown }) => void;
```
### onShapeActivate
ID der aktivierten Form.
```typescript
onShapeActivate?: (payload: { shape_id: string | number }) => void;
```
### onExport
Exportformat und Bild als Data-URL.
```typescript
onExport?: (payload: { format: string; base64: string }) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### canvas
Arbeitsfläche in Pixeln.
Typ: `{ width?: number; height?: number; [key: string]: unknown }`.
### artboard
Zeichen- und Exportbereich in Pixeln.
Typ: `{ width?: number; height?: number; [key: string]: unknown }`.
### shapes
Formen mit stabiler `id` und Geometrie in `shapeDataValue`.
Typ: `ArcWidgetDrawingShape[]`.
### exportSettings
Exportformate und Ausgabeziel. Für den Callback derzeit `target: "field"` wählen.
Typ: `Record`.
### create
Erstellen neuer Formen mit `enabled` erlauben oder verhindern.
Typ: `{ enabled?: boolean }`.
### tools
Verfügbare Zeichenwerkzeuge.
Typ: `Record[]`.
### stickerTypes
Verfügbare Sticker.
Typ: `Record[]`.
### drawingSettings
Einstellungen für das Zeichnen.
Typ: `Record`.
### zooming
Grenzen und Schrittweite des Zooms.
Typ: `{ min?: number; max?: number; step?: number }`.
## Verhalten und Grenzen
- Jede Form braucht eine stabile `id` und `shapeDataValue` als Objekt oder serialisierten JSON-String. Das React-Widget normalisiert `id` für den Zeichenkern.
- Beim Erstellen erhältst du einen zweiten Parameter: Setze `completion.promise` auf ein Promise mit der neuen ID. Übernimm dieselbe Form mit dieser ID in deinen State.
- `onShapeUpdate` liefert `shape_id` und die neue Form. Ersetze die passende Form unveränderlich in deinem State.
- Für `onExport` ist aktuell `exportSettings.allowedTypes: [{ format: "png", target: "field" }]` nötig. Der historische Wert `field` wählt den Data-URL-Callback; es wird kein Datenbankfeld geschrieben. `target: "file"` startet den Browser-Download.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetDrawingShape {
id: string | number;
shapeDataValue?: string | Record;
shapeId?: string | number;
[key: string]: unknown;
}
export interface ArcWidgetDrawingData extends ArcWidgetBaseData {
height?: string;
canvas?: { width?: number; height?: number; [key: string]: unknown };
artboard?: { width?: number; height?: number; [key: string]: unknown };
shapes?: ArcWidgetDrawingShape[];
exportSettings?: Record;
create?: { enabled?: boolean };
tools?: Record[];
stickerTypes?: Record[];
drawingSettings?: Record;
zooming?: { min?: number; max?: number; step?: number };
}
export interface ArcWidgetDrawingCreatePayload {
shape_data_value: Record;
sticker_uid?: string | null;
}
export interface ArcWidgetDrawingProps extends ArcReactWidgetProps {
onShapeCreate?: (payload: ArcWidgetDrawingCreatePayload, completion: { promise?: Promise }) => void;
onShapeUpdate?: (payload: { shape_id: string | number; shape_data_value: Record; bag?: unknown }) => void;
onShapeActivate?: (payload: { shape_id: string | number }) => void;
onExport?: (payload: { format: string; base64: string }) => void;
}
```
## Einsatzbeispiele
- [Ein Bild annotieren und exportieren](/docs/react/examples/custom-drawing-zeichnen-im-bild-teil1)
- [Markierungen auf einem Plan](/docs/react/examples/custom-drawing-teil-2-mangel-verortung-mit-pins)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Drawing
## AI Defaults (read first)
- **uniqueId**: Required, `"drawing-" + Nr`.
- **tableId**: Required – the shapes table (`tableId("Shapes")`).
- **fieldId**: The text field storing shape data (JSON), use `fieldId(Nr, "Feldname")`.
- **height**: Typically `"800px"` or `"100%"`.
- **canvas/artboard**: `canvas: { width: 4000, height: 4000 }`, `artboard: { width: 1000, height: 1000 }`.
- **shapes**: Each shape needs `shapeId: Nr` and `shapeDataValue` (from the shapes table text field).
- **embedded**: Default `false`, set `true` when nested.
- **Persistence**: Core emits `shape_create` / `shape_update` / `shape_activate` / `export`. Ninox handlers build Action Performer `create`/`update` and run shape `actions`. React: `onShapeCreate`, `onShapeUpdate`, `onShapeActivate`, `onExport` (or `onAction`).
# Custom Drawing
Das **Custom Drawing Widget** ermöglicht es, beliebige Bilder oder PDF's (z. B. Grundrisse, Produktfotos, Körper-Silhouetten) hochzuladen und mit interaktiven **Pins, Sticker oder Freihandzeichnungen** zu versehen. Jede Markierung kann mit einer **Notiz**, **Kategorie** oder **zusätzlichen Information** verknüpft werden. Ideal für Anwendungen in Bau, Mode, Medizin, Logistik u. v. m.
## Anwendungscode
```javascript
arcCustomDrawing({
uniqueId: "titel " + Nr,
embedded: false,
height: "800px",
tableId: tableId("Shapes"),
fieldId: fieldId("Shapes", "helper_shapeDataValue"),
changeFieldValues: [{
fieldId: fieldId("Tabelle", "Feld Name"),
value: "Wert"
}],
exportSettings: {
allowedTypes: [{
format: "jpg"
}, {
format: "png"
}, {
format: "svg"
}, {
format: "pdf",
mergeFile: false
}],
target: "file",
recordId: Nr,
fieldId: fieldId("Tabelle", "Feld für den Export"),
mergeFile: "Feld mit der Originaldatei",
apiKey: "API_KEY",
},
canvas: {
width: 4000,
height: 4000,
offsetX: 0,
offsetY: 0
},
zooming: {
step: 0.25,
min: 0.01,
max: 4
},
drawingSettings: {
strokeWidth: 1,
strokeColor: "#ffffff"
},
artboard: {
width: 1000,
height: 1000,
},
stickerTypes:[{
uid: uid,
image: "stickerBase64",
icon: base64,
label: Name,
width: 100,
height: 100,
originX: 0.5,
originY: 0.89,
default: false
}],
shapes: (Shapes).[{
shapeId: Nr,
movable: true,
shapeDataValue: helper_shapeDataValue,
stickerUID: "",
sidebarItem: {
header: "Titel des Eintrags",
content: "Beschreibung des Eintrags",
}
}],
rightSideContent: {
show: true,
header: "Header",
footer: "Footer"
}
})
```
### 🔸 `embedded`
Gibt an, ob das Widget sich in eine bestehende Maske (z. B. Ninox-Formular) einfügt.
```javascript
embedded: "" // default: false
embedded: true,
```
👀 **Tipp:** Bei `true` ist keine feste Höhe nötig – das Widget passt sich automatisch dem Elterncontainer an.
### 🔸 `height`
Mit dem Parameter `height` gibst du die **Gesamthöhe** des Drawing-Tools in Pixel an.
Er bestimmt, wie viel vertikaler Platz das Widget im eingebetteten Kontext (z. B. in einem Formular oder auf einer Seite) einnimmt.
**Empfehlung: **Das Widget sollte für eine bessere UI idealer Weise in Custom Layout eingebunden werden. Und die Höhe im Layout Block bestimmt werden.
### 🔸 `tableId` & `fieldId`
Diese beiden Parameter definieren, **wo die Formdaten (Shapes)** gespeichert oder geladen werden.
- `**tableId**` gibt die Tabelle an, in der die Shapes verwaltet werden.
- `**fieldId**` verweist auf das konkrete Feld innerhalb dieser Tabelle, das die Geometriedaten (`shapeDataValue`) des jeweiligen Shapes enthält. Achtung: Hier muss ein Ninox-Textfeld verwendet werden.
Du kannst hiermit eigene Formen, Marker oder Objekte dynamisch speichern – z. B. Rechtecke, Sticker, Kreise, Bilder oder Linien.
### 🔸 `dataBag`
Optional. Steuert, wie Shape-Daten in einem **JSON-Topf** (ein Textfeld mit mehreren Keys) gelesen und geschrieben werden – ohne andere Keys zu überschreiben.
```javascript
dataBag: {
key: "pin" // Shape liest/schreibt nur diesen Key im Topf
// encoding: "raw" // Default — Plain-JSON; nur bei Legacy: "urlEncoded"
}
```
**Lesen:** Das Feld `shapeDataValue` pro Shape enthält den gesamten Topf als Plain-JSON. Das Widget extrahiert `key` als Geometrie. In Formeln: `parseJSON(helper_data)` — ohne `urlDecode`.
**Schreiben:** Beim Verschieben wird nur `key` aktualisiert; andere Keys (`placedAt`, `meta`, …) bleiben erhalten.
**Beispiel: Wartungsplan mit Prüfpunkten** (z. B. Gebäudeinspektion):
```json
{
"geo": { "type": "sticker", "stickerUID": "pin_ok", "x": 420, "y": 180, "width": 40, "height": 40 },
"placedAt": "2026-06-13",
"inspectionPointId": "123"
}
```
Ohne `dataBag` bleibt das bisherige Verhalten: das gesamte Feld ist `shapeDataValue` (raw JSON).
> **Hinweis:** Das ist die **Widget-Config** (`key` + `encoding`). Für **Actions** (`update` mit `patch` in State-Bags) gilt dasselbe `dataBag`-Konzept plattformweit — siehe [`data-bag-actions`](../patterns/data-bag-actions.md).
### 🔸 `changeFieldValues`
Erlaubt es, beim **Anlegen eines neuen Shapes** zusätzliche Felder oder Verknüpfungen zu befüllen – z. B. Kategorie, Ersteller o. ä.
Pro Eintrag: `{ fieldId, value }` — `fieldId` ist die Ninox-Feld-ID (z. B. via `fieldId("Tabelle", "Feldname")`).
**Sticker-spezifisch:** Zusätzlich kann jedes Element in `stickerTypes` ein eigenes `changeFieldValues`-Array haben. Beim Platzieren eines Stickers werden zuerst die **globalen** `changeFieldValues` am Drawing gesetzt, danach die des **aktiven Sticker-Typs** — bei gleichem `fieldId` gewinnt der Sticker.
```javascript
changeFieldValues: [{
fieldId: fieldId("Pruefpunkte", "Objekt zuordnen"),
value: number(obj.Nr)
}],
stickerTypes: [{
uid: "pin_ok",
changeFieldValues: [{
fieldId: fieldId("Pruefpunkte", "Kategorie"),
value: "OK"
}]
}]
```
**Laufende Nummern:** Werte wie Positionsnummern oder fortlaufende IDs **nicht** über `changeFieldValues` setzen — der Wert stammt vom letzten Render und ist bei mehreren schnellen Creates falsch. Stattdessen **After-change-Trigger** auf dem Parent-Link-Feld; im Trigger **`myNr := number(Nr)` vor** dem Filter `number(Nr) != myNr`, sonst filtert man sich selbst weg.
### 🔸 `create`
Steuert das **Anlegen neuer Shapes** (Pins, Linien, Rechtecke, Kreise, Bilder) und bündelt optional die Create-Konfiguration. Empfohlen ab dieser Version; die Root-Props `tableId`, `fieldId`, `changeFieldValues` und `setNewRecordId` bleiben **weiterhin gültig** (Legacy).
```javascript
create: {
enabled: if lockCreate then false else true end,
tableId: tableId("Shapes"),
fieldId: fieldId("Shapes", "helper_shapeDataValue"),
changeFieldValues: [{
fieldId: fieldId("Pruefpunkte", "Objekt"),
value: number(obj.Nr)
}],
setNewRecordId: [{
recordId: Nr,
fieldId: fieldId("Objekt", "Letzter Shape")
}]
}
```
| Feld | Beschreibung |
|------|--------------|
| `enabled` | `false` = kein neues Shape (Toolbar ausgegraut, Pan/Klick/`actions` bleiben). Default: `true`. |
| `tableId` | Zieltabelle für neue Shapes (überschreibt Root-`tableId`, falls gesetzt). |
| `fieldId` | Textfeld für Geometrie am **neuen** Datensatz (überschreibt Root-`fieldId`). |
| `changeFieldValues` | Zusatzfelder beim Create (überschreibt Root-`changeFieldValues`). |
| `setNewRecordId` | Nach Create: neuen Datensatz in Parent verlinken (`[{ recordId, fieldId }]`). |
**Hinweise:**
- `dataBag` bleibt am Widget-Root (Lesen + Schreiben bestehender Shapes).
- `stickerTypes[].changeFieldValues` bleibt sticker-spezifisch und ergänzt die globalen Werte.
- Nur `create.enabled: false` reicht zum Sperren — `tableId`/`fieldId` am Root können für bestehende Shapes weiter gesetzt bleiben.
### 🔸 `setNewRecordId` (Legacy am Root)
Optional am Widget-Root oder innerhalb von `create`. Nach dem Anlegen eines Shapes wird der neue Datensatz in ein Referenzfeld geschrieben — z. B. um den Parent-Datensatz zu verknüpfen.
```javascript
setNewRecordId: [{
recordId: Nr,
fieldId: fieldId("Objekt", "Letzter Shape")
}]
```
### 🔸 `exportSettings`
Mit diesem Block konfigurierst du die **Exportfunktion des Widgets**. Du kannst festlegen, in welchen Formaten der Nutzer exportieren darf (z. B. PNG, PDF), wohin die Datei gespeichert werden soll und ob bei PDF ein bestehendes Dokument zusammengeführt wird.
💡 **Hinweis**: Konvertierung in eine vektorisierte PDF fallen Kosten an und es ist eine Verbindung zum Internet notwendig (funktioniert nicht im Offline Modus). Genaue Kosten erfragst du bitte bei dem arcRider Support.
Feld
Beschreibung
`allowedTypes`
Liste der erlaubten Exportformate. Du kannst `"jpg"`, `"png"`, `"svg"` und `"pdf"` angeben.
Beim Format `"pdf"` kannst du zusätzlich `mergeFile: false` oder ein Feldname setzen, um eine bestehende PDF zu ergänzen.
`target`
Legt fest, wohin die Datei exportiert werden soll.
`"file"` bedeutet, die Datei wird heruntergeladen.
`"field"` bedeutet, die Datei wird in ein Datei-Feld in Ninox hochgeladen.
`recordId`
Gibt den Datensatz an, in den exportiert werden soll (nur bei `target: "field"` erforderlich).
`fieldId`
Definiert das genaue Feld im Datensatz, in das die exportierte Datei geschrieben wird.
`mergeFile`
Nur für PDF-Exporte relevant.
Wenn angegeben, wird die exportierte Zeichnung mit der PDF aus diesem Feld zusammengeführt.
`apiKey`
Wird nur für den PDF-Export mit Zusammenführung benötigt.
Hier wird ein API-Schlüssel von Arc Rider verwendet, um das PDF-Rendering serverseitig durchzuführen.
#### 🔄 Auto-Export
Mit `autoExport` kannst du festlegen, dass nach jeder Shape-Änderung automatisch ein Export erfolgt – z. B. um ein Live-Vorschaubild zu speichern.
Die Properties `autoExport`, `autoExportDelay`, `target`, `recordId` und `fieldId` können sowohl global als auch **pro Format** in `allowedTypes` gesetzt werden. Format-spezifische Einstellungen überschreiben die globalen.
**Beispiel mit Auto-Export:**
```javascript
exportSettings: {
allowedTypes: [{
format: "jpg",
target: "field",
recordId: Nr,
fieldId: fieldId("Tabelle", "Vorschaubild"),
autoExport: true,
autoExportDelay: 500 // Verzögerung in ms (default: 500)
}, {
format: "pdf",
target: "file", // Manueller Download
autoExport: false
}]
}
```
| Feld | Beschreibung |
|------|--------------|
| `autoExport` | `true` oder `false` – aktiviert automatischen Export nach jeder Shape-Änderung |
| `autoExportDelay` | Verzögerung in Millisekunden bevor der Export startet (default: 500). Dient als Debounce bei schnellen Änderungen. |
### 🔸 `canvas`
Mit dem `canvas`-Block definierst du die **technische Zeichenfläche**, also den kompletten Bereich, auf dem Shapes gezeichnet und verschoben werden können.
Dieser Bereich kann deutlich größer sein als der sichtbare Ausschnitt (`artboard`) und bestimmt, wie weit sich Nutzer im Zeichenbereich bewegen können (z. B. beim Verschieben oder Zoomen).
#### 🔧 Struktur:
- `width`: Die gesamte Breite der Zeichenfläche in Pixeln.
- `height`: Die gesamte Höhe der Zeichenfläche in Pixeln.
- `offsetX`: Abstand zum linken und rechten Rand – kann genutzt werden, um Inhalte zentriert darzustellen.
- `offsetY`: Abstand zum oberen und unteren Rand – ideal für zusätzliche Arbeitsfläche oder Druckränder.
Tipp: Du kannst durchaus auch dynamische Werte aus Ninox Feldern oderBerechnungen hier einsetzen. Beispielsweise haben wir Workflows entwickelt, in denen wir die Größe des canvas abhängig von der Größe des Hintergrundshapes gemacht haben.
### 🔸 `zooming`
Der `zooming`-Block steuert, **wie weit in das Zeichenfeld hinein- oder herausgezoomt werden kann** – etwa per Mausrad oder Touch-Gesten. Damit definierst du den Zoombereich und wie fein abgestuft gezoomt wird.
#### 🔧 Struktur:
- `step`: Gibt an, wie groß ein Zoom-Schritt ist, z. B. bei Klick auf die Plus/Minus-Buttons oder beim Scrollen mit gedrückter Strg-Taste. Ein kleiner Wert (z. B. `0.1`) bedeutet feinere Zoomschritte.
- `min`: Der **kleinste erlaubte Zoomfaktor** (z. B. `0.1` = 10 %). Damit legst du fest, wie weit man maximal herauszoomen darf.
- `max`: Der **größte erlaubte Zoomfaktor** (z. B. `4` = 400 %). Damit begrenzt du das Hereinzoomen auf eine bestimmte Detailstufe.
💡 **Hinweise:**
- Der initiale Zoom wird automatisch so gesetzt, dass das Artboard gut in das Widget passt.
- Zoomaktionen wirken sich auf die Darstellung der Shapes aus, nicht auf ihre tatsächliche Größe im `canvas`.
- Wird kein `zooming`-Block gesetzt, gelten Standardwerte (Zoom zwischen ca. 10 % und 400 %).
### 🔸 `drawingSettings`
Mit dem `drawingSettings`-Block legst du die **Standard-Eigenschaften für neue Zeichenobjekte** fest – z. B. Linienfarbe und -stärke. Diese Werte gelten für alle neu gezeichneten Formen wie Linien, Rechtecke oder Kreise, solange der Nutzer keine individuellen Einstellungen verändert.
#### 🔧 Struktur:
- `strokeWidth`: Bestimmt die Linienbreite in Pixeln.
Ein Wert von `1` ergibt eine feine Linie, `2` oder `3` wirken etwas kräftiger.
- `strokeColor`: Definiert die Farbe der Linien im Hex-Format, z. B. `#ffffff` für Weiß oder `#ffaa21` für Orange.
💡 **Hinweis:**
Du kannst `strokeColor` und `strokeWidth` auch **aus Ninox-Feldern dynamisch übergeben**, um die Zeichenoptionen z. B. **vom Nutzer auswählbar zu machen**. So kannst du pro Datensatz individuelle Zeichenstile ermöglichen.
### 🔸 `toolbarSettings`
Optional. Steuert **Reihenfolge, Sichtbarkeit und Gruppierung** der Toolbar-Buttons. Ohne `toolbarSettings` bleibt das Standard-Layout unverändert (Move, Zeichenwerkzeuge, Stickers-Untermenü, Export).
#### Struktur
- `top`: Buttons in der oberen Toolbar-Leiste (von oben auf Desktop / links auf Mobile).
- `bottom`: Buttons in der unteren Leiste (Export etc.).
#### Einträge in `top` / `bottom`
| Form | Bedeutung |
|------|-----------|
| `"move"` | Tool mit Standard-Icon (Kurzform) |
| `{ tool: "draw", icon: "..." }` | Tool mit eigenem Icon (URL, Base64 oder SVG) |
| `"stickers"` | Alle `stickerTypes` **direkt** in der Toolbar (Ebene 1) |
| `{ sticker: "pin_rot" }` | Nur dieser Sticker direkt in der Toolbar |
| `{ group: "zeichnen", icon: "...", items: ["draw", "rect", "circle"] }` | Gruppe mit Unterpanel (wie bisher bei Stickers/Export) |
**Weglassen = nicht anzeigen.** Es gibt kein separates `enabled`-Flag — was nicht im Layout steht, erscheint nicht.
#### Beispiel: Prüfpunkt-Pins, nur Move + ausgewählte Sticker
```javascript
toolbarSettings: {
top: [
"move",
{ sticker: "pin_rot" },
{ sticker: "pin_gruen" }
],
bottom: ["export"]
}
```
#### Beispiel: Zeichenwerkzeuge gruppieren
```javascript
toolbarSettings: {
top: [
"move",
{
group: "zeichnen",
label: "Zeichnen",
icon: "data:image/svg+xml,...",
items: ["draw", "rect", "circle"]
},
"image",
"stickers"
],
bottom: ["export"]
}
```
### 🔸 `artboard`
Der `artboard`-Block definiert den **sichtbaren Ausschnitt deiner Zeichenfläche** – also das, was der Nutzer beim Öffnen des Widgets zunächst sieht. Es handelt sich sozusagen um das „Papier“, auf dem gezeichnet wird – während der `canvas`-Bereich das „gesamte Atelier“ darstellt.
#### 🔧 Struktur:
- `width`: Breite des sichtbaren Zeichenbereichs in Pixeln.
- `height`: Höhe des sichtbaren Zeichenbereichs in Pixeln.
Dieser Bereich wird automatisch zentriert und skaliert dargestellt, sodass er vollständig im Widget sichtbar ist (abhängig von Zoom- und Darstellungsparametern).
💡 **Hinweise:**
- Das `artboard` ist rein visuell – alle Shapes können sich auch **außerhalb dieses Bereichs** befinden, solange sie innerhalb des `canvas` liegen.
- Wenn du ein bestimmtes Seitenverhältnis möchtest (z. B. A4 oder Quadrat), kannst du die `width` und `height` entsprechend setzen.
- In Kombination mit `zooming` und `canvas` kannst du gezielt steuern, wie viel Platz Nutzer:innen für ihre Zeichnung haben – und was beim Start sofort sichtbar ist.
Tipp: Du kannst durchaus auch dynamische Werte aus Ninox Feldern oderBerechnungen hier einsetzen. Beispielsweise haben wir Workflows entwickelt, in denen wir die Größe des artboards abhängig von der Größe des Hintergrundshapes gemacht haben. Dadurch scrollt der User nicht so viel hin und her.
### 🔸 `stickerTypes`
Der `stickerTypes`-Block erlaubt es dir, **individuelle Sticker** bereitzustellen, die Nutzer im Zeichenbereich platzieren können – z. B. Icons, Symbole, Marker oder Piktogramme.
Jeder Sticker ist ein Objekt mit Eigenschaften wie Bildquelle, Größe und Positionierungsverhalten.
Ideal für Use Cases wie:
- 🔧 Technische Markierungen auf Fotos oder Plänen
- 📍 Standortpins auf Karten oder Grundrissen
- 👕 Qualitätskontrollen in der Modebranche
- 🏥 Medizinische Annotationen auf Körpersilhouetten
#### 🔧 Struktur je Sticker:
- `uid`: Eindeutige ID des Stickers (z. B. `"pin_rot"`).
- `image`: Base64-Daten-URL oder URL zur Grafik — wird beim Platzieren auf dem Canvas verwendet.
- `icon` (optional): Vorschaubild **nur** für den Toolbar-Button (wenn abweichend vom Stickerbild). Erlaubt sind:
- Bild (SVG-Markup, PNG/JPG/Data-URL, HTTP-URL) — wie `image`
- `arcCustomIcon`-Widget-Objekt: `{ widget: "arcCustomIcon", data: { iconSet: "phosphor", name: "map-pin", color: "#1565c0" } }`
- `label`: Bezeichnung des Stickers. Zwei Formen möglich:
- **String** (Legacy): nur Tooltip beim Hovern über dem Toolbar-Button, kein sichtbarer Text.
- **Objekt** (neu): sichtbarer Text unter dem Icon im Toolbar-Button — `{ value: "K", visible: true, fontColor: "#1565c0", fontSize: 10, maxWidth: 50 }`. `visible: false` verhält sich wie der String-Fall (nur Tooltip). Zu langer Text wird bei `maxWidth` mit `…` abgeschnitten.
- `width`: Breite des Stickers in Pixeln.
- `height`: Höhe des Stickers in Pixeln.
- `originX`: Horizontaler Ankerpunkt (0 = links, 0.5 = Mitte, 1 = rechts).
- `originY`: Vertikaler Ankerpunkt (0 = oben, 0.5 = Mitte, 1 = unten).
- `default` (optional): Wenn `true`, wird dieser Sticker vorausgewählt.
- `labelPlaceholder` (optional): Platzhalter-String im SVG (`image`), der durch `label` am Shape ersetzt wird — Konvention: `##LABEL##` (wie bei anderen arcWidgets: `##key##`).
- `defaultLabel` (optional): Fallback für `label` direkt beim Platzieren, bis Ninox die Formel neu liefert.
- `defaultPlaceholders` (optional): Fallback-Objekt für `shape.placeholders` beim Platzieren (gleiche Keys wie im SVG).
- `changeFieldValues` (optional): Zusätzliche Felder beim **Anlegen** eines Datensatzes für diesen Sticker-Typ — merged mit globalen `changeFieldValues` (Sticker überschreibt bei gleichem `fieldId`).
#### Dynamische SVG-Platzhalter (Sticker + Shape)
Für Marker mit Text, Status-Dot und Icons kann das **SVG-Template** Platzhalter enthalten. Das Widget ersetzt sie beim Rendern und im Export:
| Quelle | Ersetzung |
|--------|-----------|
| `stickerType.labelPlaceholder` + `shape.label` | z. B. `##LABEL##` → `"K15"` |
| `shape.placeholders` (Objekt) | Jeder Key `foo` ersetzt `##foo##` im SVG |
| `stickerType.defaultLabel` / `defaultPlaceholders` | Sofort beim Platzieren, bis Ninox reagiert |
**Data-URL-Hinweis:** Wenn das SVG per `encodeURIComponent` in `data:image/svg+xml,…` eingebettet ist, ersetzt das Widget Platzhalter auch in URL-kodierter Form (z. B. `%23%23LABEL%23%23` → `K15`, `%23ff0000` für `#ff0000`).
**Warum `##key##`?** Wie bei arcCustomInput (`##inputValue##`) und arcCustomCalendarWeek (`##clickedDate##`). Anders als `{{key}}` kollidiert `##key##` nicht mit der Ninox-Syntax `{variable}` in Text-Blöcken.
Beispiel `shape.placeholders` für Status-Icons via `display` (alle Varianten im SVG, Ninox schaltet Sichtbarkeit):
```javascript
placeholders: {
statusColor: "#4caf50",
showCheck: "block",
showWarn: "none",
showError: "none"
}
```
Beispiel `defaultPlaceholders` am `stickerType` (Fallback bis Ninox reagiert):
```javascript
defaultLabel: "",
defaultPlaceholders: {
statusColor: "#9e9e9e",
showCheck: "none",
showWarn: "none",
showError: "none"
}
```
Neue Platzhalter erfordern **keine Widget-Änderung** — nur `##key##` ins SVG und passenden Key in `shape.placeholders`.
💡 **Hinweise:**
- Die Sticker erscheinen im linken Menü des Widgets unter „Stickers“.
- Beim Platzieren eines Stickers wird seine Position automatisch anhand von `originX` / `originY` berechnet. So kannst du z. B. Marker exakt mit ihrer Spitze am Klickpunkt ausrichten.
- Du kannst beliebig viele Sticker definieren – z. B. farbige Pins, Icons für Mängel, Emojis, Status-Symbole etc.
- Die Sticker-Grafiken sollten idealerweise als **SVG** oder als **PNG mit transparentem Hintergrund** vorbereitet sein.
**Tipp**: Erstell dir eine Ninox-Tabelle mit Stickern. Lade deine SVG oder PNG Datei in ein Bildfeld. Nutze die Ninox Funktion `loadFileAsBase64URL(Image)`in einem Funktionsfeld, um das base64 für deine Stickerliste im Drawing zu erhalten. Natürlich kannst du in deiner Stickerliste auch gleich Breite, Höhe, Name … definieren.
### 🔸 `shapes`
Der `shapes`-Block definiert die Liste der **Zeichenobjekten**, die du im Widget hinterlegst. Jedes Objekt im Array entspricht einem gespeicherten Eintrag in deiner `tableId` und enthält die nötigen Informationen zur Darstellung, Position und Interaktion.
Wichtig: Um Drawing korrekt nutzen zu können, ist es essentiell eine Tabelle Shapes aufzusetzen und darin mindestens ein Textfeld `helper_shapeDataValue` anzulegen.
#### 🔧 Struktur je Shape:
- `shapeId`: Die eindeutige ID des Shapes (meist die `Nr` des Datensatzes).
- `movable`: Gibt an, ob das Objekt im Zeichenbereich verschoben werden darf (`true` oder `false`). `false` sperrt nur das Verschieben — Klick, Hover und `actions` funktionieren weiterhin. Im **Sticker-Modus**: Shapes mit `actions` fangen Klicks ab (z. B. Detail in Sidebar); reine Hintergrund-Shapes ohne `actions` lassen Pin-Platzierung durch.
- `shapeDataValue`: Die gespeicherten Formdaten (z. B. Koordinaten, Größe, Farbe, Typ etc.). Mit `dataBag.key` kann hier der gesamte JSON-Topf stehen; das Widget nutzt dann nur den Key-Wert als Geometrie.
- `label` (optional): Dynamischer Text für Sticker mit `labelPlaceholder` im `stickerType`.
- `placeholders` (optional): Objekt mit zusätzlichen SVG-Ersetzungen — jeder Key ersetzt `##key##` im Sticker-SVG (z. B. `statusColor`, `showCheck`).
- `scalable` (optional): Bei Stickern standardmäßig `false` — für pixel-stabile Marker auf Plänen setzen.
- `actions`: Optional – Liste von Aktionen, die bei **Klick** (nicht beim Draggen) ausgeführt werden. Gleiches Format wie bei anderen arcWidgets (`update`, `popup`, `openRecord`, …). Unterstützt plain `value` oder `dataBag`/`patch` für partielle Updates in einen State-Topf:
```javascript
actions: [{
type: "update",
recordId: stateRecordId,
fieldId: stateField,
dataBag: {
base: helper_mainContentState,
patch: { selectedShape: Nr }
}
}]
```
Typischer Use-Case: Shape-ID in einen gemeinsamen UI-State schreiben → Sidebar (`rightSideContent`) zeigt das Detail. Ausführlich: [`data-bag-actions`](../patterns/data-bag-actions.md).
- `stickerUID`: Wenn du einen anderen Sticker, als den initial erstellten, anzeigen möchtest (z. B. weil sich ein Status geändert hat), musst du hier die UID des entsprechenden Stickers angeben.
- `sidebarItem`: Optional – zeigt das Shape zusätzlich in der rechten Seitenleiste an, mit:
`header`: Titel (z. B. „Mangel #3“)
- `content`: Beschreibung oder weitere Infos
- `hide`: `true` oder `false` – blendet das Item in der Sidebar aus, ohne es zu löschen (z. B. für gefilterte Ansichten)
### Rezept: Wartungsplan mit Prüfpunkten
Typisches Setup für Gebäudeinspektion, Anlagenwartung oder ähnliche Plan-basierte Marker — ein **nicht verschiebbarer Plan-Hintergrund** plus **verschiebbare Prüfpunkt-Pins** mit Persistenz in einer Kind-Tabelle.
#### Bausteine
1. **Plan-Hintergrund** — ein Shape mit `type: "image"`, volle Artboard-Größe, `movable: false`, `hidden: true` (nur visuell, nicht in Sidebar). Bild aus Upload via `loadFileAsBase64URL(PlanBild)`.
2. **Prüfpunkt-Shapes** — aus `(select Pruefpunkte where Objekt = obj.Nr)` mit `movable`, `placeholders`, `actions` (Selection in State schreiben).
3. **`dataBag: { key: "geo" }`** am Drawing — Geometrie in JSON-Topf, Metadaten (`placedAt`, `inspectionPointId`, …) bleiben erhalten.
4. **`canvas` / `artboard`** — aus Upload-Metadaten (Breite/Höhe des Plans).
5. **`toolbarSettings`** — nur Move + die benötigten Sticker inline (siehe Beispiel oben).
6. **Verschieben sperren** — Boolean im State (`lockShapeMove`), pro Shape `movable: if lockShapeMove then false else true end`. Toggle per Button mit `dataBag`-Patch. Siehe State-Management-Rule (`07-state-management.mdc`).
#### Skizze (Ninox)
```javascript
let lockShapeMove := if item(stateParsed, "lockShapeMove") = false then false else true end;
let planBg := [{
shapeId: "plan-background",
movable: false,
shapeDataValue: {
type: "image",
href: loadFileAsBase64URL(obj.PlanBild),
x: 0, y: 0,
width: planWidth,
height: planHeight
}
}];
let pinShapes := (select Pruefpunkte where number(Objekt) = number(obj.Nr)).[{
shapeId: text(Nr),
movable: if lockShapeMove then false else true end,
scalable: false,
label: text(Positionsnummer),
placeholders: { statusColor: statusFarbe, showCheck: "block", showWarn: "none", showError: "none" },
shapeDataValue: helper_shapeDataValue,
actions: [{ type: "update", recordId: Nr, fieldId: stateField,
dataBag: { base: helper_mainContentState, patch: { selectedShape: text(Nr) } } }]
}];
arcCustomDrawing({
dataBag: { key: "geo" },
tableId: "Pruefpunkte",
fieldId: fieldId(Nr, "helper_shapeDataValue"),
shapes: array(planBg, pinShapes),
toolbarSettings: {
top: ["move", { sticker: "pin_ok" }, { sticker: "pin_warn" }],
bottom: []
},
rightSideContent: { show: if isMobile then false else true end }
})
```
**Upload:** Zwei After-change-Trigger (Web = Server, App = Browser) auf dem Upload-Feld — `importFile` → Zieldatei + JSON-Metadaten (Breite/Höhe) → Trigger-Felder leeren.
**Sidebar auf Mobile:** `rightSideContent.show: false` auf Mobile; stattdessen Bottom-Sheet per Layout-Block mit `actions` + `dataBag`-Patch (siehe UI-Architecture-Rule `06-ui-architecture.mdc`).
### 🔸 `rightSideContent`
Der Block `rightSideContent` steuert, **ob eine rechte Seitenleiste im Widget angezeigt wird** und was dort dargestellt werden soll. Diese Sidebar ist besonders nützlich, um eine Liste der gezeichneten Elemente anzuzeigen oder zusätzliche Informationen bereitzustellen.
#### 🔧 Struktur:
- `show`: `true` oder `false` – aktiviert oder deaktiviert die rechte Sidebar.
- `header`: (optional) Widgets oder Textinhalt für den oberen Bereich der Sidebar.
- `footer`: (optional) Widgets oder Textinhalt für den unteren Bereich der Sidebar.
- `content`: (optional) Individuelle Konfiguration des mittleren Inhalts.
Wenn `show: true` gesetzt ist und die Shapes `sidebarItem`-Einträge enthalten (siehe `shapes`), wird automatisch eine **interaktive Liste aller Shapes** angezeigt – mit Titel, Beschreibung, Hover-Effekt und Auswahlverhalten.
🔍 `content`-Block im Detail:
- `showShapeLayers`:
Wenn `true`, wird eine automatische Liste aller vorhandenen Shapes (mit `sidebarItem`) angezeigt – inklusive Titel, Beschreibung, Hover- & Klickverhalten.
Ideal z. B. für Mängellisten, Prüfpunkte oder Annotationen.
- `customLayout`:
Optionaler benutzerdefinierter Inhalt, der im mittleren Bereich angezeigt werden kann.
Hier kannst du z. B. HTML, Ninox-Formelergebnisse oder vorbereitete Layout-Komponenten einbinden.
Wenn `showShapeLayers` aktiv ist, wird die Shape-Liste angezeigt. Wenn du stattdessen ein eigenes Layout anzeigen willst, kannst du `customLayout` nutzen.
💡 **Hinweise:**
- Die Sidebar funktioniert besonders gut, wenn du Shapes mit `sidebarItem`-Infos versiehst.
- Der Bereich kann je nach Use Case rein informativ, interaktiv oder visuell angepasst werden.
- Du kannst `customLayout` auch dynamisch aus einem Ninox-Feld übernehmen – z. B. über eine Textformel oder HTML-Komponente.
- Wenn du beides kombinieren möchtest (Layer-Liste + eigene Inhalte), kannst du `customLayout` über dem Footer einfügen und `showShapeLayers` auf `true` lassen.
### 🔧 Kein Entwickler? Kein Problem.
Du hast keine Zeit, dich mit Code und Konfiguration zu beschäftigen? Wir vom **arcRider-Team** bieten dir einen **Installations- und Einrichtungssupport** für das `arcCustomDrawing`-Widget an – maßgeschneidert auf deinen Anwendungsfall.
➡️ **Schreib uns einfach an **[**office@arc-rider.com**](mailto:office@arc-rider.com).
Wir helfen dir, in wenigen Stunden loszulegen – ohne technisches Kopfzerbrechen.
# Custom Drawing
## AI Defaults (read first)
- **uniqueId**: Required, `"drawing-" + Nr`.
- **tableId**: Required – the shapes table (`tableId("Shapes")`).
- **fieldId**: The text field storing shape data (JSON), use `fieldId(Nr, "Feldname")`.
- **height**: Typically `"800px"` or `"100%"`.
- **canvas/artboard**: `canvas: { width: 4000, height: 4000 }`, `artboard: { width: 1000, height: 1000 }`.
- **shapes**: Each shape needs `shapeId: Nr` and `shapeDataValue` (from the shapes table text field).
- **embedded**: Default `false`, set `true` when nested.
- **Persistence**: Core emits `shape_create` / `shape_update` / `shape_activate` / `export`. Ninox handlers build Action Performer `create`/`update` and run shape `actions`. React: `onShapeCreate`, `onShapeUpdate`, `onShapeActivate`, `onExport` (or `onAction`).
# Custom Drawing
Das **Custom Drawing Widget** ermöglicht es, beliebige Bilder oder PDF's (z. B. Grundrisse, Produktfotos, Körper-Silhouetten) hochzuladen und mit interaktiven **Pins, Sticker oder Freihandzeichnungen** zu versehen. Jede Markierung kann mit einer **Notiz**, **Kategorie** oder **zusätzlichen Information** verknüpft werden. Ideal für Anwendungen in Bau, Mode, Medizin, Logistik u. v. m.
## Anwendungscode
```javascript
arcCustomDrawing({
uniqueId: "titel " + Nr,
embedded: false,
height: "800px",
tableId: tableId("Shapes"),
fieldId: fieldId("Shapes", "helper_shapeDataValue"),
changeFieldValues: [{
fieldId: fieldId("Tabelle", "Feld Name"),
value: "Wert"
}],
exportSettings: {
allowedTypes: [{
format: "jpg"
}, {
format: "png"
}, {
format: "svg"
}, {
format: "pdf",
mergeFile: false
}],
target: "file",
recordId: Nr,
fieldId: fieldId("Tabelle", "Feld für den Export"),
mergeFile: "Feld mit der Originaldatei",
apiKey: "API_KEY",
},
canvas: {
width: 4000,
height: 4000,
offsetX: 0,
offsetY: 0
},
zooming: {
step: 0.25,
min: 0.01,
max: 4
},
drawingSettings: {
strokeWidth: 1,
strokeColor: "#ffffff"
},
artboard: {
width: 1000,
height: 1000,
},
stickerTypes:[{
uid: uid,
image: "stickerBase64",
icon: base64,
label: Name,
width: 100,
height: 100,
originX: 0.5,
originY: 0.89,
default: false
}],
shapes: (Shapes).[{
shapeId: Nr,
movable: true,
shapeDataValue: helper_shapeDataValue,
stickerUID: "",
sidebarItem: {
header: "Titel des Eintrags",
content: "Beschreibung des Eintrags",
}
}],
rightSideContent: {
show: true,
header: "Header",
footer: "Footer"
}
})
```
### 🔸 `embedded`
Gibt an, ob das Widget sich in eine bestehende Maske (z. B. Ninox-Formular) einfügt.
```javascript
embedded: "" // default: false
embedded: true,
```
👀 **Tipp:** Bei `true` ist keine feste Höhe nötig – das Widget passt sich automatisch dem Elterncontainer an.
### 🔸 `height`
Mit dem Parameter `height` gibst du die **Gesamthöhe** des Drawing-Tools in Pixel an.
Er bestimmt, wie viel vertikaler Platz das Widget im eingebetteten Kontext (z. B. in einem Formular oder auf einer Seite) einnimmt.
**Empfehlung: **Das Widget sollte für eine bessere UI idealer Weise in Custom Layout eingebunden werden. Und die Höhe im Layout Block bestimmt werden.
### 🔸 `tableId` & `fieldId`
Diese beiden Parameter definieren, **wo die Formdaten (Shapes)** gespeichert oder geladen werden.
- `**tableId**` gibt die Tabelle an, in der die Shapes verwaltet werden.
- `**fieldId**` verweist auf das konkrete Feld innerhalb dieser Tabelle, das die Geometriedaten (`shapeDataValue`) des jeweiligen Shapes enthält. Achtung: Hier muss ein Ninox-Textfeld verwendet werden.
Du kannst hiermit eigene Formen, Marker oder Objekte dynamisch speichern – z. B. Rechtecke, Sticker, Kreise, Bilder oder Linien.
### 🔸 `dataBag`
Optional. Steuert, wie Shape-Daten in einem **JSON-Topf** (ein Textfeld mit mehreren Keys) gelesen und geschrieben werden – ohne andere Keys zu überschreiben.
```javascript
dataBag: {
key: "pin" // Shape liest/schreibt nur diesen Key im Topf
// encoding: "raw" // Default — Plain-JSON; nur bei Legacy: "urlEncoded"
}
```
**Lesen:** Das Feld `shapeDataValue` pro Shape enthält den gesamten Topf als Plain-JSON. Das Widget extrahiert `key` als Geometrie. In Formeln: `parseJSON(helper_data)` — ohne `urlDecode`.
**Schreiben:** Beim Verschieben wird nur `key` aktualisiert; andere Keys (`placedAt`, `meta`, …) bleiben erhalten.
**Beispiel: Wartungsplan mit Prüfpunkten** (z. B. Gebäudeinspektion):
```json
{
"geo": { "type": "sticker", "stickerUID": "pin_ok", "x": 420, "y": 180, "width": 40, "height": 40 },
"placedAt": "2026-06-13",
"inspectionPointId": "123"
}
```
Ohne `dataBag` bleibt das bisherige Verhalten: das gesamte Feld ist `shapeDataValue` (raw JSON).
> **Hinweis:** Das ist die **Widget-Config** (`key` + `encoding`). Für **Actions** (`update` mit `patch` in State-Bags) gilt dasselbe `dataBag`-Konzept plattformweit — siehe [`data-bag-actions`](../patterns/data-bag-actions.md).
### 🔸 `changeFieldValues`
Erlaubt es, beim **Anlegen eines neuen Shapes** zusätzliche Felder oder Verknüpfungen zu befüllen – z. B. Kategorie, Ersteller o. ä.
Pro Eintrag: `{ fieldId, value }` — `fieldId` ist die Ninox-Feld-ID (z. B. via `fieldId("Tabelle", "Feldname")`).
**Sticker-spezifisch:** Zusätzlich kann jedes Element in `stickerTypes` ein eigenes `changeFieldValues`-Array haben. Beim Platzieren eines Stickers werden zuerst die **globalen** `changeFieldValues` am Drawing gesetzt, danach die des **aktiven Sticker-Typs** — bei gleichem `fieldId` gewinnt der Sticker.
```javascript
changeFieldValues: [{
fieldId: fieldId("Pruefpunkte", "Objekt zuordnen"),
value: number(obj.Nr)
}],
stickerTypes: [{
uid: "pin_ok",
changeFieldValues: [{
fieldId: fieldId("Pruefpunkte", "Kategorie"),
value: "OK"
}]
}]
```
**Laufende Nummern:** Werte wie Positionsnummern oder fortlaufende IDs **nicht** über `changeFieldValues` setzen — der Wert stammt vom letzten Render und ist bei mehreren schnellen Creates falsch. Stattdessen **After-change-Trigger** auf dem Parent-Link-Feld; im Trigger **`myNr := number(Nr)` vor** dem Filter `number(Nr) != myNr`, sonst filtert man sich selbst weg.
### 🔸 `create`
Steuert das **Anlegen neuer Shapes** (Pins, Linien, Rechtecke, Kreise, Bilder) und bündelt optional die Create-Konfiguration. Empfohlen ab dieser Version; die Root-Props `tableId`, `fieldId`, `changeFieldValues` und `setNewRecordId` bleiben **weiterhin gültig** (Legacy).
```javascript
create: {
enabled: if lockCreate then false else true end,
tableId: tableId("Shapes"),
fieldId: fieldId("Shapes", "helper_shapeDataValue"),
changeFieldValues: [{
fieldId: fieldId("Pruefpunkte", "Objekt"),
value: number(obj.Nr)
}],
setNewRecordId: [{
recordId: Nr,
fieldId: fieldId("Objekt", "Letzter Shape")
}]
}
```
| Feld | Beschreibung |
|------|--------------|
| `enabled` | `false` = kein neues Shape (Toolbar ausgegraut, Pan/Klick/`actions` bleiben). Default: `true`. |
| `tableId` | Zieltabelle für neue Shapes (überschreibt Root-`tableId`, falls gesetzt). |
| `fieldId` | Textfeld für Geometrie am **neuen** Datensatz (überschreibt Root-`fieldId`). |
| `changeFieldValues` | Zusatzfelder beim Create (überschreibt Root-`changeFieldValues`). |
| `setNewRecordId` | Nach Create: neuen Datensatz in Parent verlinken (`[{ recordId, fieldId }]`). |
**Hinweise:**
- `dataBag` bleibt am Widget-Root (Lesen + Schreiben bestehender Shapes).
- `stickerTypes[].changeFieldValues` bleibt sticker-spezifisch und ergänzt die globalen Werte.
- Nur `create.enabled: false` reicht zum Sperren — `tableId`/`fieldId` am Root können für bestehende Shapes weiter gesetzt bleiben.
### 🔸 `setNewRecordId` (Legacy am Root)
Optional am Widget-Root oder innerhalb von `create`. Nach dem Anlegen eines Shapes wird der neue Datensatz in ein Referenzfeld geschrieben — z. B. um den Parent-Datensatz zu verknüpfen.
```javascript
setNewRecordId: [{
recordId: Nr,
fieldId: fieldId("Objekt", "Letzter Shape")
}]
```
### 🔸 `exportSettings`
Mit diesem Block konfigurierst du die **Exportfunktion des Widgets**. Du kannst festlegen, in welchen Formaten der Nutzer exportieren darf (z. B. PNG, PDF), wohin die Datei gespeichert werden soll und ob bei PDF ein bestehendes Dokument zusammengeführt wird.
💡 **Hinweis**: Konvertierung in eine vektorisierte PDF fallen Kosten an und es ist eine Verbindung zum Internet notwendig (funktioniert nicht im Offline Modus). Genaue Kosten erfragst du bitte bei dem arcRider Support.
Feld
Beschreibung
`allowedTypes`
Liste der erlaubten Exportformate. Du kannst `"jpg"`, `"png"`, `"svg"` und `"pdf"` angeben.
Beim Format `"pdf"` kannst du zusätzlich `mergeFile: false` oder ein Feldname setzen, um eine bestehende PDF zu ergänzen.
`target`
Legt fest, wohin die Datei exportiert werden soll.
`"file"` bedeutet, die Datei wird heruntergeladen.
`"field"` bedeutet, die Datei wird in ein Datei-Feld in Ninox hochgeladen.
`recordId`
Gibt den Datensatz an, in den exportiert werden soll (nur bei `target: "field"` erforderlich).
`fieldId`
Definiert das genaue Feld im Datensatz, in das die exportierte Datei geschrieben wird.
`mergeFile`
Nur für PDF-Exporte relevant.
Wenn angegeben, wird die exportierte Zeichnung mit der PDF aus diesem Feld zusammengeführt.
`apiKey`
Wird nur für den PDF-Export mit Zusammenführung benötigt.
Hier wird ein API-Schlüssel von Arc Rider verwendet, um das PDF-Rendering serverseitig durchzuführen.
#### 🔄 Auto-Export
Mit `autoExport` kannst du festlegen, dass nach jeder Shape-Änderung automatisch ein Export erfolgt – z. B. um ein Live-Vorschaubild zu speichern.
Die Properties `autoExport`, `autoExportDelay`, `target`, `recordId` und `fieldId` können sowohl global als auch **pro Format** in `allowedTypes` gesetzt werden. Format-spezifische Einstellungen überschreiben die globalen.
**Beispiel mit Auto-Export:**
```javascript
exportSettings: {
allowedTypes: [{
format: "jpg",
target: "field",
recordId: Nr,
fieldId: fieldId("Tabelle", "Vorschaubild"),
autoExport: true,
autoExportDelay: 500 // Verzögerung in ms (default: 500)
}, {
format: "pdf",
target: "file", // Manueller Download
autoExport: false
}]
}
```
| Feld | Beschreibung |
|------|--------------|
| `autoExport` | `true` oder `false` – aktiviert automatischen Export nach jeder Shape-Änderung |
| `autoExportDelay` | Verzögerung in Millisekunden bevor der Export startet (default: 500). Dient als Debounce bei schnellen Änderungen. |
### 🔸 `canvas`
Mit dem `canvas`-Block definierst du die **technische Zeichenfläche**, also den kompletten Bereich, auf dem Shapes gezeichnet und verschoben werden können.
Dieser Bereich kann deutlich größer sein als der sichtbare Ausschnitt (`artboard`) und bestimmt, wie weit sich Nutzer im Zeichenbereich bewegen können (z. B. beim Verschieben oder Zoomen).
#### 🔧 Struktur:
- `width`: Die gesamte Breite der Zeichenfläche in Pixeln.
- `height`: Die gesamte Höhe der Zeichenfläche in Pixeln.
- `offsetX`: Abstand zum linken und rechten Rand – kann genutzt werden, um Inhalte zentriert darzustellen.
- `offsetY`: Abstand zum oberen und unteren Rand – ideal für zusätzliche Arbeitsfläche oder Druckränder.
Tipp: Du kannst durchaus auch dynamische Werte aus Ninox Feldern oderBerechnungen hier einsetzen. Beispielsweise haben wir Workflows entwickelt, in denen wir die Größe des canvas abhängig von der Größe des Hintergrundshapes gemacht haben.
### 🔸 `zooming`
Der `zooming`-Block steuert, **wie weit in das Zeichenfeld hinein- oder herausgezoomt werden kann** – etwa per Mausrad oder Touch-Gesten. Damit definierst du den Zoombereich und wie fein abgestuft gezoomt wird.
#### 🔧 Struktur:
- `step`: Gibt an, wie groß ein Zoom-Schritt ist, z. B. bei Klick auf die Plus/Minus-Buttons oder beim Scrollen mit gedrückter Strg-Taste. Ein kleiner Wert (z. B. `0.1`) bedeutet feinere Zoomschritte.
- `min`: Der **kleinste erlaubte Zoomfaktor** (z. B. `0.1` = 10 %). Damit legst du fest, wie weit man maximal herauszoomen darf.
- `max`: Der **größte erlaubte Zoomfaktor** (z. B. `4` = 400 %). Damit begrenzt du das Hereinzoomen auf eine bestimmte Detailstufe.
💡 **Hinweise:**
- Der initiale Zoom wird automatisch so gesetzt, dass das Artboard gut in das Widget passt.
- Zoomaktionen wirken sich auf die Darstellung der Shapes aus, nicht auf ihre tatsächliche Größe im `canvas`.
- Wird kein `zooming`-Block gesetzt, gelten Standardwerte (Zoom zwischen ca. 10 % und 400 %).
### 🔸 `drawingSettings`
Mit dem `drawingSettings`-Block legst du die **Standard-Eigenschaften für neue Zeichenobjekte** fest – z. B. Linienfarbe und -stärke. Diese Werte gelten für alle neu gezeichneten Formen wie Linien, Rechtecke oder Kreise, solange der Nutzer keine individuellen Einstellungen verändert.
#### 🔧 Struktur:
- `strokeWidth`: Bestimmt die Linienbreite in Pixeln.
Ein Wert von `1` ergibt eine feine Linie, `2` oder `3` wirken etwas kräftiger.
- `strokeColor`: Definiert die Farbe der Linien im Hex-Format, z. B. `#ffffff` für Weiß oder `#ffaa21` für Orange.
💡 **Hinweis:**
Du kannst `strokeColor` und `strokeWidth` auch **aus Ninox-Feldern dynamisch übergeben**, um die Zeichenoptionen z. B. **vom Nutzer auswählbar zu machen**. So kannst du pro Datensatz individuelle Zeichenstile ermöglichen.
### 🔸 `toolbarSettings`
Optional. Steuert **Reihenfolge, Sichtbarkeit und Gruppierung** der Toolbar-Buttons. Ohne `toolbarSettings` bleibt das Standard-Layout unverändert (Move, Zeichenwerkzeuge, Stickers-Untermenü, Export).
#### Struktur
- `top`: Buttons in der oberen Toolbar-Leiste (von oben auf Desktop / links auf Mobile).
- `bottom`: Buttons in der unteren Leiste (Export etc.).
#### Einträge in `top` / `bottom`
| Form | Bedeutung |
|------|-----------|
| `"move"` | Tool mit Standard-Icon (Kurzform) |
| `{ tool: "draw", icon: "..." }` | Tool mit eigenem Icon (URL, Base64 oder SVG) |
| `"stickers"` | Alle `stickerTypes` **direkt** in der Toolbar (Ebene 1) |
| `{ sticker: "pin_rot" }` | Nur dieser Sticker direkt in der Toolbar |
| `{ group: "zeichnen", icon: "...", items: ["draw", "rect", "circle"] }` | Gruppe mit Unterpanel (wie bisher bei Stickers/Export) |
**Weglassen = nicht anzeigen.** Es gibt kein separates `enabled`-Flag — was nicht im Layout steht, erscheint nicht.
#### Beispiel: Prüfpunkt-Pins, nur Move + ausgewählte Sticker
```javascript
toolbarSettings: {
top: [
"move",
{ sticker: "pin_rot" },
{ sticker: "pin_gruen" }
],
bottom: ["export"]
}
```
#### Beispiel: Zeichenwerkzeuge gruppieren
```javascript
toolbarSettings: {
top: [
"move",
{
group: "zeichnen",
label: "Zeichnen",
icon: "data:image/svg+xml,...",
items: ["draw", "rect", "circle"]
},
"image",
"stickers"
],
bottom: ["export"]
}
```
### 🔸 `artboard`
Der `artboard`-Block definiert den **sichtbaren Ausschnitt deiner Zeichenfläche** – also das, was der Nutzer beim Öffnen des Widgets zunächst sieht. Es handelt sich sozusagen um das „Papier“, auf dem gezeichnet wird – während der `canvas`-Bereich das „gesamte Atelier“ darstellt.
#### 🔧 Struktur:
- `width`: Breite des sichtbaren Zeichenbereichs in Pixeln.
- `height`: Höhe des sichtbaren Zeichenbereichs in Pixeln.
Dieser Bereich wird automatisch zentriert und skaliert dargestellt, sodass er vollständig im Widget sichtbar ist (abhängig von Zoom- und Darstellungsparametern).
💡 **Hinweise:**
- Das `artboard` ist rein visuell – alle Shapes können sich auch **außerhalb dieses Bereichs** befinden, solange sie innerhalb des `canvas` liegen.
- Wenn du ein bestimmtes Seitenverhältnis möchtest (z. B. A4 oder Quadrat), kannst du die `width` und `height` entsprechend setzen.
- In Kombination mit `zooming` und `canvas` kannst du gezielt steuern, wie viel Platz Nutzer:innen für ihre Zeichnung haben – und was beim Start sofort sichtbar ist.
Tipp: Du kannst durchaus auch dynamische Werte aus Ninox Feldern oderBerechnungen hier einsetzen. Beispielsweise haben wir Workflows entwickelt, in denen wir die Größe des artboards abhängig von der Größe des Hintergrundshapes gemacht haben. Dadurch scrollt der User nicht so viel hin und her.
### 🔸 `stickerTypes`
Der `stickerTypes`-Block erlaubt es dir, **individuelle Sticker** bereitzustellen, die Nutzer im Zeichenbereich platzieren können – z. B. Icons, Symbole, Marker oder Piktogramme.
Jeder Sticker ist ein Objekt mit Eigenschaften wie Bildquelle, Größe und Positionierungsverhalten.
Ideal für Use Cases wie:
- 🔧 Technische Markierungen auf Fotos oder Plänen
- 📍 Standortpins auf Karten oder Grundrissen
- 👕 Qualitätskontrollen in der Modebranche
- 🏥 Medizinische Annotationen auf Körpersilhouetten
#### 🔧 Struktur je Sticker:
- `uid`: Eindeutige ID des Stickers (z. B. `"pin_rot"`).
- `image`: Base64-Daten-URL oder URL zur Grafik — wird beim Platzieren auf dem Canvas verwendet.
- `icon` (optional): Vorschaubild **nur** für den Toolbar-Button (wenn abweichend vom Stickerbild). Erlaubt sind:
- Bild (SVG-Markup, PNG/JPG/Data-URL, HTTP-URL) — wie `image`
- `arcCustomIcon`-Widget-Objekt: `{ widget: "arcCustomIcon", data: { iconSet: "phosphor", name: "map-pin", color: "#1565c0" } }`
- `label`: Bezeichnung des Stickers. Zwei Formen möglich:
- **String** (Legacy): nur Tooltip beim Hovern über dem Toolbar-Button, kein sichtbarer Text.
- **Objekt** (neu): sichtbarer Text unter dem Icon im Toolbar-Button — `{ value: "K", visible: true, fontColor: "#1565c0", fontSize: 10, maxWidth: 50 }`. `visible: false` verhält sich wie der String-Fall (nur Tooltip). Zu langer Text wird bei `maxWidth` mit `…` abgeschnitten.
- `width`: Breite des Stickers in Pixeln.
- `height`: Höhe des Stickers in Pixeln.
- `originX`: Horizontaler Ankerpunkt (0 = links, 0.5 = Mitte, 1 = rechts).
- `originY`: Vertikaler Ankerpunkt (0 = oben, 0.5 = Mitte, 1 = unten).
- `default` (optional): Wenn `true`, wird dieser Sticker vorausgewählt.
- `labelPlaceholder` (optional): Platzhalter-String im SVG (`image`), der durch `label` am Shape ersetzt wird — Konvention: `##LABEL##` (wie bei anderen arcWidgets: `##key##`).
- `defaultLabel` (optional): Fallback für `label` direkt beim Platzieren, bis Ninox die Formel neu liefert.
- `defaultPlaceholders` (optional): Fallback-Objekt für `shape.placeholders` beim Platzieren (gleiche Keys wie im SVG).
- `changeFieldValues` (optional): Zusätzliche Felder beim **Anlegen** eines Datensatzes für diesen Sticker-Typ — merged mit globalen `changeFieldValues` (Sticker überschreibt bei gleichem `fieldId`).
#### Dynamische SVG-Platzhalter (Sticker + Shape)
Für Marker mit Text, Status-Dot und Icons kann das **SVG-Template** Platzhalter enthalten. Das Widget ersetzt sie beim Rendern und im Export:
| Quelle | Ersetzung |
|--------|-----------|
| `stickerType.labelPlaceholder` + `shape.label` | z. B. `##LABEL##` → `"K15"` |
| `shape.placeholders` (Objekt) | Jeder Key `foo` ersetzt `##foo##` im SVG |
| `stickerType.defaultLabel` / `defaultPlaceholders` | Sofort beim Platzieren, bis Ninox reagiert |
**Data-URL-Hinweis:** Wenn das SVG per `encodeURIComponent` in `data:image/svg+xml,…` eingebettet ist, ersetzt das Widget Platzhalter auch in URL-kodierter Form (z. B. `%23%23LABEL%23%23` → `K15`, `%23ff0000` für `#ff0000`).
**Warum `##key##`?** Wie bei arcCustomInput (`##inputValue##`) und arcCustomCalendarWeek (`##clickedDate##`). Anders als `{{key}}` kollidiert `##key##` nicht mit der Ninox-Syntax `{variable}` in Text-Blöcken.
Beispiel `shape.placeholders` für Status-Icons via `display` (alle Varianten im SVG, Ninox schaltet Sichtbarkeit):
```javascript
placeholders: {
statusColor: "#4caf50",
showCheck: "block",
showWarn: "none",
showError: "none"
}
```
Beispiel `defaultPlaceholders` am `stickerType` (Fallback bis Ninox reagiert):
```javascript
defaultLabel: "",
defaultPlaceholders: {
statusColor: "#9e9e9e",
showCheck: "none",
showWarn: "none",
showError: "none"
}
```
Neue Platzhalter erfordern **keine Widget-Änderung** — nur `##key##` ins SVG und passenden Key in `shape.placeholders`.
💡 **Hinweise:**
- Die Sticker erscheinen im linken Menü des Widgets unter „Stickers“.
- Beim Platzieren eines Stickers wird seine Position automatisch anhand von `originX` / `originY` berechnet. So kannst du z. B. Marker exakt mit ihrer Spitze am Klickpunkt ausrichten.
- Du kannst beliebig viele Sticker definieren – z. B. farbige Pins, Icons für Mängel, Emojis, Status-Symbole etc.
- Die Sticker-Grafiken sollten idealerweise als **SVG** oder als **PNG mit transparentem Hintergrund** vorbereitet sein.
**Tipp**: Erstell dir eine Ninox-Tabelle mit Stickern. Lade deine SVG oder PNG Datei in ein Bildfeld. Nutze die Ninox Funktion `loadFileAsBase64URL(Image)`in einem Funktionsfeld, um das base64 für deine Stickerliste im Drawing zu erhalten. Natürlich kannst du in deiner Stickerliste auch gleich Breite, Höhe, Name … definieren.
### 🔸 `shapes`
Der `shapes`-Block definiert die Liste der **Zeichenobjekten**, die du im Widget hinterlegst. Jedes Objekt im Array entspricht einem gespeicherten Eintrag in deiner `tableId` und enthält die nötigen Informationen zur Darstellung, Position und Interaktion.
Wichtig: Um Drawing korrekt nutzen zu können, ist es essentiell eine Tabelle Shapes aufzusetzen und darin mindestens ein Textfeld `helper_shapeDataValue` anzulegen.
#### 🔧 Struktur je Shape:
- `shapeId`: Die eindeutige ID des Shapes (meist die `Nr` des Datensatzes).
- `movable`: Gibt an, ob das Objekt im Zeichenbereich verschoben werden darf (`true` oder `false`). `false` sperrt nur das Verschieben — Klick, Hover und `actions` funktionieren weiterhin. Im **Sticker-Modus**: Shapes mit `actions` fangen Klicks ab (z. B. Detail in Sidebar); reine Hintergrund-Shapes ohne `actions` lassen Pin-Platzierung durch.
- `shapeDataValue`: Die gespeicherten Formdaten (z. B. Koordinaten, Größe, Farbe, Typ etc.). Mit `dataBag.key` kann hier der gesamte JSON-Topf stehen; das Widget nutzt dann nur den Key-Wert als Geometrie.
- `label` (optional): Dynamischer Text für Sticker mit `labelPlaceholder` im `stickerType`.
- `placeholders` (optional): Objekt mit zusätzlichen SVG-Ersetzungen — jeder Key ersetzt `##key##` im Sticker-SVG (z. B. `statusColor`, `showCheck`).
- `scalable` (optional): Bei Stickern standardmäßig `false` — für pixel-stabile Marker auf Plänen setzen.
- `actions`: Optional – Liste von Aktionen, die bei **Klick** (nicht beim Draggen) ausgeführt werden. Gleiches Format wie bei anderen arcWidgets (`update`, `popup`, `openRecord`, …). Unterstützt plain `value` oder `dataBag`/`patch` für partielle Updates in einen State-Topf:
```javascript
actions: [{
type: "update",
recordId: stateRecordId,
fieldId: stateField,
dataBag: {
base: helper_mainContentState,
patch: { selectedShape: Nr }
}
}]
```
Typischer Use-Case: Shape-ID in einen gemeinsamen UI-State schreiben → Sidebar (`rightSideContent`) zeigt das Detail. Ausführlich: [`data-bag-actions`](../patterns/data-bag-actions.md).
- `stickerUID`: Wenn du einen anderen Sticker, als den initial erstellten, anzeigen möchtest (z. B. weil sich ein Status geändert hat), musst du hier die UID des entsprechenden Stickers angeben.
- `sidebarItem`: Optional – zeigt das Shape zusätzlich in der rechten Seitenleiste an, mit:
`header`: Titel (z. B. „Mangel #3“)
- `content`: Beschreibung oder weitere Infos
- `hide`: `true` oder `false` – blendet das Item in der Sidebar aus, ohne es zu löschen (z. B. für gefilterte Ansichten)
### Rezept: Wartungsplan mit Prüfpunkten
Typisches Setup für Gebäudeinspektion, Anlagenwartung oder ähnliche Plan-basierte Marker — ein **nicht verschiebbarer Plan-Hintergrund** plus **verschiebbare Prüfpunkt-Pins** mit Persistenz in einer Kind-Tabelle.
#### Bausteine
1. **Plan-Hintergrund** — ein Shape mit `type: "image"`, volle Artboard-Größe, `movable: false`, `hidden: true` (nur visuell, nicht in Sidebar). Bild aus Upload via `loadFileAsBase64URL(PlanBild)`.
2. **Prüfpunkt-Shapes** — aus `(select Pruefpunkte where Objekt = obj.Nr)` mit `movable`, `placeholders`, `actions` (Selection in State schreiben).
3. **`dataBag: { key: "geo" }`** am Drawing — Geometrie in JSON-Topf, Metadaten (`placedAt`, `inspectionPointId`, …) bleiben erhalten.
4. **`canvas` / `artboard`** — aus Upload-Metadaten (Breite/Höhe des Plans).
5. **`toolbarSettings`** — nur Move + die benötigten Sticker inline (siehe Beispiel oben).
6. **Verschieben sperren** — Boolean im State (`lockShapeMove`), pro Shape `movable: if lockShapeMove then false else true end`. Toggle per Button mit `dataBag`-Patch. Siehe State-Management-Rule (`07-state-management.mdc`).
### 🔸 `rightSideContent`
Der Block `rightSideContent` steuert, **ob eine rechte Seitenleiste im Widget angezeigt wird** und was dort dargestellt werden soll. Diese Sidebar ist besonders nützlich, um eine Liste der gezeichneten Elemente anzuzeigen oder zusätzliche Informationen bereitzustellen.
#### 🔧 Struktur:
- `show`: `true` oder `false` – aktiviert oder deaktiviert die rechte Sidebar.
- `header`: (optional) Widgets oder Textinhalt für den oberen Bereich der Sidebar.
- `footer`: (optional) Widgets oder Textinhalt für den unteren Bereich der Sidebar.
- `content`: (optional) Individuelle Konfiguration des mittleren Inhalts.
Wenn `show: true` gesetzt ist und die Shapes `sidebarItem`-Einträge enthalten (siehe `shapes`), wird automatisch eine **interaktive Liste aller Shapes** angezeigt – mit Titel, Beschreibung, Hover-Effekt und Auswahlverhalten.
🔍 `content`-Block im Detail:
- `showShapeLayers`:
Wenn `true`, wird eine automatische Liste aller vorhandenen Shapes (mit `sidebarItem`) angezeigt – inklusive Titel, Beschreibung, Hover- & Klickverhalten.
Ideal z. B. für Mängellisten, Prüfpunkte oder Annotationen.
- `customLayout`:
Optionaler benutzerdefinierter Inhalt, der im mittleren Bereich angezeigt werden kann.
Hier kannst du z. B. HTML, Ninox-Formelergebnisse oder vorbereitete Layout-Komponenten einbinden.
Wenn `showShapeLayers` aktiv ist, wird die Shape-Liste angezeigt. Wenn du stattdessen ein eigenes Layout anzeigen willst, kannst du `customLayout` nutzen.
💡 **Hinweise:**
- Die Sidebar funktioniert besonders gut, wenn du Shapes mit `sidebarItem`-Infos versiehst.
- Der Bereich kann je nach Use Case rein informativ, interaktiv oder visuell angepasst werden.
- Du kannst `customLayout` auch dynamisch aus einem Ninox-Feld übernehmen – z. B. über eine Textformel oder HTML-Komponente.
- Wenn du beides kombinieren möchtest (Layer-Liste + eigene Inhalte), kannst du `customLayout` über dem Footer einfügen und `showShapeLayers` auf `true` lassen.
### 🔧 Kein Entwickler? Kein Problem.
Du hast keine Zeit, dich mit Code und Konfiguration zu beschäftigen? Wir vom **arcRider-Team** bieten dir einen **Installations- und Einrichtungssupport** für das `arcCustomDrawing`-Widget an – maßgeschneidert auf deinen Anwendungsfall.
➡️ **Schreib uns einfach an **[**office@arc-rider.com**](mailto:office@arc-rider.com).
Wir helfen dir, in wenigen Stunden loszulegen – ohne technisches Kopfzerbrechen.
---
# Custom Gantt
Source: https://www.arc-rider.com/docs/widgets/gantt
# Custom Gantt
## AI Defaults (read first)
- **Function name**: `arcGantt` (NOT `arcCustomGantt`).
- **uniqueId**: Required, `"gantt-" + Nr`.
- **ganttSettings**: `height`, `embedded`, `showScrollbar` live here (NOT at root level).
- **height**: `ganttSettings: { height: "100%" }` when embedded in dashboard.
- **years**: Array of integers, e.g. `[2025, 2026]`.
- **items**: Each item needs `recordId: Nr` and `timeEntries` array.
- **timeEntries**: Each needs `recordId: Nr`, `startDate`, `endDate` (date field values).
- **Hierarchy**: Nest `items` arrays inside parent items for tree structure.
- **sidebarSettings**: `width: "400px"` for the left sidebar.
# Custom Gantt
Das arcGantt Widget ist ein interaktives Tool zur grafischen Planung und Verwaltung von beispielsweise Projekten, Aufgaben und Zeiträumen. Es ermöglicht eine klare Balkendarstellung von Zeitverläufen, unterstützt hierarchische Strukturen und bietet eine dynamische Steuerung per Klick.
Typische Einsatzbereiche:
✔ Projektmanagement – Aufgaben & Deadlines verwalten
✔ Ressourcenplanung – Verfügbarkeiten im Blick behalten
✔ Einsatzplanung – Teams & Termine effizient organisieren
Das Widget lässt sich flexibel in deiner Ninox Datenbank integrieren und auf deinen Anwendungsfall anpassen. In den folgenden Abschnitten erfährst du, wie du das Widget konfigurierst. 🚀
## Anwendungscode
```javascript
let data := {
uniqueId: "Projekt Gantt",
ganttSettings: {
height: "800px",
embedded: false,
showScrollbar: true,
currentZoomLevel: 500,
nativeCollapse: true,
},
dateSettings: {
highlights: [{
title: "Feiertag",
date: date(2024, 1, 1),
backgroundColor: "",
color: "#fff"
}, {
title: "Heute",
date: today(),
backgroundColor: "#e9595c10",
color: "#fff"
}, {
title: "Samstag",
weekday: 6,
backgroundColor: "",
color: "#fff"
}, {
title: "Sonntag",
weekday: 7,
backgroundColor: "",
color: "#fff"
}]
},
timeSettings: {
amount: 1,
startTime: 6,
duration: 12
},
createModeSettings: {
show: false,
amount: 2
},
barSettings: {
height: "40px",
borderRadius: "10px"
},
sidebarSettings: {
width: "400px",
title: "Einsatzplanung",
clickActions: [{
title: "Heute",
date: today(),
position: ""
}, {
title: "Q1",
date: date(2024, 1, 1),
position: ""
}, {
title: "Q2",
date: date(2024, 4, 1),
position: ""
}, {
title: "Q3",
date: date(2024, 7, 1),
position: ""
}, {
title: "Q4",
date: date(2024, 10, 1),
position: ""
}, {
title: "Christmas",
date: date(2024, 12, 24),
position: ""
}]
},
years: [2025,2026,2027],
items: (select Projekte where Aktiv=true).[{
recordId: Nr,
title: Name,
backgroundColor: "",
height: "100px",
barSettings: {
height: "20px",
borderRadius: "50px",
borderColor: "",
backgroundColor: ""
},
clickAction:true,
timeEntries: [{
title: Name,
recordId: Nr,
startDate: min(Aufgaben.Startdatum),
endDate: max(Aufgaben.Enddatum),
clickAction: true,
barSettings: {
height: "20px",
borderRadius: "50px",
borderColor: "",
backgroundColor: ""
},
}],
items: Aufgaben.[{
recordId: Nr,
title: "Aufgaben",
backgroundColor: "",
height: "100px",
barSettings: {
height: "20px",
borderRadius: "4px",
borderColor: "",
backgroundColor: ""
},
timeEntries: [{
recordId: Nr,
title: Aufgabe.Bezeichnung,
startDate: Startdatum,
endDate: Enddatum,
startTime: Startzeit,
endTime: Endzeit,
clickAction: true,
barSettings: {
height: "20px",
borderRadius: "50px",
borderColor: "",
backgroundColor: ""
},
}]
}]
}]
};
arcCustomGantt(data)
```
## Einzelne Parameter
### `**uniqueId**`
`uniqueID` ist die individuelle Bezeichnung deines Gantts. Achte darauf, dass du hier einen einzigartigen Titel vergibst. Das ist wichtig, falls du mehrere Gantts auf einer Seite darstellen möchtest und sich keine Style-Einstellungen überschreiben.
### `**ganttSettings**` Block
Der Block `ganttSettings` enthält allgemeine Anzeigeeinstellungen für das Gantt-Diagramm – also wie das Gantt selbst dargestellt wird, unabhängig von seinen Inhalten.
#### `**height**` im `**ganttSettings**` Block
`height` bestimmt die Höhe des Gantt-Diagramms in Pixeln. Beispiel: `"800px"`
#### `**embedded**` im `**ganttSettings**` Block
Mit dem Parameter `embedded` legst du fest, ob dein Gantt-Diagramm **eigenständig** angezeigt oder **in ein anderes Widget eingebettet** wird.
#### `**showScrollbar**` im `**ganttSettings**` Block
Mit `showScrollbar` bestimmst du, ob unterhalb des Gantt-Diagramms eine **horizontale Scrollbar** angezeigt wird.
Das ist besonders hilfreich für User ohne Touchpad oder Maus mit horizontalem Scrollrad – sie können dann bequem per Klick auf der Scrollbar im Zeitraster nach rechts oder links navigieren.
#### `**currentZoomLevel**` im `**ganttSettings**` Block
Mit `currentZoomLevel` legst du die **Zoomstufe** deines Gantt-Diagramms fest. Der Wert wird als **Prozentzahl** angegeben.
- Ein höherer Wert (z. B. `500`) bedeutet eine stärkere Vergrößerung – die einzelnen Zeitblöcke im Grid werden größer dargestellt.
- Ein niedrigerer Wert (z. B. `100`) zeigt mehr Zeitraum auf einmal, aber in kleinerem Maßstab.
So kannst du steuern, wie detailliert oder wie übersichtlich dein Gantt beim Laden angezeigt wird.
#### `**nativeCollapse**` im `**ganttSettings**` Block
Mit `nativeCollapse` steuerst du, ob die **standardmäßigen Auf- und Zuklapp-Icons** für hierarchische Gantt-Einträge automatisch angezeigt werden.
- `true` → Die Gantt-Komponente zeigt automatisch die bekannten Pfeil-Icons zum Ein- und Ausklappen von Gruppen oder Unterpunkten.
- `false` → Du übernimmst selbst die Kontrolle über die Darstellung und Funktion – z. B. mit eigenen Icons und Klick-Logiken.
Das ist besonders nützlich, wenn du ein individuelles Verhalten oder Design für die Aufklappfunktion brauchst.
Wenn du `nativeCollapse` auf `false` setzt, kannst du eine **eigene Logik zum Ein- und Ausklappen** deiner Gantt-Einträge umsetzen.
Dazu steuerst du die Anzeige der untergeordneten Items mithilfe einer `**if**`**-Bedingung**, die auf ein **Hilfsfeld** wie z. B. `showChildren` zugreift:
Diese Methode ist nicht nur flexibel, sondern auch **performancefreundlich**: Unterelemente werden nur geladen und angezeigt, wenn sie tatsächlich sichtbar sein sollen – das reduziert Ladezeiten und sorgt für flüssigere Interaktionen im Gantt.
### `**dateSettings**` Block
Mit dem `dateSettings`-Block kannst du **bestimmte Tage oder Daten im Gantt-Grid visuell hervorheben** – z. B. Feiertage, Projekt-Deadlines oder andere wichtige Zeitpunkte.
Jedes Highlight kannst du individuell gestalten, z. B. mit eigener Hintergrundfarbe und Linienfabre der Zeilen.
### `**timeSettings**` Block
Der `timeSettings` Block ist ein besonders geeignetes Feature, wenn du nicht 24 Stunden eines Tages darstellen möchtest, sondern nur eine bestimmte Stundenanzahl je Tag. Das kann sinnvoll sein, wenn du zum Beispiel Mitarbeitereinsätze einplanen möchtest und dir dabei nur die wirklichen Arbeitsstunden des Tages anzeigen lässt. Zum Beispiel 08:00 Uhr bis 18:00 Uhr.
### `**amount**` in `**timeSettings**`
Mit dem Parameter `amount` legst du fest, in welche Zeiteinheiten ein Tag im Gantt-Diagramm unterteilt wird. Standardmäßig ist eine Stunde (also `1`) eingestellt – das bedeutet, jede Spalte im Gantt steht für eine Stunde.
Wenn du feinere Einteilungen möchtest, kannst du zum Beispiel `0.5` angeben, um halbstündliche Intervalle anzuzeigen. Auch kleinere Werte wie `0.25` (15 Minuten) sind möglich – je nachdem, wie detailliert du deine Zeitplanung darstellen möchtest.
💡Hinweis: Achte darauf, dass du Dezimalzahlen mit einem Punkt, und nicht einem Komma trennst.
### `**startTime**` in `**timeSettings**`
Mit dem Parameter `startTime` bestimmst du, ab welcher Uhrzeit der Tag im Gantt-Diagramm beginnen soll.
Standardmäßig würde der gesamte 24-Stunden-Tag angezeigt. Wenn du jedoch nur einen bestimmten Zeitraum darstellen möchtest – zum Beispiel einen typischen Arbeitstag ab 8 Uhr – dann gibst du einfach `8` an. Das Gantt-Diagramm startet dann bei Stunde 8 (also 08:00 Uhr) und zeigt keine früheren Zeiten an.
### `**duration**` in `**timeSettings**`
Mit dem Parameter `duration` legst du fest, wie viele Stunden im Gantt-Diagramm ab der `startTime` angezeigt werden.
Das ist besonders hilfreich, wenn du nur einen bestimmten Zeitraum – z. B. einen klassischen Arbeitstag – abbilden möchtest. Wenn du zum Beispiel `startTime: 8` und `duration: 10` angibst, wird der Zeitraum von 08:00 Uhr bis 18:00 Uhr dargestellt.
### `**createModeSettings**` Block
Mit dem `createMode`-Block legst du fest, ob User direkt im Gantt-Diagramm per Hover einen neuen Eintrag erstellen dürfen.
Innerhalb dieses Blocks definierst du auch den Parameter `amount`, der bestimmt, wie viele Stunden ein neu erstellter Eintrag standardmäßig umfassen soll.
Beispiel: Wenn `amount: 2` gesetzt ist, wird bei einem Klick auf das Gantt automatisch ein Termin mit einer Dauer von 2 Stunden erstellt.
### `**barSettings**` Block
Die `barSettings` können auf jeder Ebene deiner hierarchischen Gantt-Items individuell festgelegt werden.
Wenn eine untergeordnete Ebene (z. B. ein Task) keine eigenen Einstellungen hat, übernimmt sie automatisch die `barSettings` der übergeordneten Ebene. So musst du nicht jede Einstellung mehrfach definieren und behältst trotzdem maximale Flexibilität.
### `**sidebarSettings**` Block
Die `sidebarSettings` bestimmen das Aussehen und Verhalten der linken Seitenleiste im Gantt-Diagramm.
- Über den Parameter `title` legst du die Überschrift des Gantt-Diagramms fest.
- Mit `customText` kannst du diesen Titel zusätzlich stylen – z. B. Schriftgröße, Farbe oder Formatierung.
- `position` bestimmt die Position des Sichtfensters, das beim Springen zu einem spezifischen Datum angezeigt wird. Das Datum kann also linksbündig oder mittig im Sichtfenster angezeigt werden.
Außerdem kannst du `clickActions` definieren:
Damit bestimmst du, was passieren soll, wenn ein Nutzer auf einen Eintrag in der Sidebar klickt.
Ein typisches Beispiel: Per Quicklink springt der Gantt-View automatisch zu einem bestimmten Datum, das du vordefiniert hast.
### `**years**`
Mit dem Parameter `years` legst du fest, welche Jahreszahlen im Gantt-Diagramm angezeigt werden sollen. Du kannst entweder ein einzelnes Jahr oder eine ganze Spanne definieren – zum Beispiel:
Es ist auch möglich, die Anzeige dynamisch zu steuern – etwa über ein Ninox-Feld. So kann der User per Auswahlfeld selbst bestimmen, welche Jahre im Gantt dargestellt werden sollen.
### `**items**` Abschnitt
Der Abschnitt `items` definiert die konkreten Inhalte deines Gantt-Diagramms.
Dabei legst du fest:
- **Was in der linken Sidebar** (also den Zeilenüberschriften) angezeigt wird
- **Und was im Content-Bereich des Gantts** (also dem Zeitraster) für jede Zeile dargestellt wird
Typischerweise arbeitest du hier mit einer `**for**`**-Schleife**, um dynamisch auf Werte bzw. Datensätze aus einer Ninox-Tabelle zuzugreifen. So kannst du dein Gantt automatisch mit den relevanten Daten füllen – etwa so:
### `**items**` in der Sidebar
Im oberen Bereich des `items`-Blocks definierst du, **wie die einzelnen Zeilen (Rows) in der linken Sidebar des Gantt-Diagramms aussehen sollen**.
Du kannst hier z. B. Titel, Farben, Höhe, Bar-Styling und Klickverhalten festlegen.
- `recordId`: Verknüpft das Sidebar-Item mit einem konkreten Datensatz. Wird unter anderem für die `clickAction` benötigt.
- `title`: Der Text, der in der linken Spalte angezeigt wird – z. B. der Projektname. Hier kannst du auch ganz eigene Designs mithilfe anderer Widgets, wie Custom Layout, custom text oder Selects gestalten.
- `clickAction`: Ermöglicht, dass ein Klick auf das Sidebar-Item zum zugehörigen Record führt.
- `barSettings`: Hier kannst du das Aussehen des zugehörigen Zeitbalkens im Grid-Bereich steuern – unabhängig vom Stil der Sidebar.
### `**timeEntries**` – Zeiteinträge im Content-Bereich
Im `timeEntries`-Block definierst du, **wie die einzelnen Zeiteinträge im Zeitraster (Content-Bereich) des Gantt-Diagramms dargestellt werden**.
Ein `timeEntry` ist dabei **ein Balken auf der Zeitachse** – also ein Zeitraum mit Start- und Enddatum, der z. B. ein Projekt oder eine Aufgabe visualisiert.
#### Wichtige Eigenschaften:
- **Mehrere Zeiteinträge pro Zeile möglich**
Du kannst beliebig viele `timeEntries` pro Item definieren – z. B. wenn ein Projekt mehrere Zeitabschnitte hat.
- `**title**`
Der Text, der im Balken angezeigt wird – kann auch durch Widgets ersetzt oder dynamisch gefüllt werden.
- `**recordId**`
Verlinkt den Eintrag mit einem Datensatz. In Verbindung mit `clickAction` wird so ein Klick auf den Balken zur Detailansicht weitergeleitet.
- `**startDate**`** / **`**endDate**`
Bestimmen die Position und Breite des Balkens auf der Zeitachse.
- `**barSettings**`
Für jedes `timeEntry` kannst du eigene Styles definieren – z. B. eine andere Farbe für unerledigte Aufgaben (`backgroundColor: "#ef1d2e"`).
Bei Fragen zur Konfiguration oder bei individuellen Anwendungsfällen hilft dir das Entwicklerteam gerne weiter.
Schau auch in die Beispiele oder hole dir Inspiration in der Discord Community.
Happy Widgeting 🥳
---
# Custom Grid
Source: https://www.arc-rider.com/docs/widgets/custom-grid
# Custom Grid
## AI Defaults (read first)
- **uniqueId**: Required, `"grid-" + Nr`.
- **columns**: String value (e.g. `"3"`), NOT a number. Default: auto-fill.
- **columnWidth**: Default `"200px"`, controls minimum column width in auto-fill mode.
- **gap**: Default `"2px"`, typically set to `"10px"` or `"16px"`.
- **height**: Use `"auto"` or `"100%"` depending on context.
- **blocks**: Each block can have `width`, `height`, `alignX`, `alignY`.
- **embedded**: Set `true` when inside another widget.
# Custom Grid
Das Custom Grid ermöglicht die Erstellung von flexiblen und leistungsstarken Layouts durch die Definition eines zweidimensionalen Rasters. Durch die Festlegung von Spalten und Zeilen hast du eine präzise Kontrolle über die Anordnung von Inhalten, was besonders nützlich für die Schaffung komplexer Layoutstrukturen und die Gestaltung responsiver Designs ist.
Der grundlegende Unterschied zwischen dem Grid und Layout besteht darin, dass das Layout in einer Dimension konzipiert wurde – entweder einer Zeile *oder* einer Spalte. Grid wurde für ein zweidimensionales Layout konzipiert – Zeilen und Spalten gleichzeitig.
Beispiel-Bild eines Rasters mit der Integration von [Cards ](/documentation/cards)und [Layouts](/documentation/custom-layout):
## Anwendungscode manuell
Bei einem manuellen Grid kannst du die Blöcke einzeln definieren und die Anzahl der Blöcke & deren Inhalte beliebig selbst bestimmen.
```javascript
arcCustomGrid({
uniqueId: "",
width: "100%",
height: "100%",
columns: "2",
columnWidth: "400px",
gap: "10px",
paddingY: "20px",
paddingX: "20px",
blocks: [{
blockId: "",
width: "",
height: "",
alignX: "center",
alignY: "center",
paddingY: "",
paddingX: "",
backgroundColor: "",
lineHeight: "",
styles: "",
value: ""
},{
blockId: "",
width: "",
height: "",
alignX: "center",
alignY: "center",
paddingY: "",
paddingX: "",
backgroundColor: "",
lineHeight: "",
styles: "",
value: ""
}]
})
```
## Anwendungscode dynamisch
Bei einem dynamischen Grid, speist du die einzelnen Block-Elemente aus einer dynamischen Liste in das Grid ein. Im Anwendungscode kannst du vor deinen block-Elementen deine Liste referenzieren. Hier im Beispiel aus einer Aufgaben-Tabelle.
```javascript
let aufgabe := (select Aufgaben);
arcCustomGrid({
uniqueId: "",
width: "100%",
height: "100%",
columns: "2",
columnWidth: "400px",
gap: "10px",
paddingY: "20px",
paddingX: "20px",
blocks: aufgabe.[{
blockId: "",
width: "",
height: "",
alignX: "center",
alignY: "center",
paddingY: "",
paddingX: "",
backgroundColor: "",
lineHeight: "",
styles: "",
value: ""
}]
})
```
## Allgemeine Settings
Die oberen Parameter geben die allgemeinen Settings deines Grids an.
### uniqueId
*uniqueId* ist die individuelle Bezeichnung deines Grids. Achte darauf, dass du hier einen einzigartigen Titel vergibst. Das ist wichtig, falls du mehrere Grids auf einer Seite / in einer Tabelle darstellen möchtest und diese sich nicht gegenseitig überschreiben.
```javascript
uniqueId: "Grid Aufgaben"+Nr,
```
### width
*width* gibt die Breite deines Grids an.
```javascript
width: "100%", // Prozent-Werte. Hier: volle Breite.
width: "100px", // Pixel-Werte
width: "" // default: 100%
```
### height
*height* gibt die Höhe des Grids an.
```javascript
height: "auto", // Automatisch an den Inhalt angepasste Höhe.
height: "300px", // Pixel-Werte
height: "", // default: auto
```
### columns
*columns* definiert wie viele Spalten (also wie viele Blöcke je Zeile) in deinem Grid angezeigt werden.
```javascript
columns: "2", // Zahlen-Wert
columns: "", // default: auto-fill
```
### columnWidth
*columnWidth* definiert wie breit deine einzelnen Spalten, die du unter columns angibst, sein sollen.
```javascript
columnWidth: "400px", // Pixel-Wert
columnWidth: "", // default: 200px
```
### gap
*gap* gibt den Abstand zwischen den einzelnen Blöcken (nicht nur Spalten!) an.
```javascript
gap: "10px", // Pixel-Werte
gap: "", // dafault: 2px
```
### paddingX
*paddingX gibt den Abstand zwischen dem Inhalt (hier: Blöcke) und dem Rand jeweils links und rechts an. *
```javascript
paddingX: "20px", // Pixel-Werte
paddingX: "", // default: 0px
```
### paddingY
*paddingY gibt den Abstand zwischen dem Inhalt (hier: Blöcke) und dem Rand jeweils oben und unten an. *
```javascript
paddingY: "20px", // Pixel-Werte
paddingY: "", // default: 0px
```
## Block Settings
In den Block Settings gibst du an, was in deinen einzelnen Blöcken des Grids angezeigt werden soll. Wie oben aufgezeigt, kannst du die Blöcke entweder manuell oder dynamisch definieren.
### blockId
Die blockId kannst du nutzen, um deine Blöcke besser unterscheiden zu können. Das macht vor allem bei dem manuellen Grid Sinn. Die blockId wirkt sich aber auf keine anderen Parameter aus.
```javascript
blockId: "",
```
### width
*width* gibt die Breite deines Grid-Blocks an.
```javascript
width: "100%", // Prozent-Werte. Hier: volle Breite.
width: "fraction", // Mit Fraction ordnet sich das Element unter und nimmt nur der übrig gebliebenen Platz ein.
width: "100px", // Pixel-Werte
width: "" // default: 100%
```
### height
*height* gibt die Höhe des Grid-Blocks an.
```javascript
height: "auto", // Automatisch an den Inhalt angepasste Höhe.
height: "fraction", // Mit Fraction ordnet sich das Element unter und nimmt nur der übrig gebliebenen Platz ein.
height: "300px", // Pixel-Werte
height: "", // default: auto
```
### alignX
*alignX* gibt an, wie deine Inhalte auf der X-Achse angeordnet werden.
```javascript
alignX: "center", // zentriert // default: center
alignX: "left", // linksbündig
alignX: "right", // rechtsbündig
alignX: "between", // teilt blocks auf gesamtbreite auf
alignX: "", // default: left
```
### alignY
*alignY* gibt an, wie deine Inhalte auf der Y-Achse angeordnet werden.
```javascript
alignY: "center", // zentriert // default: center
alignY: "top", // oben angeordnet
alignY: "bottom", // unten angeordnet
alignY: "between", // teilt blocks auf gesamtbreite auf
alignY: "", // default: center
```
### paddingY
*paddingY gibt den Abstand zwischen dem Inhalt deines einzelnenBlocks und dem Rand jeweils links und rechts an. *
```javascript
paddingY: "20px", // Pixel-Werte
paddingY: "", // default: 0px
```
### paddingX
*paddingX gibt den Abstand zwischen dem Inhalt deines einzelnenBlocks und dem Rand jeweils links und rechts an. *
```javascript
paddingX: "20px", // Pixel-Werte
paddingX: "", // default: 0px
```
### backgroundColor
*backgroundColor gibt die Hintergrundfarbe deines einzelnen Blocks an. *
```javascript
backgroundColor: "#000", // HEX-Wert
backgroundColor: "", // default: Keine
```
### lineHeight
*lineHeight* gibt den Zeilenabstand in den Texten deines Blocks an.
```javascript
lineHeight: "normal", // Standardhöhe je nach Schriftgröße
lineHeight: "1.6", // Zahlenwerte getrennt durch Punkte
lineHeight: "10px", // Pixel-Werte
lineHeight: "", // default: normal
```
### styles
Bei ***styles*** kannst du dem Grid-Block eigene CSS styles hinzufügen.
```javascript
styles: "", // z.B. font-weight: 700;
```
### value
In deinem *value *definierst du nun, was in den einzelnen Blöcken angezeigt wird. Beispielsweise kannst du hier nun andere Widgets, wie die [Custom Card](/documentation/cards) einfügen. * *
```javascript
value: ""
```
## Aktionen
***clickAction*** beschreibt deine Aktionen in den jeweiligen Blocks.
```javascript
clickAction: {
recordId: Nr,
type: "update",
field: "",
value: "",
}
```
### Unterschiedliche Typen der Aktionen
***type*** sind die jeweiligen Funktionen der Aktion.
```javascript
// Folgende Actions benötigen die zwei Paramter: "recordId" und "type"
"popup"
"delete"
"openRecord"
"fullscreen"
// Folgender Actions benötigt die 4 Parmater: "recordId", "type", "field", "value"
"update"
// Folgende Actions benötigen nur den Parameter "type" in der clickAction.
"closeFullScreen"
"closeRecord"
"closeAllRecords"
```
---
# Custom Kanban
Source: https://www.arc-rider.com/docs/widgets/custom-kanban
# Kanban in React
Aufgaben oder Vorgänge als Karten in Statusspalten darstellen. Auswahl und gespeicherter Board-Zustand gehören deiner React-Anwendung.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import {
ArcWidgetBadge,
ArcWidgetIcon,
ArcWidgetKanban,
ArcWidgetLayout,
ArcWidgetText,
} from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const LANES = {
neu: {
id: 'neu',
title: t('Neu', 'New', 'Nuevo'),
borderColor: '#F59E0B',
},
offer: {
id: 'offer',
title: t('Angebot verschickt', 'Offer sent', 'Oferta enviada'),
borderColor: '#8B5CF6',
},
won: {
id: 'won',
title: t('Gewonnen', 'Won', 'Ganado'),
borderColor: '#22C55E',
},
lost: {
id: 'lost',
title: t('Verloren', 'Lost', 'Perdido'),
borderColor: '#E04F5F',
},
} as const;
type LaneId = keyof typeof LANES;
type Deal = {
id: string;
title: string;
company: string;
value: string;
chance: number;
overdue?: boolean;
};
const deal = (
id: string,
title: string,
company: string,
value: string,
chance: number,
overdue = false,
): Deal => ({ id, title, company, value, chance, overdue });
const demoDeals: Record = {
neu: [
deal(
'1',
t('Website-Relaunch', 'Website relaunch', 'Rediseño web'),
'Müller GmbH',
'18.400,00 €',
20,
true,
),
deal(
'2',
t('Erstgespräch', 'First call', 'Primera llamada'),
'Stahlwerk West',
'6.200,00 €',
10,
),
deal(
'7',
t('Shop-Anbindung', 'Shop integration', 'Integración tienda'),
'Nordlicht KG',
'9.600,00 €',
15,
),
deal(
'8',
t('App-Redesign', 'App redesign', 'Rediseño app'),
'Bauer AG',
'24.100,00 €',
25,
),
],
offer: [
deal(
'3',
t('CRM-Einführung', 'CRM rollout', 'Implantación CRM'),
'Globex Inc.',
'42.000,00 €',
60,
),
deal(
'4',
t('Servicevertrag', 'Service contract', 'Contrato servicio'),
'Acme Corp',
'12.800,00 €',
45,
),
deal(
'9',
t('Schulungspaket', 'Training package', 'Paquete formación'),
'Wayne Ent.',
'16.400,00 €',
55,
),
],
won: [
deal(
'5',
t('Lizenzpaket', 'Licence pack', 'Paquete licencias'),
'Umbrella Co.',
'96.500,00 €',
100,
),
deal(
'10',
t('Wartung 24/7', 'Maintenance 24/7', 'Mantenimiento 24/7'),
'Stark Ind.',
'54.000,00 €',
100,
),
deal(
'11',
t('Schnittstellen', 'Integration', 'Integración'),
'Soylent Ltd.',
'31.200,00 €',
100,
),
],
lost: [
deal(
'6',
t('Pilotprojekt', 'Pilot project', 'Proyecto piloto'),
'Initech',
'8.900,00 €',
0,
),
deal(
'12',
t('Workshop-Tag', 'Workshop day', 'Día de taller'),
'Pied Piper',
'4.800,00 €',
0,
),
],
};
const extraDeals: Record = {
neu: [
deal(
'13',
t('Newsletter-Relaunch', 'Newsletter relaunch', 'Rediseño newsletter'),
'Hooli',
'7.400,00 €',
18,
),
deal(
'14',
t('Messestand', 'Fair booth', 'Stand feria'),
'InGen',
'11.200,00 €',
22,
),
],
offer: [
deal(
'15',
t('Cloud-Migration', 'Cloud migration', 'Migración cloud'),
'Cyberdyne',
'38.000,00 €',
50,
),
deal(
'16',
t('Support-Plus', 'Support plus', 'Soporte plus'),
'Massive Dyn.',
'9.100,00 €',
40,
),
],
won: [
deal(
'17',
t('Jahreslizenz', 'Annual licence', 'Licencia anual'),
'Pied Piper',
'21.000,00 €',
100,
),
],
lost: [
deal(
'18',
t('PoC intern', 'Internal PoC', 'PoC interno'),
'Hooli',
'3.200,00 €',
0,
),
],
};
const busyDeals: Record = {
neu: [...demoDeals.neu, ...extraDeals.neu],
offer: [...demoDeals.offer, ...extraDeals.offer],
won: [...demoDeals.won, ...extraDeals.won],
lost: [...demoDeals.lost, ...extraDeals.lost],
};
const emptyDeals: Record = {
neu: [],
offer: [],
won: [],
lost: [],
};
const deals =
pack === 'empty' ? emptyDeals : pack === 'busy' ? busyDeals : demoDeals;
const itemView = (item: Deal, borderColor: string) => ({
id: item.id,
clickable: true,
draggable: true,
paddingX: '12px',
paddingY: '10px',
backgroundColor: '#ffffff',
borderPosition: 'left',
borderColor: item.overdue ? '#DC2626' : borderColor,
borderWidth: '3px',
title: (
{item.title}
),
subtitle: (
{item.company}
{item.value}
),
value: (
{item.chance}%
),
});
const startLanes = (Object.keys(LANES) as LaneId[]).map((id) => ({
...LANES[id],
items: deals[id],
}));
const PLUS_BLOCK = 4;
function LaneHeader({
title,
count,
dot,
onAdd,
}: {
title: string;
count: number;
dot: string;
onAdd: () => void;
}) {
return (
),
},
{
width: 'auto',
height: 'auto',
value: (
),
},
{
width: 'auto',
height: 'auto',
value: (
),
},
{ width: 'fraction', height: '1px', value: '' },
{
width: 'auto',
height: 'auto',
clickable: true,
value: (
),
},
],
}}
onBlockClick={(block_index) => {
if (block_index === PLUS_BLOCK) onAdd();
}}
/>
);
}
export default function Example() {
const [lanes, setLanes] = useState(startLanes);
const [selected, setSelected] = useState(
t(
'Karte ziehen oder anklicken',
'Drag or click a card',
'Arrastra o pulsa una tarjeta',
),
);
const addDeal = (laneId: LaneId) => {
setLanes((current) =>
current.map((lane) =>
lane.id === laneId
? {
...lane,
items: [
...lane.items,
deal(
`${laneId}-${lane.items.length + 1}-${Date.now()}`,
t('Neuer Deal', 'New deal', 'Nuevo trato'),
t('Ohne Kontakt', 'No contact', 'Sin contacto'),
'—',
laneId === 'won' ? 100 : laneId === 'lost' ? 0 : 15,
),
],
}
: lane,
),
);
setSelected(
`${t('Deal angelegt in', 'Deal added to', 'Trato añadido a')} ${LANES[laneId].title}`,
);
};
return (
<>
({
id: lane.id,
title: (
addDeal(lane.id)}
/>
),
minWidth: '300px',
fontColor: '#111827',
backgroundColorHeader: '#FFFFFF',
backgroundColorBody: '#F4F5F7',
showAmount: false,
empty: true,
items: lane.items.map((item) => itemView(item, lane.borderColor)),
})),
}}
onItemClick={(_event, { item_index }) =>
setSelected(`${t('Deal', 'Deal', 'Trato')} ${item_index + 1}`)
}
onItemDrop={async (payload) => {
const next = lanes.map((lane) => ({
...lane,
items: [...lane.items],
}));
const [item] = next[payload.source_swimlane_index].items.splice(
payload.item_index_in_section,
1,
);
next[payload.target_swimlane_index].items.splice(
payload.target_index_in_section,
0,
item,
);
setLanes(next);
setSelected(t('Karte verschoben', 'Card moved', 'Tarjeta movida'));
}}
/>
{selected}
);
}
```
## Features ausprobieren
### Gruppen, JSX-Karten und leere Spalten
Schalte die Gruppierung um und klicke auf eine Karte. Das ergänzende Drag-Beispiel darunter zeigt die Speicherung mit Fehlerbehandlung.
```tsx
import { useState } from 'react';
import { ArcWidgetKanban, ArcWidgetBadge } from '@arcrider/arcwidgets-react';
export default function Example() {
const [grouped, setGrouped] = useState(true);
const [selected, setSelected] = useState('Keine Auswahl');
const task = (id: string, title: string) => ({
id,
title,
subtitle: (
),
clickable: true,
draggable: false,
});
return (
<>
setSelected(
`Spalte ${p.swimlane_index + 1} · Gruppe ${p.section_index + 1} · Karte ${p.item_index_in_section + 1}`,
)
}
/>
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetKanbanData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onItemClick
Browser-Event und Position der Karte.
```typescript
onItemClick?: (event: Event, payload: ArcWidgetKanbanItemClickPayload) => void;
```
### onItemDrop
Neue Position einer verschobenen Karte. Ein zurückgegebenes Speicher-Promise hält den Vorgang bis zum Abschluss offen; Ablehnung setzt den Wechsel zurück.
```typescript
onItemDrop?: (payload: ArcWidgetKanbanItemDropPayload) => void | Promise;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### empty
Anzeige für leere Spalten; `true` oder eine eigene Beschriftung und Farben.
Typ: `boolean | string | ArcWidgetKanbanEmpty`.
### swimlanes
Spalten mit flachen `items` oder benannten `sections`.
Typ: `ArcWidgetKanbanSwimlane[]`.
### scrollSettings
Scrollverhalten des Inhaltsbereichs.
Typ und verschachtelte Felder stehen in `ArcWidgetKanbanData` unter Datentypen.
### showScrollbar
Sichtbarkeit des Scrollbalkens.
Typ: `boolean`.
### collapsible
Aufklappen bzw. Einklappen; das konkrete Format steht im Typ.
Typ: `boolean`.
## Verhalten und Grenzen
- Eine Spalte enthält entweder flache `items` oder benannte `sections` mit eigenen `items`. Gruppen brauchen eine stabile `id`.
- `onItemClick` liefert zuerst das Browser-Event, dann Indizes für Spalte, Gruppe und Karte. Diese Indizes beziehen sich auf die übergebene Datenstruktur.
- Aktiviere `draggable` nur mit einem passenden `onItemDrop`. Gib dessen Speicher-Promise zurück; ein abgelehntes Promise bricht den optimistischen Wechsel ab. Aktualisiere nach erfolgreichem Speichern deinen State.
- Die leere Spaltenanzeige aktivierst du mit `empty: true` oder einer eigenen Konfiguration.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetKanbanItemClickPayload {
swimlane_index: number;
section_index: number;
item_index: number;
item_index_in_section: number;
}
export interface ArcWidgetKanbanItemDropPayload {
source_swimlane_index: number;
target_swimlane_index: number;
item_index: number;
source_section_index: number;
target_section_index: number;
item_index_in_section: number;
target_index_in_section: number;
}
export interface ArcWidgetKanbanItem {
id?: string | number;
title?: ArcWidgetSlot;
subtitle?: ArcWidgetSlot;
value?: ArcWidgetSlot;
clickable?: boolean;
draggable?: boolean;
paddingX?: string;
paddingY?: string;
borderPosition?: string;
borderColor?: string;
borderWidth?: string;
}
export interface ArcWidgetKanbanSection {
id: string;
title?: ArcWidgetSlot;
items?: ArcWidgetKanbanItem[];
hideWhenEmpty?: boolean;
collapsed?: boolean;
[key: string]: unknown;
}
export interface ArcWidgetKanbanEmpty {
enabled?: boolean;
value?: ArcWidgetSlot;
backgroundColor?: string;
fontColor?: string;
fontWeight?: string | number;
}
export interface ArcWidgetKanbanSwimlane {
id?: string | number;
title?: ArcWidgetSlot;
minWidth?: string;
empty?: boolean | string | ArcWidgetKanbanEmpty;
items?: ArcWidgetKanbanItem[];
sections?: ArcWidgetKanbanSection[];
scrollY?: { scrollbar?: { enabled?: boolean }; [key: string]: unknown };
[key: string]: unknown;
}
export interface ArcWidgetKanbanData extends Omit {
height?: string;
empty?: boolean | string | ArcWidgetKanbanEmpty;
swimlanes?: ArcWidgetKanbanSwimlane[];
scrollSettings?: {
scrollX?: { scrollbar?: { enabled?: boolean }; [key: string]: unknown } | boolean;
scrollY?: { scrollbar?: { enabled?: boolean }; [key: string]: unknown } | boolean;
[key: string]: unknown;
};
showScrollbar?: boolean;
collapsible?: boolean;
}
export type ArcWidgetKanbanProps = ArcReactWidgetProps & {
onItemClick?: (event: Event, payload: ArcWidgetKanbanItemClickPayload) => void;
onItemDrop?: (payload: ArcWidgetKanbanItemDropPayload) => void | Promise;
};
```
## Einsatzbeispiele
- [Kanban speichern und Fehler behandeln](/docs/react/examples/react-kanban-persistenz)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Kanban
# Custom Kanban
## AI Defaults (read first)
- **uniqueId**: Required, `"kanban-" + Nr`.
- **height**: Use `"100%"` when embedded in a dashboard layout.
- **Swimlane minWidth**: Set `minWidth: "300px"` for readable swimlanes.
- **recordId**: Use raw `Nr` in swimlanes, NEVER `number(Nr)`. Stays on the formula; core never reads it. Drop handler looks up `ui.data.swimlanes[target_swimlane_index].recordId`.
- **fieldId**: Use `fieldId(Nr, "Feldname")`, NOT the display name as string. Drop persistence is Ninox-handler only — core does not read `fieldId`.
- **items mapping**: Use `.[{ itemId: Nr, ... }]` with `Nr` (not `number(Nr)`). `itemId` stays on the formula. Core emits swimlane/section/item **indices**; the handler reads `itemId` / `fieldId` from `ui.data.swimlanes[i]`.
- **sections** (optional pro Swimlane): `[{ id: "…", title: "…", items: [ … ], hideWhenEmpty: false, collapsed: false }]`. Ohne `sections` oder leer → flaches `items` wie bisher (eine implizite Gruppe, kein Gruppenkopf). `id` ist Pflicht sobald Gruppen genutzt werden (State).
- **scrollSettings**: Root: `scrollX` / `scrollY` mit `scrollbar: { enabled: boolean }` fuer das gesamte Kanban (ersetzt/ergaenzt `showScrollbar` fuer X). Pro Swimlane: `scrollY.scrollbar.enabled` fuer vertikales Scrollen in der Spalte.
- **dragAction**: Needs `fieldId` (field ID) for the status field being updated on drag. Adapter-only.
- **Persistence**: Card drag saves in the **Ninox handler** (`type: "update"` from `item.fieldId` + target swimlane `recordId`). React hosts: `onItemDrop` / `onAction('item_drop')` — **no** global `database` stub.
- **clickable**: Core gated nur darüber. Ninox: `clickAction: false` → nicht klickbar; sonst Default-Popup über `itemId`.
- **Filter values**: Extract filter variables BEFORE the `(select ...)` query, never inline.
- **Sections with different data**: Use `for section in sections do...end`, NOT a static array.
- **empty**: Off by default. Opt-in pill: `empty: { enabled: true, value: "Keine Einträge", backgroundColor: "#fff", fontColor: "#888", fontWeight: 400 }` on the board or a swimlane.
# Custom Kanban
Das Kanban stellt Daten einer Tabelle (Kanban Karten) in einem bestimmten Status (in den Swimlanes) dar. Dafür legst du wie gewöhnlich eine Variable ***data*** an, die du dann in der globalen Funktion ***arcCustomKanban*** ausgibst. Es gibt zwei Möglichkeiten ein Kanban anzulegen:
- **dynamisch** (Swimlanes beziehen sich auf eine Liste/Tabelle/for-Schleife)
- **manuell** (Swimlanes werden manuell definiert)
## Dynamischer Anwendungscode
```javascript
let current := this;
let listFirmen := (select Firmen);
let listStates := (select Status_Leads);
let data := {
uniqueId: "Kanban individuell",
height: "600px",
collapsible: true,
showScrollbar: true,
swimlanes: listStates.[{
title: Titel,
recordId: number(Nr),
backgroundColorHeader: text(color(Farbe)),
backgroundColorBody: "",
fontColor: "",
minWidth: "",
amount: let id := Nr;
cnt(listFirmen[number(Status) = number(id)]),
items: let id := Nr;
listFirmen[number(Status) = number(id)].[{
itemId: Nr,
fieldId: "D",
clickAction: false,
dragAction: true,
paddingX:",
paddingY: "",
borderPosition: "",
borderColor: "",
borderWidth: "",
title: Name,
subtitle: "Kunden-Nr.:" + Nr,
value: arcCustomProgressBar({
uniqueId: "progress" + Nr,
title: "",
width: "100%",
fontSize: "",
fontColor: "",
backgroundColor: "",
progressColor: "",
valueTotal: stateTotal,
valueProgress: stateCurrent,
valueText: stateCurrent + "/" + stateTotal
})
}]
}]
};
arcCustomKanban(data)
```
### Variablen einstellen
```javascript
let current := this; // Definiert diesen Record
let listFirmen := (select Firmen); // Definiert die Tabelle für die darzustellenden Inhalte
let listStates := (select Status_Leads); // Definiert die Liste für die Swimlanes
```
### Allgemeine Einstellungen in *data*
***uniqueId*** ist die individuelle Bezeichnung deines Kanbans. Achte darauf, dass du hier einen einzigartigen Titel vergibst. Das ist wichtig, falls du mehrere Kanbans auf einer Seite darstellen möchtest und deine Style-Einstellungen sich nicht überschreiben.
```javascript
uniqueId: "Kanban individuell",
```
***height*** defineirt die Höhe deines Kanbans.
```javascript
height: "600px", // Pixel-Werte
height: "auto", // Passt die Höhe an die Inhalte an.
height: "100%", // Passt sich der Höhe des Funktionsfeldes an.
height: "", // Fallback-Wert: 100%
```
Mit ***collapsible*** kannst du einstellen, dass der User die Swimlanes über einen Klick auf das Einklapp-Icon (caret-up) ein- oder aufklappen kann.
```javascript
collapsible: true, // Aktiviert die Funktion
collapsible: "", // Fallback-Wert = "false"
```
Mit ***showScrollbar*** kann die horizontale Scrollbar für das gesamte Kanban eingeblendet werden. Dies hilft vor allem Usern ohne Trackpad oder Tablet.
```javascript
showScrollbar: true, // Scrollbar wird eingeblendet
showScrollbar: false, // keine Anzeige der Scrollbar
showScrollbar: "", // default: false
```
### Swimlane Einstellungen in *data*
Der Parameter swimlane definiert die Darstellung deiner einzelnen Spalten deines Kanbans. Diese werden innerhalb der eckigen und geschwungenen Klammer definiert.
```javascript
swimlanes: listStates.[{
}]
```
***title*** definiert den Titel deiner jeweiligen Swimlane. Dieser kann in diesem Beispiel der Titel aus der Tabelle listStates sein - ist also dynamisch.
```javascript
title: Titel, // Ninox-Feld im Textformat.
title: "Hans" // Text in ", wenn das Kanban manuell angelegt ist
title: "" // Kein Fallback hinterlegt.
```
***recordId*** definiert den Datensatz aus der dynamischen Liste, die du vorher definiert hast. Hier: listStates.
```javascript
recordId: number(Nr), // Nr des jeweiligen Records aus der Liste
```
***backgroundColorHeader*** definiert die Hintergrund-Farbe der Kopfzeile jeder Swimlane.
```javascript
backgroundColorHeader: text(color(Farbe)), // Ninox Feld , das Farbe referenziert (HEX Wert ausgibt)
backgroundColorHeader: "#000", // HEX Wert in "
backgroundColorHeader: " ,// Fallback-Wert: #8594c1
```
***backgroundColorBody ***definiert die Hintergrund-Farbe Swimlane-Körpers (Body).
```javascript
backgroundColorBody: text(color(Farbe)), // Ninox Feld , das Farbe referenziert (HEX Wert ausgibt)
backgroundColorBody: "#000", // HEX Wert in "
backgroundColorBody: "", // Fallback-Wert: #f4f7ff
```
***fontColor*** definiert die Schriftfarbe für den Header.
```javascript
fontColor: "#000", // Hex-Wert in "
fontColor: "", // Fallback-Wert: #fff
```
***minWidth*** gibt die minimale Breite der Swimlanes an. Das verhindert, dass die Swimlanes bei kleineren Bildschirmen immer kleiner gedrückt werden. Somit werden deine Inhalte immer gut lesbar dargestellt, da dann nach rechts gescrollt werden kann.
```javascript
minWidth: "300px", // Pixel-Wert in "
minWidth: "", // Fallback-Wert: 150px
```
***empty*** blendet in leeren Spalten eine Pill ein. **Default: aus.** Am Board für alle Spalten, oder pro Swimlane (überschreibt das Board). `true` / `"true"` ist der alte Kurz-Schalter.
```javascript
empty: {
enabled: true,
value: "Keine Einträge",
backgroundColor: "#fff",
fontColor: "#888888",
fontWeight: 400
}
empty: true
empty: "" // Default: keine Pill
```
***amount*** definiert, welche Anzahl in dem Swimlane Header angezeigt wird. Zahl, HTML-String oder verschachteltes Widget — wie `title`. Leer / weggelassen blendet die Bubble aus. Eine **Zahl** aktualisiert sich sofort beim Verschieben einer Karte. **HTML oder ein Widget** bleibt unverändert (kein automatischer Zähler) und kommt erst mit dem nächsten Ninox-Reload neu.
```javascript
amount: let id := Nr; cnt(list[number(Status) = number(id)]),
amount: "" + cnt(list[number(Status) = number(id)]) + "",
amount: "" // Kein Fallback-Wert. Die Amount-Bubble wird in diesem Fall ausgeblendet.
```
### Item Einstellungen (Cards) innerhalb von *swimlanes*
Der Parameter items definiert die Darstellung deiner Karten innerhalb der Swimlane. Diese werden innerhalb der eckigen und geschwungenen Klammer definiert.
```javascript
items: let id := Nr;
listFirmen[number(Status) = number(id)].[{
}]
```
***itemId*** definiert den Record der item-Liste. hier: listFirmen.
```javascript
itemId: Nr, // Record-Id
```
***fieldId*** definiert das Feld, das geändert werden soll, beim Wechsel der Swimlane. In den meisten Fällen ist das der Status.
```javascript
fieldId: "D", // Field ID findest du mit dem arcFieldFinder heraus
```
***clickAction*** steuert den Klick auf die Karte. Legacy-kompatibel:
- `false` → kein Klick
- `true` / weglassen / `""` → öffnet den Record per `popupRecord` (`itemId`)
- Objekt (oder Array) → eine Action wie bei Calendar/Layout (z. B. `{ type: "popup", recordId: Nr }`)
```javascript
clickAction: false, // Deaktiviert die Klick-Aktion
clickAction: true, // Fallback: popupRecord(itemId)
clickAction: {
type: "popup",
recordId: Nr
},
clickAction: {
type: "update",
recordId: helperRecordId,
fieldId: "A",
value: Nr
},
```
***actions*** (Array) — bevorzugter Weg für mehrere Aktionen beim Klick. Hat Vorrang vor `clickAction` (außer `clickAction: false`). Gleiche Action-Typen wie Calendar/Layout (`popup`, `update`, `openRecord`, `create`, …).
```javascript
actions: [{
type: "popup",
recordId: Nr
}, {
type: "update",
recordId: helperRecordId,
fieldId: "A",
value: Nr
}],
```
***dragAction*** definiert, ob der User die Karte per Drag and Drop verschieben kann.
```javascript
dragAction: false, // Deaktiviert die Drag & Drop Funktion.
dragAction: "", // Fallback-Wert: true
```
***paddingX*** definiert den Abstand von der Border zum Inhalt rechts und links innerhalb der Karte.
```javascript
paddingX: "10px" // Pixel-Wert in "
paddingX:", // Fallback-Wert: 12px
```
***paddingY*** definiert den Abstand von der Border zum Inhalt oben und unten innerhalb der Karte.
```javascript
paddingY: "10px" // Pixel-Wert in "
paddingY: "", // Fallback-Wert: 12px
```
***borderPosition*** definiert ob du in der Karte eine einseitige border darstellen möchtest. Diese könnte durch de Farbe ein weiteres Attribut / Kategorie deiner Inhalte darstellen (Zum Beispiel Aktiv / Inaktiv)
```javascript
borderPosition: "left", // Border auf der linken Seite
borderPosition: "right", // Border auf der rechten Seite
borderPosition: "top", // Border auf der oberen Seite
borderPosition: "bottom", // Border auf der unteren Seite
borderPosition: "", // Fallback-Wert: keine border
```
***borderColor*** definiert die Farbe deiner Border.
```javascript
borderColor: if aktiv=true then "#c5f2b3" else "#ccc"// HEX-Wert in "
borderColor: "", // Fallback-Wert:
```
```javascript
borderWidth: "1px", // Pixel-Wert in "
borderWidth: "", // Fallback-Wert:
```
***title*** gibt den Obersten Titel in der Karte aus und ist fett gedruckt.
```javascript
title: Name, // Ninox-feld in Text-Format
title: "" // Kein Fallback
```
```javascript
subtitle: "Kunden-Nr.:" + Nr, // Text und/oder Ninox Felder in Textformat
subtitle: arcCustomLayout({ uniqueId: "sub-" + Nr, embedded: true, ... }), // gleiches Slot wie value
subtitle: "", // Kein Fallback
```
Mit ***value*** kannst du deine Karte so individuell gestalten, wie du möchtest. Hier kannst du mit Schrift arbeiten oder auch jedes andere Widget integrieren. Zum Beispiel kannst du mit [arcCustomLayout](/documentation/custom-layout) komplexere Karten aufsetzen oder einfach eine Progressbar mit [arcCustomProgressBar](/documentation/progress-bar) einsetzen.
```javascript
value: "Hier steht Text" // Texte oder Werte aus Ninox-Feldern
value: arcCustomProgressBar({
uniqueId: "progress" + Nr,
title: "",
width: "100%",
fontSize: "",
fontColor: "",
backgroundColor: "",
progressColor: "",
valueTotal: stateTotal,
valueProgress: stateCurrent,
valueText: stateCurrent + "/" + stateTotal
}) // Andere Widgets
value: "", // Kein Fallback
```
---
# Custom KPI Bar
Source: https://www.arc-rider.com/docs/widgets/custom-kpi-bar
# KpiBar in React
Mehrere Kennzahlen mit Beschriftung und optionaler Klickaktion nebeneinander anzeigen.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetKpiBar } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const demoMetrics = [
{
title: t('Offene Aufträge', 'Open orders', 'Pedidos abiertos'),
value: 12,
color: '#d97706',
},
{
title: t('In Arbeit', 'In progress', 'En curso'),
value: 7,
color: '#0f766e',
},
{
title: t('Abgeschlossen', 'Completed', 'Completados'),
value: 38,
color: '#15803d',
},
];
const busyMetrics = [
...demoMetrics,
{ title: t('Wartet', 'Waiting', 'En espera'), value: 4, color: '#be123c' },
{
title: t('Heute fällig', 'Due today', 'Vence hoy'),
value: 3,
color: '#7c3aed',
},
];
const metrics =
pack === 'empty' ? [] : pack === 'busy' ? busyMetrics : demoMetrics;
export default function Example() {
const [selected, setSelected] = useState(t('Alle', 'All', 'Todos'));
return (
<>
({
card: index + 1,
title: metric.title,
value: metric.value,
clickable: true,
settings: {
colorValue: metric.color,
borderColor: metric.color,
},
})),
}}
onClick={(_event, index) =>
setSelected(metrics[index]?.title ?? selected)
}
/>
);
}
```
## Features ausprobieren
### Abgeleitete Kennzahlen und Klick-Filter
Die Kennzahlen werden gemeinsam aus einem State berechnet. Klicke auf eine Karte, um ihren Index im Callback zu prüfen.
```tsx
import { useState } from 'react';
import { ArcWidgetKpiBar } from '@arcrider/arcwidgets-react';
export default function Example() {
const [completed, setCompleted] = useState(7);
const [selected, setSelected] = useState('Keine');
const cards = [
{ title: 'Gesamt', value: 12 },
{ title: 'Erledigt', value: completed },
{ title: 'Offen', value: 12 - completed },
];
return (
<>
({ ...c, card: i + 1, clickable: true })),
}}
onClick={(_event, index) => setSelected(cards[index].title)}
/>
Ausgewählte Kennzahl: {selected}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetKpiBarData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onClick
Meldet den Klick. Beachte die widgetspezifischen Argumente unten.
```typescript
onClick?: (event: unknown, cardIndex: number) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### settings
Gemeinsame Darstellung der Einträge.
Typ: `ArcWidgetKpiBarSettings`.
### cards
Kennzahlenkarten mit Beschriftung, Wert und optionaler Klickbarkeit.
Typ: `ArcWidgetKpiBarCard[]`.
## Verhalten und Grenzen
- `cards` enthält Werte und Beschriftungen, `settings` die gemeinsame Darstellung.
- Aktiviere `clickable` pro Karte. `onClick(event, cardIndex)` kann einen Filter ändern oder in deiner Anwendung navigieren.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetKpiBarSettings {
height?: string;
colorLabel?: string;
fontSizeLabel?: string;
colorValue?: string;
fontSizeValue?: string;
backgroundColor?: string;
borderColor?: string;
[key: string]: unknown;
}
export interface ArcWidgetKpiBarCard {
card: number;
title?: ArcWidgetSlot;
value?: ArcWidgetSlot;
subtitle?: ArcWidgetSlot;
settings?: ArcWidgetKpiBarSettings;
clickable?: boolean;
}
export interface ArcWidgetKpiBarData extends Omit {
settings?: ArcWidgetKpiBarSettings;
cards?: ArcWidgetKpiBarCard[];
}
export interface ArcWidgetKpiBarProps extends ArcReactWidgetProps {
onClick?: (event: unknown, cardIndex: number) => void;
}
```
## Einsatzbeispiele
- [Dashboard mit CSS Grid](/docs/react/examples/dashboardansicht-mit-grid)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom KPI Bar
## AI Defaults (read first)
- **Function name**: `arcKPIBar` (NOT `arcCustomKpiBar`).
- **uniqueId**: Required, `"kpi-" + Nr`.
- **cards**: Array of `{ card: 1, title: "...", value: ... }` – `card` is eine Nummer (1, 2, 3…).
- **Klick (Ninox):** `actions: [...]` auf der Karte — der Adapter setzt intern `clickable: true`. Unterstützte Action-Typen wie bei arcCustomButton.
- **Klick (React):** `clickable: true` auf der Karte; `onClick(event, cardIndex)` am Host (`cardIndex` = 0-basierter Index in `cards`) — **kein** `actions` in `data`.
- **Large numbers**: Use `shortNumbers(value)` for auto-formatting (1.2K, 3.5M).
- **height**: Set in `settings: { height: "250px" }`.
- **Null handling**: Do NOT guard values with `else "" end`, omit the else.
# Custom KPI Bar
Die Custom KPI Bar besteht aus einem Anwendungscode, den du in einem Ninox Formel-Feld auf deiner Wunschoberfläche in der Datenbank einfügst. Dieser besteht aus einem allgemeinen Part (settings), in dem du Grundeinstellungen vornimmst und einem Detail-Bereich (cards), in dem du individuell bestimmst, welche Werte, Farben oder Aktionen du anwendest.
## Gesamter Anwendungscode
Hier siehst du einen beispielhaften Anwendungscode, der deine KPI-Bar definiert. Mit *data* definierst du die Inhalte, die du dann mit der Funktion *arcKPIBar()* ausgeben lässt.
```javascript
let data := {
uniqueId: "KPI Bar 2",
settings: {
height: "",
colorLabel: "",
fontSizeLabel: "15",
colorValue: "",
fontSizeValue: "40px",
backgroundColor: "",
borderColor: ""
},
cards: [{
card: 1,
settings: {
colorLabel: "#8e99c4",
fontSizeLabel: "15",
colorValue: "#8e99c4",
fontSizeValue: "40px",
backgroundColor: "#49547e",
borderColor: "#646f9b"
},
title: "Gesamtumsatz",
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
subtitle: "€" +
shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}]
};
arcKPIBar(data)
```
## Allgemeine Settings
In den allgemeinen Settings nimmst du die Grundeinstellungen deiner KPI Karte vor. Diese **wirkt sich auf alle Karten aus**. Folgend werden dir die einzelnen Parameter erläutert:
*uniqueId* vergibt einen eigenen Namen für deine KPI Bar. Es ist wichtig, dass diese Bezeichnung einzigartig ist. Hast du beispielsweise mehrere KPI-Bars auf einem Datensatz und gibst keinen einzigartigen Namen an, dann überschreiben sich die Werte gegenseitig. Versuche also möglichst individuell zu Bezeichnen.
```javascript
uniqueId: "KPI Bar 1",
```
*height* bestimmt die Höhe deiner KPI Bar. Hier kannst du folgende Werte angeben:
```javascript
height: "250px" // Pixel Werte
```
*colorLabel *gibt die Farbe der Schrift an. Hier kannst du folgende Werte angeben:
```javascript
colorLabel: "FFFFFF" // HEX Code für deinen Farbwert.
```
*fontSizeLabel* bestimmt die Größe deiner Schrift über und unter dem KPI-Wert. Diese gibst du mit folgenden Werten an:
```javascript
fontSizeLabel: "12px" // Pixel Werte
```
*colorValue *gibt die Farbe deines KPI Wertes an. Hier kannst du folgende Werte angeben:
```javascript
colorValue: "FFFFFF" // HEX Code für deinen Farbwert.
```
*fontSizeValue* bestimmt die Größe deines KPI-Wertes. Diese gibst du mit folgenden Werten an:
```javascript
fontSizeValue: "35px" // Pixel Werte
```
*backgroundColor* bestimmt die Farbe des Hintergrundes deiner Karte. Hier kannst du folgende Werte angeben:
```javascript
backgroundColor: "FFFFFF" // HEX Code für deinen Farbwert.
```
*borderColor* bestimmt die Farbe der Umrandung der Karte. Hier kannst du folgende Werte angeben:
```javascript
borderColor: "FFFFFF" // HEX Code für deinen Farbwert.
```
## Standard-Werte als Fallback
💡 **Hinweis: **Alle Werte der Parameter werden in Anführungszeichen angegeben. Trägst du nichts in die Anführungszeichen ein, so greift das System auf ein Fallback zurück. Das heißt es gibt voreingestellte Standard-Werte, sodass immer etwas ausgegeben wird. Hier siehst du die Karte mit den Fallback-Werten:
## Detail-Bereich
Im Detail-Bereich definierst du alle Styles und Werte der einzelnen KPI-Karten. Das heißt: Jede Karte kann individuell gestaltet werden. Die Styles überschreiben in dem Fall die Werte aus den Allgemeinen Settings. Folgend siehst du einen Code für eine beispielhafte KPI Card.
```javascript
{card: 1,
settings: {
colorLabel: "#F9244B",
fontSizeLabel: "15",
colorValue: "#F9244B",
fontSizeValue: "40px",
backgroundColor: "#FCD9DF",
borderColor: "#EABDC5"
},
title: "Gesamtumsatz",
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
subtitle: "€" + shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}
```
*card* ist die individuelle Nummer deiner Karte und sorgt für Übersichtlichkeit und Datenstruktur. Diese gibst du wie folgt an:
```javascript
card: 1 // Nummer deiner Karte als reine Zahl
```
*settings* sind die gleichen Einstellungswerte, wie in den allgemeinen Settings. Diese kannst du hier je Karte überschreiben und individuell gestalten.
```javascript
settings: {
colorLabel: "#F9244B",
fontSizeLabel: "15",
colorValue: "#F9244B",
fontSizeValue: "40px",
backgroundColor: "#FCD9DF",
borderColor: "#EABDC5"
}
```
*title* ist die Überschrift über deinem KPI-Wert.
```javascript
title: "Gesamtumsatz" // Reiner, statischer Text als Überschrift
title: if Status=abgeschlossen then "Gesamtumsatz" else "Erwarteter Umsatz" // Du kannst alle normalen Ninox Funktionen verwenden, um dir deinen Titel ausgeben zu lassen.
```
*value* gibt deinen Wert der KPI Karte aus.
```javascript
value: "5.000.000€" // Reiner, statischer Text als Wert
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)) // Greife auf Ninox Felder zurück und arbeite mit üblichen Ninox Funktionen / -Schreibweisen.
```
*subtitle* gibt den Untertitel unter deinem KPI Wert an.
```javascript
subtitle: "in diesem Monat" // Reiner, statischer Text als Unterschrift
subtitle: "€" +
shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat" // Greife auf Ninox Felder zurück und arbeite mit üblichen Ninox Funktionen / -Schreibweisen.
```
*actions* (nur Ninox) definiert Aktionen, die beim Klick auf die KPI-Karte ausgeführt werden. Der Adapter setzt daraus `clickable: true` für das Widget-Core — die Karte wird klickbar (Cursor: pointer, Hover-Effekt). Unterstützte Action-Typen: `update`, `popup`, `openRecord`, `fullscreen`, `openUrl`, `create`, `delete` (analog zu arcCustomButton).
*clickable* (React / andere Hosts) markiert die Karte als klickbar. Setze `clickable: true` in `data` und reagiere im Host auf `onClick(event, cardIndex)` — `cardIndex` ist der **0-basierte** Index in `cards`. In React **kein** `actions` in `data` verwenden.
```javascript
actions: [{
type: "update",
recordId: Nr,
field: fieldId(Nr, "helper_activeTab"),
value: "umsatz"
}]
actions: [{ type: "popup", recordId: Nr }]
```
## Vervielfältigung deiner KPI Karten
Du kannst selbst bestimmen, wie viele KPI Karten du dir anzeigen lassen möchtest. Per Copy Paste kannst du deine Karten einfach in dem Code vervielfältigen. Trenne die einzelnen Cards durch ein Komma (,).
cards: [{
card: 1,
title: "Gesamtumsatz",
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
subtitle: "€" +
shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 2,
title: "Abgeschlossen gesamt",
value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 3,
title: "Conversion Rate",
value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
"%",
subtitle: round(cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
cnt(select Projekte where month(Abgeschlossen) = month(today())) *
100, 2) + "%" + " in diesem Monat"
}]
## Parameter
In dem Detail-Bereich deiner KPI-Karten kannst du verschiedenste Parameter definieren. Dabei kannst du selbst entscheiden, welche Parameter du definieren möchtest. Lässt du Parameter einfach weg, werden diese nicht ausgegeben. Hier siehst du alle Parameter, die du bei der KPI Bar verwenden kannst:
```javascript
card: "",
settings: {
colorLabel: "",
fontSizeLabel: "",
colorValue: "",
fontSizeValue: "",
backgroundColor: "",
borderColor: ""
},
title: "",
value: "",
subtitle: "",
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "Feld"), value: "..." }]
```
## Funktionen
Du kannst deine Parameter mit allen Ninox Funktionen & Schreibweisen definieren. Wir haben dir aber auch einige nützliche arcRider Funktionen erstellt, die dir deine Werte noch übersichtlicher machen.
*shortNumbers() *kürzt lange Zahlen ab 4 Stellen ab und setzt den Zahlennamen (Tsd.,Mio.,Mrd.,Bill.) dahinter.
```javascript
shortNumbers("2000") // Gibt den abgekürzten Wert der statischen Zahl aus (2 Tsd.)
shortNumbers(cnt((select Projekte).Umsatz)) // Gibt den abgekürzten Wert der dynamischen Zahl aus (z.B. 35 Mio.)
```
## Beispiele
Folgend findest du einige Praxisbeispiele, die dir den unterschiedlichen Einsatz der KPI Bar veranschaulichen.
### KPI Card Fallback
```javascript
let data := {
uniqueId: "KPI Bar 1",
settings: {
height: "",
colorLabel: "",
fontSizeLabel: "15",
colorValue: "",
fontSizeValue: "40px",
backgroundColor: "",
borderColor: ""
},
cards: [{
card: 1,
title: "Gesamtumsatz",
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
subtitle: "€" +
shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 2,
title: "Abgeschlossen gesamt",
value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 3,
title: "Conversion Rate",
value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
"%",
subtitle: round(cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
cnt(select Projekte where month(Abgeschlossen) = month(today())) *
100, 2) +
"%" +
" in diesem Monat"
}]
};
arcKPIBar(data)
```
### KPI Bar individuell
```javascript
let data := {
uniqueId: "KPI Bar 2",
settings: {
height: "",
colorLabel: "",
fontSizeLabel: "15",
colorValue: "",
fontSizeValue: "40px",
backgroundColor: "",
borderColor: ""
},
cards: [{
card: 1,
settings: {
colorLabel: "#F9244B",
fontSizeLabel: "15",
colorValue: "#F9244B",
fontSizeValue: "40px",
backgroundColor: "#FCD9DF",
borderColor: "#EABDC5"
},
title: "Gesamtumsatz",
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
subtitle: "€" +
shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 2,
settings: {
colorLabel: "#000",
fontSizeLabel: "15",
colorValue: "#1f96bf",
fontSizeValue: "40px",
backgroundColor: "#FDE8A5",
borderColor: "#D9C78C"
},
title: "Abgeschlossen gesamt",
value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 3,
settings: {
colorLabel: "#CAECCD",
fontSizeLabel: "15",
colorValue: "#CAECCD",
fontSizeValue: "40px",
backgroundColor: "#56C275",
borderColor: "#9DCDA1"
},
title: "Conversion Rate",
value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
"%",
subtitle: cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
cnt(select Projekte where month(Abgeschlossen) = month(today())) *
100 +
"%" +
" in diesem Monat"
}]
};
arcKPIBar(data)
```
### KPI Bar Darkmode
```javascript
let data := {
uniqueId: "KPI Bar 3",
settings: {
height: "",
colorLabel: "",
fontSizeLabel: "15",
colorValue: "",
fontSizeValue: "40px",
backgroundColor: "",
borderColor: ""
},
cards: [{
card: 1,
settings: {
colorLabel: "#8e99c4",
fontSizeLabel: "15",
colorValue: "#8e99c4",
fontSizeValue: "40px",
backgroundColor: "#49547e",
borderColor: "#646f9b"
},
title: "Gesamtumsatz",
value: "€" + shortNumbers(cnt((select Projekte).Umsatz)),
subtitle: "€" +
shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 2,
settings: {
colorLabel: "#8e99c4",
fontSizeLabel: "15",
colorValue: "#8e99c4",
fontSizeValue: "40px",
backgroundColor: "#49547e",
borderColor: "#646f9b"
},
title: "Abgeschlossen gesamt",
value: shortNumbers(cnt(select Projekte where Abgeschlossen != null)),
subtitle: shortNumbers(cnt((select Projekte where month(Abgeschlossen) = month(today())).Umsatz)) +
" in diesem Monat"
}, {
card: 3,
settings: {
colorLabel: "#8e99c4",
fontSizeLabel: "15",
colorValue: "#8e99c4",
fontSizeValue: "40px",
backgroundColor: "#49547e",
borderColor: "#646f9b"
},
title: "Conversion Rate",
value: round(cnt(select Projekte where Abgeschlossen != null) / cnt(select Projekte) * 100, 2) +
"%",
subtitle: cnt(select Projekte where Abgeschlossen != null and month(Abgeschlossen) = month(today())) /
cnt(select Projekte where month(Abgeschlossen) = month(today())) *
100 +
"%" +
" in diesem Monat"
}]
};
arcKPIBar(data)
```
**Weiterführende Links: **
[> NX Custom KPI Bar ](https://www.arc-rider.de/custom-kpi-bar)
---
# Custom Layout
Source: https://www.arc-rider.com/docs/widgets/custom-layout
# Layout in React
Widgets horizontal oder vertikal anordnen. Für responsive Raster kannst du das Layout mit CSS Grid oder Flexbox deiner Anwendung kombinieren.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import {
ArcWidgetBadge,
ArcWidgetButton,
ArcWidgetLayout,
ArcWidgetText,
} from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [count, setCount] = useState(pack === 'busy' ? 12 : 0);
const badges =
pack === 'empty'
? []
: [
{ value: t('Offen', 'Open', 'Abierto'), color: '#d97706' },
{ value: t('Live', 'Live', 'En vivo'), color: '#15803d' },
...(pack === 'busy'
? [
{
value: t('Priorität', 'Priority', 'Prioridad'),
color: '#be123c',
},
{ value: t('Messe', 'Fair', 'Feria'), color: '#7c3aed' },
]
: []),
];
return (
),
},
...(badges.length
? [
{
height: 'auto' as const,
value: (
({
width: 'auto',
height: 'auto',
value: (
),
})),
}}
/>
),
},
]
: []),
{
height: 'fraction',
value: (
setCount((value) => value + 1)}
/>
),
},
],
}}
/>
);
}
```
## Features ausprobieren
### Richtung, Abstände und verschachtelte Callbacks
Wechsle die Anordnung, ohne den Anwendungs-State zurückzusetzen. Der verschachtelte Button aktualisiert das Badge im anderen Block.
```tsx
import { useState } from 'react';
import {
ArcWidgetLayout,
ArcWidgetButton,
ArcWidgetBadge,
} from '@arcrider/arcwidgets-react';
export default function Example() {
const [horizontal, setHorizontal] = useState(true);
const [gap, setGap] = useState(12);
const [count, setCount] = useState(0);
return (
<>
),
},
{
width: 'fraction',
height: 'fraction',
value: (
setCount((c) => c + 1)}
/>
),
},
],
}}
/>
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetLayoutData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onClick
Meldet den Klick. Beachte die widgetspezifischen Argumente unten.
```typescript
onClick?: () => void;
```
### onBlockClick
Nullbasierter Index in `data.blocks`.
```typescript
onBlockClick?: (block_index: number) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### embedded
Passt das Widget in einen umgebenden Inhaltsbereich ein.
Typ: `boolean`.
### direction
Anordnung horizontal oder vertikal.
Typ: `'horizontal' | 'vertical' | string`.
### alignX
Horizontale Ausrichtung.
Typ: `'left' | 'center' | 'right' | string`.
### alignY
Vertikale Ausrichtung.
Typ: `'top' | 'center' | 'bottom' | string`.
### width
Breite des Widgets als Größenangabe.
Typ: `string`.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### gap
Abstand zwischen den Inhalten.
Typ: `string`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### paddingX
Innerer Abstand links und rechts.
Typ: `string`.
### paddingY
Innerer Abstand oben und unten.
Typ: `string`.
### scrollSettings
Scrollverhalten des Inhaltsbereichs.
Typ: `ArcWidgetLayoutScrollSettings`.
### clickable
Aktiviert den Klick-Callback des Widgets.
Typ: `boolean`.
### blocks
Layoutbereiche mit Größe, Ausrichtung und Inhalt in `value`.
Typ: `ArcWidgetLayoutBlock[]`.
## Verhalten und Grenzen
- Setze `direction` ausdrücklich. `fraction` verteilt verbleibenden Platz auf der jeweiligen Achse; eine Höhe von `100%` benötigt einen begrenzten Elterncontainer.
- `blocks[].value` unterstützt JSX. Binde Events verschachtelter Komponenten direkt an deren Callback-Props.
- Für Layout- oder Blockklicks muss am betreffenden Objekt `clickable: true` gesetzt sein. `onBlockClick` erhält den Index in `blocks`.
- Für Vollbild und Seitenlayout verwende den Container deiner React-App. Die historischen Felder `fullscreen`, `fullscreenMode`, `page` und `showAdminTools` sind keine React-Routing-API.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetLayoutBlock {
width?: string;
height?: string;
lineHeight?: string;
alignX?: 'left' | 'center' | 'right' | string;
alignY?: 'top' | 'center' | 'bottom' | string;
color?: string;
styles?: ArcWidgetStyles | string;
value?: ArcWidgetSlot;
clickable?: boolean;
[key: string]: unknown;
}
export interface ArcWidgetLayoutScrollSettings {
scrollY?: boolean;
scrollX?: boolean;
[key: string]: unknown;
}
export interface ArcWidgetLayoutData extends Omit {
embedded?: boolean;
direction?: 'horizontal' | 'vertical' | string;
alignX?: 'left' | 'center' | 'right' | string;
alignY?: 'top' | 'center' | 'bottom' | string;
width?: string;
height?: string;
gap?: string;
backgroundColor?: string;
paddingX?: string;
paddingY?: string;
fullscreen?: boolean;
fullscreenMode?: string;
page?: boolean;
showAdminTools?: boolean;
scrollSettings?: ArcWidgetLayoutScrollSettings;
clickable?: boolean;
blocks?: ArcWidgetLayoutBlock[];
}
export interface ArcWidgetLayoutProps extends ArcReactWidgetProps {
onClick?: () => void;
onBlockClick?: (block_index: number) => void;
}
```
## Einsatzbeispiele
- [Dashboard mit CSS Grid](/docs/react/examples/dashboardansicht-mit-grid)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Layout
## AI Defaults (read first)
- **Dashboard wrappers**: MUST have `fullscreen: true`, `fullscreenMode: if isAdminMode() then "" else "full" end`, `height: "100%"`.
- **embedded**: `false` for standalone/dashboard layouts, `true` when nested inside another widget.
- **direction**: Always set explicitly (`"horizontal"` or `"vertical"`).
- **Block widths**: At least one block should use `width: "fraction"` to fill remaining space.
- **Scrollable areas**: Use `height: "fraction"` + `scrollSettings: { scrollY: true }` for content below fixed headers.
- **uniqueId**: Required, no special characters.
- **Sticky headers**: Need `overflow-x: hidden` on parent (NOT `overflow: hidden`), background-color, and z-index.
- **Two for-loops**: NEVER place two for-loops side by side in blocks – each needs its own wrapper layout.
- **Nested widgets (Next-Gen)**: In `blocks[].value`, use `{ widget: "arc-widget-…", uid: "…", data: { … } }` — not `arcCustomXxx({ … })`. Requires current `bundle.js`; legacy Ninox-formula widgets do not support this. See `docs/patterns/nested-widget-descriptors.md`.
# Custom Layout
Mit dem Layout-Widget gestaltest du Oberflächen ohne Tabellenraster — flexibler Container (wie Flexbox): Ausrichtung, Abstände, Farben, verschachtelte Widgets.
In Ninox heißt der Einstieg `arcCustomLayout({ ... })` im Formelfeld.
Ob du einfache Abschnitte nebeneinander anordnen willst, eine Info-Card mit grafischem Hintergrund bauen möchtest oder interaktive Elemente auf einer Seite strukturieren willst – `arcCustomLayout` ist dein Werkzeug dafür.
**Dabei steuerst du:**
- Ausrichtung (horizontal / vertikal)
- Abstände, Farben, Hintergrundbilder
- Flexibles Verhalten bei Bildschirmgrößen
- Individuelle Stile je Block
- Interaktionen (z. B. Klickaktionen auf Bereiche)
Im Gegensatz zum `arcCustomGrid`, das für zweidimensionale Strukturen (Zeilen *und* Spalten) gedacht ist, arbeitet das Layout bewusst **eindimensional**: Du bestimmst, ob die Inhalte **horizontal (nebeneinander)** oder **vertikal (untereinander)** dargestellt werden – inklusive Ausrichtung, Abstände, Farben und responsiven Anpassungen.
**🎯 Was du damit machen kannst:**
- **Karten-ähnliche Layouts** mit Titel, Beschreibung und Buttons nebeneinander
- **Hero-Bereiche** mit großem Textblock + Bild nebeneinander (horizontal)
- **Vertikale Formblöcke** mit gezieltem Abstand und Hintergrundfarbe
- **Interaktive Blöcke** mit Klickfunktionen (Popup, Update, Löschen, etc.)
- **Kombination mehrerer Datenquellen** in einem dynamischen Layout
## Anwendungscode
### Schneller Einstieg – Simple Basis Layout
Ein kompaktes Beispiel, mit dem du direkt starten kannst. Ideal, wenn du ein paar Inhalte nebeneinander (`direction: "horizontal"`) oder untereinander (`direction: "vertical"`) anordnen willst – zum Beispiel Textbausteine, KPIs oder Buttons. Die wichtigsten Parameter wie Ausrichtung, Breite und Abstand sind bereits gesetzt und lassen sich leicht anpassen.
✅ Schnell einsetzbar
✅ Flexibel anpassbar
✅ Perfekt zum Kopieren und Loslegen
```javascript
arcCustomLayout({
uniqueId: "Beispiel "+ Nr,
embedded: true,
direction: "horizontal",
alignX: "left",
alignY: "center",
width: "100%",
height: "auto",
gap: "10px",
backgroundColor: "",
paddingY: "",
paddingX: "",
styles: "",
scrollSettings: {
scrollY: false,
scrollX: false,
},
blocks: [{
width: "fraction",
height: "auto",
lineHeight: "",
alignX: "left",
color: "",
styles: "",
value: ""
}, {
width: "auto",
height: "auto",
lineHeight: "",
alignX: "left",
color: "",
value: "",
}]
})
```
### Full Layout Basis – Breites Layout im Datensatz-Container
Dieses Setup ist für Layouts gedacht, die **nicht eingebettet** sind und sich **über den gesamten Inhaltsbereich eines Datensatzes oder einer Seite erstrecken**. Besonders geeignet für **Dashboards, Übersichtsseiten oder Startbildschirme**, die innerhalb von Ninox aufgeräumt und fokussiert wirken sollen.
✅ Volle Breite innerhalb des Tabs oder Datensatzes
✅ Kein Einbetten – das Layout steht für sich
✅ Ideal für größere Komponenten, Panels oder Übersichtsseiten
### Code mit allen Parametern
```javascript
arcCustomLayout({
uniqueId: Nr,
embedded: true,
fullscreen: false, // Gibst du hier "true" an, wird das Layout in dem ganzen Datensatz eingebunden
fullscreenMode: "full",
page: false, // Gibst du an, wenn du den fullscreen auf einer Tabelle einstellen möchtest.
showAdminTools: false,
hideHeaderIcons: true,
direction: "vertical",
alignX: "center",
alignY: "center",
width: "",
height: "",
gap: "5px",
backgroundColor: "#ccc",
paddingY: "10px",
paddingX: "5px",
blocks: [{
width: "",
height: "auto",
lineHeight: "1.6",
alignX: "left",
value: "",
color: "#000",
styles: "", // Hier kannst du eigene CSS Styles hinterlegen.
clickAction: {
recordId: Nr,
type: "popup"
}
}, {
width: "",
height: "auto",
lineHeight: "",
alignX: "left",
value: "",
color: "", // Fallback: "#000"
clickAction: {
type: "openFullscreen",
recordId: raw(record(Firmen,1).Nr)
},
}]
})
```
**💡Hinweis:** Du kannst auch mehrere Layouts ineinander verschachteln. Somit kannst du komplexe Interfaces aufbauen und Ninox noch übersichtlicher gestalten.
## Allgemeine Settings
Die oberen Parameter geben die allgemeinen Settings deines gesamten Layouts an. Das ist sozusagen der äußerste Container deines Layouts.
### uniqueId
***uniqueId*** ist die individuelle Bezeichnung deines Layouts. Achte darauf, dass du hier einen einzigartigen Titel vergibst. Das ist wichtig, falls du mehrere Layouts auf einer Seite / in einer Tabelle darstellen möchtest und diese sich nicht gegenseitig überschreiben.
```javascript
uniqueId: "Layout container",
```
### embedded
***embedded*** gibt an, ob dein Layout in einem anderen Widget integriert werden soll.
```javascript
embedded: true, // Ja, es wird in einem anderen Widget integriert
embedded: false, // Nein, es ist nicht in anderen Widgets integriert
embedded: false, // default: false
```
### fullscreen
***fullscreen*** bestimmt, ob dein Layout über den gesamten Bildschirm (Datensatz / Page) angezeigt werden soll.
```javascript
fullscreen: true,
fullscreen: false, // default: false
```
### ninoxVersion
***ninoxVersion*** gibt die Ninox-Web-Version an, in der du dich befindest (z. B. `"3.13"`). Für einwandfreies Fullscreen-Verhalten bitte setzen; Werte ab `3.13` gelten auch für neuere Versionen (z. B. `3.15`).
```javascript
ninoxVersion: "3.13",
```
### page
***page*** definiert, ob du das Layout auf einer Page oder in einer Tabelle einbindest. `true` = Page, `false` = Tabelle / Record. Früher wirkte `fullscreenMode: "full"` nur auf Pages; mit `page: false` greift Fullscreen auch auf Records einer Tabelle.
```javascript
page: true, // Page
page: false, // Tabelle / Record
```
### fullscreenMode
***fullscreenMode***: `"full"` blendet Ninox-Header und Tabs aus. Zusammen mit `fullscreen: true` und `ninoxVersion` nutzen.
```javascript
fullscreenMode: "full",
fullscreenMode: "", // default: kein Full-Chrome-Hide
```
### showAdminTools
***showAdminTools*** steuert, ob der Admin-Button (Ninox-Schlüssel) für Admins sichtbar bleibt.
```javascript
showAdminTools: true,
showAdminTools: false, // default: false in vielen Dashboard-Beispielen
```
### scrollSettings
***scrollSettings*** steuert, ob das Layout vertikal (`scrollY`) oder horizontal (`scrollX`) scrollbar ist. Das Layout merkt sich die Scroll-Position — nach Triggern, die Ninox kurz neu laden, bleibt die letzte Position erhalten.
#### scrollY
```javascript
scrollSettings: {
scrollY: true,
scrollX: false,
}
```
#### scrollX
```javascript
scrollSettings: {
scrollY: false,
scrollX: true,
}
```
### direction
***direction*** gibt an, wie deine weiteren Inhalte (blocks) angeordnet werden sollen.
```javascript
direction: "vertical", // Alle Inhalte werden untereinander angeordnet.
direction: "horizontal", // Alle Inhalte werden nebeneinander angeordnet.
```
### alignX
**alignX:** gibt an, wie deine Inhalte auf der X-Achse angeordnet werden.
```javascript
alignX: "center", // zentriert // default: center
alignX: "left", // linksbündig
alignX: "right", // rechtsbündig
alignX: "between", // teilt Blocks auf Gesamtbreite auf
```
### alignY
**alignY:** gibt an, wie deine Inhalte auf der Y-Achse angeordnet werden.
```javascript
alignY: "center", // zentriert // default: center
alignY: "top", // oben angeordnet
alignY: "bottom", // unten angeordnet
alignY: "between", // teilt Blocks auf Gesamthöhe auf
```
### width
***width*** gibt die Weite an.
```javascript
width: "100%", // Prozent-Werte. Hier: volle Breite.
width: "100px", // Pixel-Werte
```
### height
***height*** gibt die Höhe an.
```javascript
height: "auto", // Automatisch an den Inhalt angepasste Höhe.
height: "300px", // Pixel-Werte
```
### gap
Mit ***gap*** bestimmst du, wie viel Abstand zwischen deinen ***blocks*** sein soll.
```javascript
gap: "5px", // Pixel-Werte
```
### actions (Klick auf das gesamte Layout)
Mit ***actions*** auf Widget-Ebene (nicht innerhalb eines Blocks) machst du das **gesamte Layout klickbar** — nützlich z. B. für einen Card-Wrapper oder einen Mobile-Dimmer, ohne dass du dafür einen eigenen Block brauchst.
```javascript
actions: [{
recordId: Nr,
type: "popup"
}]
```
Mehrere Einträge werden nacheinander ausgeführt, `dataBag` funktioniert wie bei jeder anderen Action auf `update`/`create`-Typ:
```javascript
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "helper_mainContentState"),
dataBag: {
base: helper_mainContentState,
patch: { sidebarOpen: "" }
}
}]
```
**Wichtig:** Hat ein einzelner Block selbst `actions` oder `clickAction`, wird dessen Klick **nicht** zusätzlich an die Widget-`actions` weitergegeben (kein Doppel-Feuern) — nur Klicks außerhalb eines konfigurierten Blocks lösen die Widget-`actions` aus.
Ausführlich zu Block-Actions: [`actions Block`](#actions-block-empfohlen) weiter unten.
### loading (Widget-Ebene)
Mit **`loading`** steuerst du, ob beim Ausführen der Widget-`actions` ein Spinner über dem Zielbereich erscheint. Ohne `loading` (oder mit `show: false`) läuft die Action wie bisher — nur ohne visuelles Feedback.
```javascript
loading: {
show: true,
target: "layout", // Default: "layout" | { blockId: "sidebar" }
indicator: { type: "spinner", color: "#4970ff", width: "32px", height: "32px" },
dim: true, // halbtransparenter Hintergrund über dem Zielbereich
minDuration: 300, // Mindest-Anzeigedauer in ms
hideOnFinish: true // Default: true
}
```
**`target`** auf Widget-Ebene:
| Wert | Bedeutung |
|---|---|
| `"layout"` (Default) | Spinner über dem gesamten Layout |
| `{ blockId: "sidebar" }` | Spinner nur über dem Block mit dieser `blockId` |
**`indicator.type`:** `dots` | `spinner` | `pulse` — wie beim Button.
#### overlay (Fullscreen-Modal)
Mit **`loading.overlay`** erscheint statt des lokalen Block-/Layout-Overlays ein **Fullscreen-Modal** über der gesamten Ansicht — identisch zum Button (`arcModalWindows`). `target` und `dim` werden in diesem Modus ignoriert.
| `overlay` | Verhalten |
|-----------|-----------|
| `true` | Nur Backdrop + Spinner |
| `{ title, message }` | Feste Meldung in der Dialog-Karte |
| `{ sequences: [...] }` | Dynamische Meldungen (Zeit +/oder Ninox-Booleans) |
```javascript
loading: {
show: true,
overlay: {
title: { value: "Wird gespeichert…", styles: "font-size: 18px; font-weight: 700;" },
message: "Bitte einen Moment warten.",
indicator: { type: "spinner", color: "#4970ff", width: "32px", height: "32px" }
},
minDuration: 300,
hideOnFinish: true
}
```
Vollständige Overlay-API (`width`, `height`, `backgroundColor`, `sequences`, `when`, `priority`): siehe [Button Loading — overlay](../mini_widgets/buttons.md#overlay-zusätzlich).
## Settings im Layout Block
Die Parameter innerhalb eines Blocks bestimmen Werte die zu einem jeweiligen Layoutblock gehören. Du kannst auch weitere Blöcke hinzufügen (Komma getrennt).
```javascript
blocks: [{ // Beginn Block 1
blockId: "sidebar", // optional — stabile ID für Loading-Targeting
width: "",
height: "auto",
lineHeight: "1.6", // default: normal
alignX: "left",
color: "#000", // Schriftfarbe von Text im Layoutblock
backgroundColor: "#333", // Hintergrundfarbe von Text im Layoutblock
styles: "", // Hier kannst du eigene CSS Styles hinterlegen.
value: "", // Hier gibst du den Wert an, der im Block ausgegeben werden soll.
clickAction: {
recordId: Nr,
type: "popup"
}
},
{ // Beginn Block 2
width: "",
height: "auto",
lineHeight: "1.6", // default: normal
alignX: "left",
color: "#000",
backgroundColor: "#ccc",
styles: "", // Hier kannst du eigene CSS Styles hinterlegen.
value: "",
clickAction: {
recordId: Nr,
type: "popup"
}
}
}]
```
### width
***width ***und*** height*** geben die Breite und Höhe des Layoutblocks an.
```javascript
width: "auto", // Automatisch an den Inhalt angepasste Weite. // default:
width: "300px", // Pixel-Werte oder Prozenz-Werte
height: "auto", // Automatisch an den Inhalt angepasste Höhe. // default:
height: "300px", // Pixel-Werte oder Prozenz-Werte
```
### lineHeight
Mit*** lineHeight ***bestimmst du den Abstand zwischen den Zeilen im Layout.
```javascript
lineHeight: "1.6", // default: normal
```
### alignX
**alignX:** gibt an, wie deine Inhalte auf der X-Achse innerhalb des Layoutblocks angeordnet werden.
```javascript
alignX: "center", // zentriert // default: center
alignX: "left", // linksbündig
alignX: "right", // rechtsbündig
alignX: "between", // teilt Blocks auf Gesamtbreite auf
```
### color & backgroundColor
Mit ***color***** und *****backgroundColor***** **bestimmst du die Schriftfarbe und Hintergrundfarbe des Textes innerhalb deines Layoutblocks.
```javascript
color: "#33AAFF", // default: #000
backgroundColor: "#ccc", // default: no default color
```
### styles
Bei ***styles*** kannst du dem Layoutblock eigene CSS styles hinzufügen.
```javascript
styles: "", // z.B. font-weight: 700;
```
### value
***value*** ist der Wert, der innerhalb des Layoutblocks ausgegeben wird. Hier kannst du z.B. Text, Ninox-Felder oder customWidgets angeben.
```javascript
value: "Überschrift", // einfacher Text
value: Titel, // Ninox-Feld
value: arcCustomButton({...}) // Top-Level oder Legacy: Funktionsaufruf
value: "", // default: Gibst du keinen Wert an, wird nichts ausgegeben ;)
```
#### Verschachtelte Widgets (Next-Gen, Object-Notation)
Wenn ein Block **ein anderes arcWidget** enthält und beide aus dem aktuellen **`bundle.js`** kommen, kannst du statt `arcCustomButton({ … })` ein **Descriptor-Objekt** setzen:
```javascript
value: {
widget: "arc-widget-button",
uniqueId: "block-btn-" + Nr, // uid: "block-btn-" + Nr ist gleichwertig
data: {
title: "Speichern",
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "Status"), value: "done" }]
}
}
```
- **`widget`**: interne ID (`arc-widget-layout`, `arc-widget-button`, …) — nicht der Funktionsname
- **`uniqueId`** oder **`uid`**: beide akzeptiert — top-level, **nicht** in `data`
- **`data`**: dieselben Parameter wie im Funktionsaufruf
**Wichtig:** Funktioniert nur mit **Next-Gen-Widgets** im Bundle. Alte **Legacy-Ninox-Formeln** (noch nicht als JS-Widget deployed) verstehen diese Objekte nicht.
Ausführlich: [`nested-widget-descriptors`](../patterns/nested-widget-descriptors.md)
#### actions Block (empfohlen)
***actions*** beschreibt deine Aktionen in den jeweiligen Blocks als Array. Mehrere Einträge werden nacheinander ausgeführt — z. B. erst State leeren, dann Record öffnen.
```javascript
actions: [{
recordId: Nr,
type: "update",
fieldId: fieldId(Nr, "helper_uiState"),
dataBag: {
base: helper_uiState,
patch: { activeTab: "details" }
}
}, {
recordId: Nr,
type: "popup"
}]
```
***openTable*** öffnet eine Tabellenansicht in Ninox:
```javascript
actions: [{
type: "openTable",
tableId: "A"
}]
```
***openUrl*** öffnet eine externe URL:
```javascript
actions: [{
type: "openUrl",
value: "https://www.arc-rider.com"
}]
```
**Action-Typen** (wie bei Button und anderen Widgets):
Wiederholtes Trigger-`update` mit `polling` + Formel-Boolean `active`: siehe [`action-polling`](../patterns/action-polling.md).
```javascript
// Folgende Actions benötigen die zwei Parameter: "recordId" und "type"
"popup"
"delete"
"openRecord"
"fullscreen"
// Folgende Action benötigt die 4 Parameter: "recordId", "type", "field", "value"
"update"
// Folgende Action benötigt 2 Parameter: "type", "value"
"openUrl"
// Folgende Action benötigt 2 Parameter: "type", "tableId"
"openTable"
// Folgende Actions benötigen nur den Parameter "type"
"closeFullScreen"
"closeRecord"
"closeAllRecords"
```
Partielle State-Updates per `dataBag` auf `update`-Actions: [`data-bag-actions`](../patterns/data-bag-actions.md).
#### loading Block
Mit **`loading`** auf Block-Ebene steuerst du den Spinner beim Ausführen der Block-`actions`. Das Ziel kann der Block selbst, ein anderer Block oder das gesamte Layout sein.
```javascript
blockId: "save-panel",
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "Status"), value: "done" }],
loading: {
show: true,
target: "block", // Default: "block" | "layout" | { blockId: "other" }
indicator: { type: "spinner", color: "#4970ff" },
dim: true,
minDuration: 300,
hideOnFinish: true
}
```
**`target`** auf Block-Ebene:
| Wert | Bedeutung |
|---|---|
| `"block"` (Default) | Spinner über dem geklickten Block |
| `"layout"` | Spinner über dem gesamten Layout |
| `{ blockId: "sidebar" }` | Spinner über einem anderen Block (per `blockId`) |
**`blockId`** ist optional, aber nötig wenn du per `{ blockId: "…" }` ein anderes Ziel ansprechen willst. Die ID muss auf der Seite eindeutig sein — `{ blockId: "…" }` sucht zuerst im selben Layout, dann seitenweit (funktioniert also auch, wenn der Ziel-Block in einem übergeordneten Layout liegt, das dieses Layout per `blocks[].value: { widget: "arc-widget-layout", … }` verschachtelt).
**`loading.overlay`** funktioniert auch auf Block-Ebene — dann erscheint das Fullscreen-Modal statt des lokalen Overlays (siehe [overlay (Widget-Ebene)](#overlay-fullscreen-modal) oben).
Während eine Action läuft, sind erneute Klicks auf denselben Zielbereich blockiert (Re-Entry-Schutz).
#### clickAction Block (Legacy)
Das frühere einzelne Feld **`clickAction`** wird weiterhin unterstützt und wie ein Eintrag in `actions` ausgeführt. Für neue Konfigurationen **`actions`** verwenden.
```javascript
clickAction: {
recordId: Nr,
type: "update",
field: "",
value: ""
}
```
```javascript
clickAction: {
type: "openTable",
tableId: "A"
}
```
```javascript
clickAction: {
type: "openUrl",
value: "https://www.arc-rider.com"
}
```
#### Fullscreen Mode (Ninox)
***fullscreenMode*** blendet bei `fullscreen: true` Ninox-Formelemente aus. `showAdminTools` steuert den Ninox-Schlüssel für andere Admins. `hideHeaderIcons` blendet Ninox-Symbole im Header.
```javascript
fullscreen: true,
fullscreenMode: "full",
showAdminTools: true,
hideHeaderIcons: true,
```
# Custom Layout
## AI Defaults (read first)
- **Dashboard wrappers**: MUST have `fullscreen: true`, `fullscreenMode: if isAdminMode() then "" else "full" end`, `height: "100%"`.
- **embedded**: `false` for standalone/dashboard layouts, `true` when nested inside another widget.
- **direction**: Always set explicitly (`"horizontal"` or `"vertical"`).
- **Block widths**: At least one block should use `width: "fraction"` to fill remaining space.
- **Scrollable areas**: Use `height: "fraction"` + `scrollSettings: { scrollY: true }` for content below fixed headers.
- **uniqueId**: Required, no special characters.
- **Sticky headers**: Need `overflow-x: hidden` on parent (NOT `overflow: hidden`), background-color, and z-index.
- **Two for-loops**: NEVER place two for-loops side by side in blocks – each needs its own wrapper layout.
- **Nested widgets (Next-Gen)**: In `blocks[].value`, use `{ widget: "arc-widget-…", uid: "…", data: { … } }` — not `arcCustomXxx({ … })`. Requires current `bundle.js`; legacy Ninox-formula widgets do not support this. See `docs/patterns/nested-widget-descriptors.md`.
# Custom Layout
Mit dem Layout-Widget gestaltest du Oberflächen ohne Tabellenraster — flexibler Container (wie Flexbox): Ausrichtung, Abstände, Farben, verschachtelte Widgets.
Ob du einfache Abschnitte nebeneinander anordnen willst, eine Info-Card mit grafischem Hintergrund bauen möchtest oder interaktive Elemente auf einer Seite strukturieren willst – `arcCustomLayout` ist dein Werkzeug dafür.
**Dabei steuerst du:**
- Ausrichtung (horizontal / vertikal)
- Abstände, Farben, Hintergrundbilder
- Flexibles Verhalten bei Bildschirmgrößen
- Individuelle Stile je Block
- Interaktionen (z. B. Klickaktionen auf Bereiche)
Im Gegensatz zum `arcCustomGrid`, das für zweidimensionale Strukturen (Zeilen *und* Spalten) gedacht ist, arbeitet das Layout bewusst **eindimensional**: Du bestimmst, ob die Inhalte **horizontal (nebeneinander)** oder **vertikal (untereinander)** dargestellt werden – inklusive Ausrichtung, Abstände, Farben und responsiven Anpassungen.
**🎯 Was du damit machen kannst:**
- **Karten-ähnliche Layouts** mit Titel, Beschreibung und Buttons nebeneinander
- **Hero-Bereiche** mit großem Textblock + Bild nebeneinander (horizontal)
- **Vertikale Formblöcke** mit gezieltem Abstand und Hintergrundfarbe
- **Interaktive Blöcke** mit Klickfunktionen (Popup, Update, Löschen, etc.)
- **Kombination mehrerer Datenquellen** in einem dynamischen Layout
## Anwendungscode
### Schneller Einstieg – Simple Basis Layout
Ein kompaktes Beispiel, mit dem du direkt starten kannst. Ideal, wenn du ein paar Inhalte nebeneinander (`direction: "horizontal"`) oder untereinander (`direction: "vertical"`) anordnen willst – zum Beispiel Textbausteine, KPIs oder Buttons. Die wichtigsten Parameter wie Ausrichtung, Breite und Abstand sind bereits gesetzt und lassen sich leicht anpassen.
✅ Schnell einsetzbar
✅ Flexibel anpassbar
✅ Perfekt zum Kopieren und Loslegen
```javascript
arcCustomLayout({
uniqueId: "Beispiel "+ Nr,
embedded: true,
direction: "horizontal",
alignX: "left",
alignY: "center",
width: "100%",
height: "auto",
gap: "10px",
backgroundColor: "",
paddingY: "",
paddingX: "",
styles: "",
scrollSettings: {
scrollY: false,
scrollX: false,
},
blocks: [{
width: "fraction",
height: "auto",
lineHeight: "",
alignX: "left",
color: "",
styles: "",
value: ""
}, {
width: "auto",
height: "auto",
lineHeight: "",
alignX: "left",
color: "",
value: "",
}]
})
```
### Full Layout Basis – Breites Layout im Datensatz-Container
Dieses Setup ist für Layouts gedacht, die **nicht eingebettet** sind und sich **über den gesamten Inhaltsbereich eines Datensatzes oder einer Seite erstrecken**. Besonders geeignet für **Dashboards, Übersichtsseiten oder Startbildschirme**, die innerhalb von Ninox aufgeräumt und fokussiert wirken sollen.
✅ Volle Breite innerhalb des Tabs oder Datensatzes
✅ Kein Einbetten – das Layout steht für sich
✅ Ideal für größere Komponenten, Panels oder Übersichtsseiten
### Code mit allen Parametern
```javascript
arcCustomLayout({
uniqueId: Nr,
embedded: true,
fullscreen: false, // Gibst du hier "true" an, wird das Layout in dem ganzen Datensatz eingebunden
fullscreenMode: "full",
page: false, // Gibst du an, wenn du den fullscreen auf einer Tabelle einstellen möchtest.
showAdminTools: false,
hideHeaderIcons: true,
direction: "vertical",
alignX: "center",
alignY: "center",
width: "",
height: "",
gap: "5px",
backgroundColor: "#ccc",
paddingY: "10px",
paddingX: "5px",
blocks: [{
width: "",
height: "auto",
lineHeight: "1.6",
alignX: "left",
value: "",
color: "#000",
styles: "", // Hier kannst du eigene CSS Styles hinterlegen.
clickAction: {
recordId: Nr,
type: "popup"
}
}, {
width: "",
height: "auto",
lineHeight: "",
alignX: "left",
value: "",
color: "", // Fallback: "#000"
clickAction: {
type: "openFullscreen",
recordId: raw(record(Firmen,1).Nr)
},
}]
})
```
**💡Hinweis:** Du kannst auch mehrere Layouts ineinander verschachteln. Somit kannst du komplexe Interfaces aufbauen und Ninox noch übersichtlicher gestalten.
## Allgemeine Settings
Die oberen Parameter geben die allgemeinen Settings deines gesamten Layouts an. Das ist sozusagen der äußerste Container deines Layouts.
### uniqueId
***uniqueId*** ist die individuelle Bezeichnung deines Layouts. Achte darauf, dass du hier einen einzigartigen Titel vergibst. Das ist wichtig, falls du mehrere Layouts auf einer Seite / in einer Tabelle darstellen möchtest und diese sich nicht gegenseitig überschreiben.
```javascript
uniqueId: "Layout container",
```
### embedded
***embedded*** gibt an, ob dein Layout in einem anderen Widget integriert werden soll.
```javascript
embedded: true, // Ja, es wird in einem anderen Widget integriert
embedded: false, // Nein, es ist nicht in anderen Widgets integriert
embedded: false, // default: false
```
### fullscreen
***fullscreen*** bestimmt, ob dein Layout über den gesamten Bildschirm (Datensatz / Page) angezeigt werden soll.
```javascript
fullscreen: true,
fullscreen: false, // default: false
```
### ninoxVersion
***ninoxVersion*** gibt die Ninox-Web-Version an, in der du dich befindest (z. B. `"3.13"`). Für einwandfreies Fullscreen-Verhalten bitte setzen; Werte ab `3.13` gelten auch für neuere Versionen (z. B. `3.15`).
```javascript
ninoxVersion: "3.13",
```
### page
***page*** definiert, ob du das Layout auf einer Page oder in einer Tabelle einbindest. `true` = Page, `false` = Tabelle / Record. Früher wirkte `fullscreenMode: "full"` nur auf Pages; mit `page: false` greift Fullscreen auch auf Records einer Tabelle.
```javascript
page: true, // Page
page: false, // Tabelle / Record
```
### fullscreenMode
***fullscreenMode***: `"full"` blendet Ninox-Header und Tabs aus. Zusammen mit `fullscreen: true` und `ninoxVersion` nutzen.
```javascript
fullscreenMode: "full",
fullscreenMode: "", // default: kein Full-Chrome-Hide
```
### showAdminTools
***showAdminTools*** steuert, ob der Admin-Button (Ninox-Schlüssel) für Admins sichtbar bleibt.
```javascript
showAdminTools: true,
showAdminTools: false, // default: false in vielen Dashboard-Beispielen
```
### scrollSettings
***scrollSettings*** steuert, ob das Layout vertikal (`scrollY`) oder horizontal (`scrollX`) scrollbar ist. Das Layout merkt sich die Scroll-Position — nach Triggern, die Ninox kurz neu laden, bleibt die letzte Position erhalten.
#### scrollY
```javascript
scrollSettings: {
scrollY: true,
scrollX: false,
}
```
#### scrollX
```javascript
scrollSettings: {
scrollY: false,
scrollX: true,
}
```
### direction
***direction*** gibt an, wie deine weiteren Inhalte (blocks) angeordnet werden sollen.
```javascript
direction: "vertical", // Alle Inhalte werden untereinander angeordnet.
direction: "horizontal", // Alle Inhalte werden nebeneinander angeordnet.
```
### alignX
**alignX:** gibt an, wie deine Inhalte auf der X-Achse angeordnet werden.
```javascript
alignX: "center", // zentriert // default: center
alignX: "left", // linksbündig
alignX: "right", // rechtsbündig
alignX: "between", // teilt Blocks auf Gesamtbreite auf
```
### alignY
**alignY:** gibt an, wie deine Inhalte auf der Y-Achse angeordnet werden.
```javascript
alignY: "center", // zentriert // default: center
alignY: "top", // oben angeordnet
alignY: "bottom", // unten angeordnet
alignY: "between", // teilt Blocks auf Gesamthöhe auf
```
### width
***width*** gibt die Weite an.
```javascript
width: "100%", // Prozent-Werte. Hier: volle Breite.
width: "100px", // Pixel-Werte
```
### height
***height*** gibt die Höhe an.
```javascript
height: "auto", // Automatisch an den Inhalt angepasste Höhe.
height: "300px", // Pixel-Werte
```
### gap
Mit ***gap*** bestimmst du, wie viel Abstand zwischen deinen ***blocks*** sein soll.
```javascript
gap: "5px", // Pixel-Werte
```
### actions (Klick auf das gesamte Layout)
Mit ***actions*** auf Widget-Ebene (nicht innerhalb eines Blocks) machst du das **gesamte Layout klickbar** — nützlich z. B. für einen Card-Wrapper oder einen Mobile-Dimmer, ohne dass du dafür einen eigenen Block brauchst.
```javascript
actions: [{
recordId: Nr,
type: "popup"
}]
```
Mehrere Einträge werden nacheinander ausgeführt, `dataBag` funktioniert wie bei jeder anderen Action auf `update`/`create`-Typ:
```javascript
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "helper_mainContentState"),
dataBag: {
base: helper_mainContentState,
patch: { sidebarOpen: "" }
}
}]
```
**Wichtig:** Hat ein einzelner Block selbst `actions` oder `clickAction`, wird dessen Klick **nicht** zusätzlich an die Widget-`actions` weitergegeben (kein Doppel-Feuern) — nur Klicks außerhalb eines konfigurierten Blocks lösen die Widget-`actions` aus.
Ausführlich zu Block-Actions: [`actions Block`](#actions-block-empfohlen) weiter unten.
### loading (Widget-Ebene)
Mit **`loading`** steuerst du, ob beim Ausführen der Widget-`actions` ein Spinner über dem Zielbereich erscheint. Ohne `loading` (oder mit `show: false`) läuft die Action wie bisher — nur ohne visuelles Feedback.
```javascript
loading: {
show: true,
target: "layout", // Default: "layout" | { blockId: "sidebar" }
indicator: { type: "spinner", color: "#4970ff", width: "32px", height: "32px" },
dim: true, // halbtransparenter Hintergrund über dem Zielbereich
minDuration: 300, // Mindest-Anzeigedauer in ms
hideOnFinish: true // Default: true
}
```
**`target`** auf Widget-Ebene:
| Wert | Bedeutung |
|---|---|
| `"layout"` (Default) | Spinner über dem gesamten Layout |
| `{ blockId: "sidebar" }` | Spinner nur über dem Block mit dieser `blockId` |
**`indicator.type`:** `dots` | `spinner` | `pulse` — wie beim Button.
#### overlay (Fullscreen-Modal)
Mit **`loading.overlay`** erscheint statt des lokalen Block-/Layout-Overlays ein **Fullscreen-Modal** über der gesamten Ansicht — identisch zum Button (`arcModalWindows`). `target` und `dim` werden in diesem Modus ignoriert.
| `overlay` | Verhalten |
|-----------|-----------|
| `true` | Nur Backdrop + Spinner |
| `{ title, message }` | Feste Meldung in der Dialog-Karte |
| `{ sequences: [...] }` | Dynamische Meldungen (Zeit +/oder Ninox-Booleans) |
```javascript
loading: {
show: true,
overlay: {
title: { value: "Wird gespeichert…", styles: "font-size: 18px; font-weight: 700;" },
message: "Bitte einen Moment warten.",
indicator: { type: "spinner", color: "#4970ff", width: "32px", height: "32px" }
},
minDuration: 300,
hideOnFinish: true
}
```
Vollständige Overlay-API (`width`, `height`, `backgroundColor`, `sequences`, `when`, `priority`): siehe [Button Loading — overlay](../mini_widgets/buttons.md#overlay-zusätzlich).
## Settings im Layout Block
Die Parameter innerhalb eines Blocks bestimmen Werte die zu einem jeweiligen Layoutblock gehören. Du kannst auch weitere Blöcke hinzufügen (Komma getrennt).
```javascript
blocks: [{ // Beginn Block 1
blockId: "sidebar", // optional — stabile ID für Loading-Targeting
width: "",
height: "auto",
lineHeight: "1.6", // default: normal
alignX: "left",
color: "#000", // Schriftfarbe von Text im Layoutblock
backgroundColor: "#333", // Hintergrundfarbe von Text im Layoutblock
styles: "", // Hier kannst du eigene CSS Styles hinterlegen.
value: "", // Hier gibst du den Wert an, der im Block ausgegeben werden soll.
clickAction: {
recordId: Nr,
type: "popup"
}
},
{ // Beginn Block 2
width: "",
height: "auto",
lineHeight: "1.6", // default: normal
alignX: "left",
color: "#000",
backgroundColor: "#ccc",
styles: "", // Hier kannst du eigene CSS Styles hinterlegen.
value: "",
clickAction: {
recordId: Nr,
type: "popup"
}
}
}]
```
### width
***width ***und*** height*** geben die Breite und Höhe des Layoutblocks an.
```javascript
width: "auto", // Automatisch an den Inhalt angepasste Weite. // default:
width: "300px", // Pixel-Werte oder Prozenz-Werte
height: "auto", // Automatisch an den Inhalt angepasste Höhe. // default:
height: "300px", // Pixel-Werte oder Prozenz-Werte
```
### lineHeight
Mit*** lineHeight ***bestimmst du den Abstand zwischen den Zeilen im Layout.
```javascript
lineHeight: "1.6", // default: normal
```
### alignX
**alignX:** gibt an, wie deine Inhalte auf der X-Achse innerhalb des Layoutblocks angeordnet werden.
```javascript
alignX: "center", // zentriert // default: center
alignX: "left", // linksbündig
alignX: "right", // rechtsbündig
alignX: "between", // teilt Blocks auf Gesamtbreite auf
```
### color & backgroundColor
Mit ***color***** und *****backgroundColor***** **bestimmst du die Schriftfarbe und Hintergrundfarbe des Textes innerhalb deines Layoutblocks.
```javascript
color: "#33AAFF", // default: #000
backgroundColor: "#ccc", // default: no default color
```
### styles
Bei ***styles*** kannst du dem Layoutblock eigene CSS styles hinzufügen.
```javascript
styles: "", // z.B. font-weight: 700;
```
### value
***value*** ist der Wert, der innerhalb des Layoutblocks ausgegeben wird. Hier kannst du z.B. Text, Ninox-Felder oder customWidgets angeben.
```javascript
value: "Überschrift", // einfacher Text
value: Titel, // Ninox-Feld
value: arcCustomButton({...}) // Top-Level oder Legacy: Funktionsaufruf
value: "", // default: Gibst du keinen Wert an, wird nichts ausgegeben ;)
```
#### Verschachtelte Widgets (Next-Gen, Object-Notation)
Wenn ein Block **ein anderes arcWidget** enthält und beide aus dem aktuellen **`bundle.js`** kommen, kannst du statt `arcCustomButton({ … })` ein **Descriptor-Objekt** setzen:
```javascript
value: {
widget: "arc-widget-button",
uniqueId: "block-btn-" + Nr, // uid: "block-btn-" + Nr ist gleichwertig
data: {
title: "Speichern",
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "Status"), value: "done" }]
}
}
```
- **`widget`**: interne ID (`arc-widget-layout`, `arc-widget-button`, …) — nicht der Funktionsname
- **`uniqueId`** oder **`uid`**: beide akzeptiert — top-level, **nicht** in `data`
- **`data`**: dieselben Parameter wie im Funktionsaufruf
**Wichtig:** Funktioniert nur mit **Next-Gen-Widgets** im Bundle. Alte **Legacy-Ninox-Formeln** (noch nicht als JS-Widget deployed) verstehen diese Objekte nicht.
Ausführlich: [`nested-widget-descriptors`](../patterns/nested-widget-descriptors.md)
#### actions Block (empfohlen)
***actions*** beschreibt deine Aktionen in den jeweiligen Blocks als Array. Mehrere Einträge werden nacheinander ausgeführt — z. B. erst State leeren, dann Record öffnen.
```javascript
actions: [{
recordId: Nr,
type: "update",
fieldId: fieldId(Nr, "helper_uiState"),
dataBag: {
base: helper_uiState,
patch: { activeTab: "details" }
}
}, {
recordId: Nr,
type: "popup"
}]
```
***openTable*** öffnet eine Tabellenansicht in Ninox:
```javascript
actions: [{
type: "openTable",
tableId: "A"
}]
```
***openUrl*** öffnet eine externe URL:
```javascript
actions: [{
type: "openUrl",
value: "https://www.arc-rider.com"
}]
```
**Action-Typen** (wie bei Button und anderen Widgets):
Wiederholtes Trigger-`update` mit `polling` + Formel-Boolean `active`: siehe [`action-polling`](../patterns/action-polling.md).
```javascript
// Folgende Actions benötigen die zwei Parameter: "recordId" und "type"
"popup"
"delete"
"openRecord"
"fullscreen"
// Folgende Action benötigt die 4 Parameter: "recordId", "type", "field", "value"
"update"
// Folgende Action benötigt 2 Parameter: "type", "value"
"openUrl"
// Folgende Action benötigt 2 Parameter: "type", "tableId"
"openTable"
// Folgende Actions benötigen nur den Parameter "type"
"closeFullScreen"
"closeRecord"
"closeAllRecords"
```
Partielle State-Updates per `dataBag` auf `update`-Actions: [`data-bag-actions`](../patterns/data-bag-actions.md).
#### loading Block
Mit **`loading`** auf Block-Ebene steuerst du den Spinner beim Ausführen der Block-`actions`. Das Ziel kann der Block selbst, ein anderer Block oder das gesamte Layout sein.
```javascript
blockId: "save-panel",
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "Status"), value: "done" }],
loading: {
show: true,
target: "block", // Default: "block" | "layout" | { blockId: "other" }
indicator: { type: "spinner", color: "#4970ff" },
dim: true,
minDuration: 300,
hideOnFinish: true
}
```
**`target`** auf Block-Ebene:
| Wert | Bedeutung |
|---|---|
| `"block"` (Default) | Spinner über dem geklickten Block |
| `"layout"` | Spinner über dem gesamten Layout |
| `{ blockId: "sidebar" }` | Spinner über einem anderen Block (per `blockId`) |
**`blockId`** ist optional, aber nötig wenn du per `{ blockId: "…" }` ein anderes Ziel ansprechen willst. Die ID muss auf der Seite eindeutig sein — `{ blockId: "…" }` sucht zuerst im selben Layout, dann seitenweit (funktioniert also auch, wenn der Ziel-Block in einem übergeordneten Layout liegt, das dieses Layout per `blocks[].value: { widget: "arc-widget-layout", … }` verschachtelt).
**`loading.overlay`** funktioniert auch auf Block-Ebene — dann erscheint das Fullscreen-Modal statt des lokalen Overlays (siehe [overlay (Widget-Ebene)](#overlay-fullscreen-modal) oben).
Während eine Action läuft, sind erneute Klicks auf denselben Zielbereich blockiert (Re-Entry-Schutz).
#### clickAction Block (Legacy)
Das frühere einzelne Feld **`clickAction`** wird weiterhin unterstützt und wie ein Eintrag in `actions` ausgeführt. Für neue Konfigurationen **`actions`** verwenden.
```javascript
clickAction: {
recordId: Nr,
type: "update",
field: "",
value: ""
}
```
```javascript
clickAction: {
type: "openTable",
tableId: "A"
}
```
```javascript
clickAction: {
type: "openUrl",
value: "https://www.arc-rider.com"
}
```
## Vue
Das `data`-Objekt wird als Prop an die Vue-Komponente übergeben.
```vue
```
---
# Custom Menu
Source: https://www.arc-rider.com/docs/widgets/custom-menu
# Custom Menu
## AI Defaults (read first)
- **uniqueId**: Required, `"menu-" + Nr`.
- **tableId**: Required – the table the menu writes to (e.g. `tableId("Dashboard")`).
- **menuItems**: Each item needs `item` (number), `title`, `active` (boolean), `actions`.
- **actions**: Use `type: "update"` with `recordId: Nr`, `field: fieldId(Nr, "Feldname")`.
- **active state**: Set `active: Feldname = "Wert"` to highlight current selection.
- **embedded**: Default `false`, set `true` when nested.
# Custom Menu
Das Widget `arcCustomMenu` ist ein flexibles Menü-System, mit dem du Navigationselemente, Filter oder Umschaltoptionen direkt auf deiner Oberfläche darstellen kannst. Ideal, um zwischen Ansichten zu wechseln, Datenfelder zu setzen oder Popups auszulösen – ganz ohne komplexes UI-Bauen in Ninox.
Das Menü lässt sich optisch komplett an dein Design anpassen: Farben, Schriftgrößen, Icons, aktive Zustände und Hover-Effekte sind frei konfigurierbar. Buttons können zusätzlich Badges tragen und mit verschiedenen Aktionen belegt werden (`update`, `popup`, `delete`).
💡 Das Widget kann **eingebettet** in bestehende Layouts verwendet werden oder als eigene Komponente dargestellt werden – je nach Einsatzszenario.
## 🔧 Struktur des arcCustomMenu-Widgets
Das `arcCustomMenu` besteht aus einem zentralen Konfigurationsobjekt mit folgenden Bereichen:
- **Allgemeine Einstellungen**
Direkt auf oberster Ebene (`uniqueId`, `embedded`, `hoverActions`)
- **Menü-Konfiguration (**`**menu[…]**`**)**
Steuert das Layout der Menüleiste – z. B. Positionierung, Schriftgröße und Farben für normale und aktive Zustände
- **Menüpunkte (**`**menu[…].menuItems[…]**`**)**
Einzelne Buttons mit Titel, Icon, Aktivitätszustand und Aktionen (z. B. Feldwert ändern, Popup öffnen)
```javascript
let current := this;
arcCustomMenu({
uniqueId: "menu " + Nr,
embedded: false,
borderRadius: "4px",
hoverActions: {
backgroundColor: "#192e65",
fontColor: "#fff",
borderColor: "#192e65",
iconColor: "#fff",
animation: "0.2s"
},
menu: [{
tableId: tableId(current),
embedded: false,
settings: {
menuBar: {
width: "",
position: "",
backgroundColor: "",
borderColor: "",
fontSize: "20px"
},
stateNormal: {
backgroundColor: "",
borderColor: "",
fontColor: ""
},
stateActive: {
backgroundColor: "",
borderColor: "",
fontColor: ""
}
}
}, {
menuItems: [{
item: 1,
title: "Table",
active: Menu = text("A"),
icon: arcCustomIcon({
name: "table"
}),
actions: [{
recordId: Nr,
type: "update",
field: "K",
value: "A"
}]
}, {
item: 2,
title: "Kanban",
active: Menu = text("B"),
icon: arcCustomIcon({
name: "kanban"
}),
actions: [{
recordId: Nr,
type: "update",
field: "K",
value: "B"
}]
}, {
item: 3,
title: "KPI Bar",
active: Menu = text("C"),
icon: arcCustomIcon({
name: "copy"
}),
actions: [{
recordId: Nr,
type: "update",
field: "K",
value: "C"
}]
}]
}]
})
```
## Allgemeine Parameter-Einstellungen
### uniqueId
**Typ:** `text`
**Pflichtfeld:** ja
Definiert eine eindeutige ID für die jeweilige Menü-Instanz. Diese ID wird intern zur gezielten CSS-Ansprache verwendet und ist notwendig, damit mehrere Menüs auf derselben Seite unabhängig voneinander funktionieren.
💡 **Tipp: **Setze die ID dynamisch, z. B. mit `uniqueId: "menu-" + Nr`, wenn du das Widget mehrfach aufrufst.
### embedded
**Typ:** `boolean`
**Default:** `false`
Legt fest, ob das Widget in ein bestehendes Widget (z. B. [Layout](https://www.arc-rider.de/documentation/custom-layout)) eingebettet wird oder als eigenständiges Widget auf der Ninox Oberfläche integriert wird.
💡 **Hinweis: **Wenn du `embedded: true` setzt, musst du sicherstellen, dass das umgebende Element eine passende Höhe und ggf. ein eigenes Layout mitbringt. Das Widget passt sich dann vollständig diesem Rahmen an.
### hoverActions
**Typ:** `object`
**Default:** kein Hover-Verhalten
Definiert das Verhalten beim Überfahren eines Menüpunktes mit der Maus.
Du kannst hier gezielt Farben und Animationen setzen, die beim Hover-Effekt angewendet werden sollen. Alle Felder sind optional – wenn du nichts angibst, bleibt das Standarddesign erhalten.
Feld
Typ
Beschreibung
`backgroundColor`
`text`
Hintergrundfarbe beim Hover. Z. B. HEX-Wert: `"#192e65"`
`fontColor`
`text`
Schriftfarbe beim Hover. Z. B. HEX-Wert: `"#fff"`
`borderColor`
`text`
Rahmenfarbe beim Hover. Z. B. HEX-Wert: `"#192e65"`
`iconColor`
`text`
Farbe des Icons beim Hover. Z. B. HEX-Wert:`"#fff"`
`animation`
`text`
Transition-Zeit, z. B. `"0.2s"` für weiche Effekte
💡 **Tipp: **Hover-Effekte verbessern die Benutzerführung deutlich – sie geben visuelles Feedback und zeigen, dass ein Element interaktiv ist. Schon ein einzelner Wert wie `backgroundColor` reicht aus, um dieses Feedback spürbar zu machen.
### borderRadius
**Typ:** `text`
**Default:** kein Radius (eckige Kanten)
Legt den Eckenradius der Menü-Buttons fest. Mit diesem Wert kannst du die Buttons abgerundet gestalten – von leicht soften Ecken bis zu pillenförmig.
Typische Werte:
- `"4px"` für leicht abgerundet
- `"12px"` für deutliche Rundung
- `"50%"` für kreisförmige Buttons
💡 **Tipp: **Ein kleiner `borderRadius` sorgt oft schon für ein moderneres, freundlicheres Erscheinungsbild – vor allem in Kombination mit Hover-Farben.
## Menü-Einstellungen (`menu[…]`)
In diesem Block steuerst du das Layout und Design der Menüleiste – also Ausrichtung, Größe und Farben. Er ist Teil des ersten Elements im `menu`-Array:
```javascript
menu: [{
tableId: tableId(current),
settings: {
menuBar: {
width: "",
position: "",
backgroundColor: "",
borderColor: "",
fontSize: "20px"
},
stateNormal: {
backgroundColor: "",
borderColor: "",
fontColor: ""
},
stateActive: {
backgroundColor: "",
borderColor: "",
fontColor: ""
}
}
}, {
menuItems: [...]
}]
```
### tableId
**Typ:** `text`
**Pflichtfeld:** ja
Definiert die Tabelle, auf die sich Aktionen innerhalb des Menüs beziehen. Auch wenn der `tableId`-Wert aktuell nicht direkt verarbeitet wird, ist er Teil der erwarteten Datenstruktur und sollte immer gesetzt werden.
### settings-Block
**Typ:** `object`
**Pflichtfeld:** ja
Enthält die visuellen Einstellungen für die Menüleiste und die Darstellung der Buttons – im normalen sowie im aktiven Zustand.
Der `settings`-Block besteht aus drei Unterobjekten:
- `menuBar` → Layout & Ausrichtung der Leiste
- `stateNormal` → Design nicht aktiver Buttons
- `stateActive` → Design aktiver Buttons
💡 **Tipp: **Wenn du Werte leer lässt, greifen automatisch sinnvolle Standardwerte – so kannst du das Menü auch minimal konfigurieren und es sieht trotzdem gut aus.
```javascript
settings: {
menuBar: {
width: "", // Pixel-Werte o. Prozent-Werte in "
position: "", // left, center, right
backgroundColor: "", // HEX-Wert in "
borderColor: "", // HEX-Wert in "
fontSize: "100px" // Pixel-Wert in "
},
stateNormal: {
backgroundColor: "", // HEX-Wert in " | definiert die Hintergrundfarbe deines Buttons im unangeklickten Modus.
borderColor: "", // HEX-Wert in " | definiert die Rahmengrundfarbe deines Buttons im unangeklickten Modus.
fontColor: "" // HEX-Wert in " | definiert die Schriftfarbe deines Buttons im unangeklickten Modus.
},
stateActive: {
backgroundColor: "", // HEX-Wert in " | definiert die Hintergrundfarbe deines Buttons im angeklickten Modus.
borderColor: "", // HEX-Wert in " | definiert die Rahmengrundfarbe deines Buttons im angeklickten Modus.
fontColor: "" // HEX-Wert in " | definiert die Schriftfarbe deines Buttons im angeklickten Modus.
}
}
}
```
## menuItems[]
Der zweite Teil des `menu`-Arrays enthält die eigentlichen Menüeinträge. Jeder Menüpunkt wird als Objekt in der Liste `menuItems` definiert. Ein Menüeintrag besteht in der Regel aus einem Titel, einem Icon, einem aktiven Zustand und einer oder mehreren auszuführenden Aktionen.
```javascript
menuItems: [{
item: 1,
field: "menuText",
title: "Übersicht",
activeState: if menuText = text("U") then "active" else " end,
iconName: "info",
actions: [{
recordId: Nr,
type: "update",
field: "B",
value: "U"
}]
}
```
### item
Dieser Wert ist eine laufende Nummer, die intern zur Sortierung oder Identifikation der Menüeinträge verwendet wird.
**Typ:** `number`
**Pflichtfeld:** ja
```javascript
item: 1, // Zahlenwert. Beschrifte hier deine Menüpunkte einfach nach Anzahl.
```
### title
Hier legst du den Text fest, der im Button angezeigt wird. Der Titel ist für die Nutzer sichtbar und sollte die Funktion des Buttons klar benennen.
**Typ:** `text`
**Pflichtfeld:** ja
```javascript
title: "Übersicht",
```
***activeState*** definiert, wann dein Menüpunkt aktiv sein soll. In diesem Beispiel: Wenn der Text "A" in dem Textfeld menuText steht, dann soll der Button aktiv sein.
```javascript
activeState: if menuText = text("A") then "active" else " end,
```
### icon
Mit dem `icon`-Feld kannst du ein [Icon](https://www.arc-rider.de/documentation/custom-icon) zu deinem Button hinzufügen. Die Icons werden typischerweise über `arcCustomIcon({ name: "..." })` definiert. Wenn kein Icon angegeben wird, besteht der Button nur aus Text.
**Typ:** `function`
**Pflichtfeld:** nein
```javascript
icon: "", // Kein Icon wird angezeigt
icon: arcCustomIcon({
name: "kanban" }), // Benutze das Widget arcCiustomIcon()
```
### active
Das Feld `active` bestimmt, ob ein Menüpunkt gerade als aktiv markiert ist. Meist handelt es sich dabei um einen Ausdruck, der den aktuellen Zustand vergleicht – z. B. `Menu = "A"` oder `Menu=1`. Aktive Menüpunkte werden visuell hervorgehoben (z. B. mit einer anderen Hintergrundfarbe) und helfen den Nutzern zu erkennen, welcher Bereich gerade ausgewählt ist.
**Typ:** `boolean` oder Ausdruck
**Pflichtfeld:** ja
## actions
In `actions` legst du fest, was beim Klick auf den Button passieren soll. Du kannst hier eine oder mehrere Aktionen definieren. Jeder Aktionseintrag ist ein Objekt mit einem `type` und ggf. zusätzlichen Parametern wie `recordId`, `field` oder `value`.
**Typ:** `array`
**Pflichtfeld:** ja
💡 **Hinweis: **Jede Aktion wird in der Reihenfolge ausgeführt, in der sie im Array steht. Du kannst mehrere Aktionen kombinieren – z. B. zuerst einen Feldwert setzen und danach ein Popup öffnen.
### Mögliche Aktionen
`type`
Beschreibung
Aufbau Code
`update`
Setzt den Wert eines Feldes im angegebenen Datensatz
`recordId`, `field`, `value`
`popup`
Öffnet den angegebenen Datensatz als Popup
`recordId`
`delete`
Löscht den angegebenen Datensatz aus der Datenbank
`recordId`
### Aktion: update
```javascript
actions: [{
recordId: Nr,
type: "update", // update aktualisiert/manipuliert ein Feld.
field: "B", // Feld Id des zu manipulierenden Feldes.
value: "A" // Wert, der in das Feld geschrieben werden soll. In dem Beispiel: wird "A" in ein Textfeld geschrieben.
}]
```
### Aktion: popup
```javascript
actions: [{
recordId: Nr,
type: "popup", // popup öffnet den Record
}]
```
### Aktion: delete
```javascript
actions: [{
recordId: Nr,
type: "delete", // delete löscht den Record
}]
```
## Fazit ✅
Mit `arcCustomMenu` kannst du flexible Menüleisten in deiner Ninox-Oberfläche erstellen – ideal zum Umschalten von Ansichten, Setzen von Feldwerten oder Öffnen von Popups.
Das Widget lässt sich vollständig an dein Design anpassen: von Farben und Schriften bis hin zu Hover- und Aktiv-Zuständen.
Let’s build smarter interfaces – with arcWidgets.
Fragen oder Feedback? → [office@arc-rider.com](mailto:office@arc-rider.com)
---
# Custom NumPad
Source: https://www.arc-rider.com/docs/widgets/custom-numpad
# Numpad in React
Zahlen per Bildschirmtastatur erfassen, etwa Mengen oder Beträge. Das Ergebnis bleibt zunächst ein formatierter String.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetNumpad } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [value, setValue] = useState('0');
return (
<>
);
}
```
## Features ausprobieren
### Dezimalstellen, Suffix und Tastatureingabe
Teste Ganzzahlen und Dezimalwerte. Tastaturereignisse gelten nur innerhalb der geöffneten Live-Vorschau; Enter übernimmt den Wert.
```tsx
import { useState } from 'react';
import { ArcWidgetNumpad } from '@arcrider/arcwidgets-react';
export default function Example() {
const [value, setValue] = useState('12.5');
const [decimals, setDecimals] = useState(2);
const [keyboard, setKeyboard] = useState(false);
return (
<>
Übernommen: {value} Stk
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetNumpadData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onSubmit
Bestätigter Eingabestring.
```typescript
onSubmit?: (value: string) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### currentValue
Aktueller Anzeigewert.
Typ: `string | number`.
### actionTitle
Beschriftung der Bestätigung.
Typ: `string`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### fontColor
Schriftfarbe.
Typ: `string`.
### display
Darstellung der Zahlenanzeige.
Typ: `ArcWidgetNumpadDisplay`.
### suffix
Inhalt nach der Beschriftung oder Einheit.
Typ: `string`.
### clearOnFirstInput
Ersetzt den bisherigen Wert bei der ersten Eingabe.
Typ: `boolean`.
### decimalSeparator
Dezimaltrennzeichen des Eingabestrings.
Typ: `string`.
### maxDecimals
Maximale Anzahl Nachkommastellen.
Typ: `number`.
### keyboard
Bedienung über die physische Tastatur.
Typ: `boolean | ArcWidgetNumpadKeyboard`.
## Verhalten und Grenzen
- `onSubmit` liefert einen String, etwa `"12,50"`. Normalisiere das konfigurierte Dezimaltrennzeichen vor einer numerischen Berechnung und prüfe das Ergebnis.
- `currentValue` befüllt die Anzeige. `clearOnFirstInput` ist hilfreich beim Überschreiben eines vorhandenen Werts.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetNumpadDisplay {
fontColor?: string;
height?: string;
}
export interface ArcWidgetNumpadKeyboard {
enabled?: boolean;
submitOnEnter?: boolean;
}
export interface ArcWidgetNumpadData extends Omit {
currentValue?: string | number;
actionTitle?: string;
backgroundColor?: string;
fontColor?: string;
display?: ArcWidgetNumpadDisplay;
suffix?: string;
clearOnFirstInput?: boolean;
decimalSeparator?: string;
maxDecimals?: number;
keyboard?: boolean | ArcWidgetNumpadKeyboard;
}
export interface ArcWidgetNumpadProps extends ArcReactWidgetProps {
onSubmit?: (value: string) => void;
}
```
## Einsatzbeispiele
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom NumPad
## AI Defaults (read first)
- **uniqueId**: Required, `"numpad-" + Nr`.
- **embedded**: Default `false`, set `true` when nested in a layout.
- **currentValue**: Initial display value (string or number).
- **actions**: Required for submit — use `##numpadValue##` placeholder (numeric, dot decimal) like `##inputValue##` on Input.
- **confirm / dataBag**: Standard action types — no Numpad-specific API; nest `confirm` or `dataBag` inside `actions`.
- **keyboard**: Opt-in (`true` or `{ enabled: true, submitOnEnter: true }`) — physical keyboard when no other field is focused.
- **fontColor**: Text color on digit and submit buttons (default `#ffffff`). Display uses `display.fontColor`.
- **Optimized for iPad**: Primary use case is tablet input without keyboard popup.
# Custom NumPad
Mit dem Numpad kannst du deine Oberflächen noch besser gestalten. Besonders für iPads optimiert, bietet das Numpad eine nahtlose Möglichkeit, Zahlen direkt einzugeben – ganz ohne störend aufspringende Tastatur. Der Submit-Button (oder Enter bei aktivierter Tastatur) feuert das zentrale **Actions-System** — inklusive `confirm`, `dataBag` und beliebiger Action-Ketten.
**Abgrenzung:** Für ein **Zahlenfeld mit kleinem Popup-Numpad** (analog Datepicker) nutze `arcCustomInput` mit `type: "number"` und `numpad` / `numberFormat` — siehe [Input](/documentation/input). Dieses Widget hier ist das **eigenständige** Inline-/Fullscreen-Numpad.
## Anwendungscode
```javascript
arcCustomNumPad({
uniqueId: "numpad-" + Nr,
embedded: false,
currentValue: text(Menge),
actionTitle: "Speichern",
backgroundColor: "#007bff",
fontColor: "#ffffff",
display: {
fontColor: "#121B2B",
height: "30%"
},
suffix: "€",
clearOnFirstInput: true,
decimalSeparator: ",",
maxDecimals: 2,
keyboard: true,
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "Menge"),
value: "##numpadValue##"
}]
})
```
## Allgemeine Settings
### uniqueId
Die `uniqueId` vergibst du individuell und sollte einzigartig sein. Wenn du mehrere Numpads mit unterschiedlichen Settings auf deiner Oberfläche erstellst, überschreiben sich die Styles nicht.
```javascript
uniqueId: "numpad-" + Nr,
```
### embedded
Steuert, ob das Widget standalone oder in einem Layout eingebettet ist.
```javascript
embedded: false,
embedded: true,
```
### currentValue
Anfangswert in der Anzeige — z. B. der aktuelle Feldwert oder leer.
```javascript
currentValue: text(Menge),
currentValue: "",
```
### actionTitle
Text auf dem Submit-Button unterhalb des Ziffernfelds. Default: `"Submit"`.
```javascript
actionTitle: "Speichern",
```
### backgroundColor
Hintergrundfarbe der Ziffern- und Submit-Buttons. Default: `#007bff`. Beim Drücken (Maus oder Tastatur) wird automatisch eine **leicht hellere** Variante derselben Farbe angezeigt.
```javascript
backgroundColor: "#007bff",
```
### fontColor
Schriftfarbe auf den Ziffern- und Submit-Buttons. Default: `#ffffff`.
```javascript
fontColor: "#ffffff",
fontColor: "#121B2B",
```
### display
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `fontColor` | text | Schriftfarbe der Anzeige |
| `height` | text | Max. Höhe der Anzeige (CSS, z. B. `"30%"`) |
```javascript
display: {
fontColor: "#121B2B",
height: "30%"
},
```
### suffix
Optionales Suffix neben dem Wert (z. B. Währung oder Einheit).
```javascript
suffix: "€",
```
### clearOnFirstInput
Wenn `true`, wird bei der **ersten** Zifferneingabe ein vorbelegter `currentValue` gelöscht und ersetzt — statt angehängt.
```javascript
clearOnFirstInput: true,
```
### decimalSeparator
Anzeige-Trennzeichen für Dezimalstellen. Default: `","`. Der Platzhalter `##numpadValue##` wird immer als Punkt-Dezimalzahl aufgelöst (Ninox-kompatibel).
```javascript
decimalSeparator: ",",
decimalSeparator: ".",
```
### maxDecimals
Optionale Begrenzung der Nachkommastellen nach dem Dezimaltrennzeichen.
```javascript
maxDecimals: 2,
```
## actions
Submit feuert `actions` mit aufgelöstem `##numpadValue##` — analog zu `##inputValue##` bei `arcCustomInput`.
```javascript
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "Menge"),
value: "##numpadValue##"
}]
```
Mehrere Actions werden nacheinander ausgeführt.
### confirm
Bestätigungsdialog vor dem Speichern — kein Numpad-spezifischer Code nötig:
```javascript
actions: [{
type: "confirm",
title: "Wert übernehmen?",
message: "##numpadValue## speichern?",
confirmLabel: "Speichern",
cancelLabel: "Abbrechen",
actions: [{
type: "update",
recordId: Nr,
fieldId: fieldId(Nr, "Menge"),
value: "##numpadValue##"
}]
}]
```
### dataBag
Partielle JSON-State-Updates — siehe [`data-bag-actions`](../patterns/data-bag-actions.md):
```javascript
let stateField := fieldId(Nr, "helper_mainContentState");
actions: [{
type: "update",
recordId: Nr,
fieldId: stateField,
dataBag: {
base: helper_mainContentState,
patch: { lastAmount: "##numpadValue##" }
}
}]
```
## keyboard
Physische Tastatur-Eingabe (opt-in). Default: `false`.
```javascript
keyboard: true,
```
```javascript
keyboard: {
enabled: true,
submitOnEnter: true
},
```
| Taste | Wirkung |
|-------|---------|
| `0`–`9` | Ziffer anhängen |
| `,` oder `.` | Dezimaltrennzeichen (einmal) |
| `Backspace` | Letzte Ziffer löschen (⌫-Button) |
| `Delete` / `Escape` | Alles löschen (`C`) |
| `Enter` | Submit (`actions` feuern) |
**Verhalten bei mehreren Numpads:** Der zuletzt geladene oder angeklickte Numpad ist aktiv.
**Sicherheitsnetz:** Solange der Fokus in einem anderen Eingabefeld liegt (`input`, `textarea`, `arcCustomInput`, `arcCustomSelect`, …), greift der Numpad **nicht** auf Tastendrücke zu.
## Ziffernfeld
Layout (3 Spalten):
```
1 2 3
4 5 6
7 8 9
C ⌫ 0
, (Dezimal, volle Breite)
```
- **C** — Wert auf `0` zurücksetzen
- **⌫** — letzte Ziffer entfernen
- **Dezimal** — einmaliges Dezimaltrennzeichen (Label = `decimalSeparator`)
---
# Custom Slider
Source: https://www.arc-rider.com/docs/widgets/custom-slider
# Slider in React
Einen Zahlenwert innerhalb eines festen Bereichs verändern, etwa eine Auslastung oder Zielvorgabe.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import {
ArcWidgetProgressBar,
ArcWidgetSlider,
} from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [value, setValue] = useState(42);
return (
<>
);
}
```
## Features ausprobieren
### Schrittweite und gemeinsamer State
Der Slider steuert den Fortschrittsbalken über denselben State. Ändere die Schrittweite und verschiebe den Regler.
```tsx
import { useState } from 'react';
import {
ArcWidgetSlider,
ArcWidgetProgressBar,
} from '@arcrider/arcwidgets-react';
export default function Example() {
const [value, setValue] = useState(40);
const [step, setStep] = useState(5);
return (
<>
Übernommener Wert: {value}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetSliderData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onChange
Übernimmt den neuen Eingabewert in deinen State.
```typescript
onChange?: (value: number) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### value
Anzuzeigender bzw. aktuell bearbeiteter Wert.
Typ: `number`.
### min
Kleinster Wert.
Typ: `number`.
### max
Größter Wert.
Typ: `number`.
### step
Schrittweite.
Typ: `number`.
### width
Breite des Widgets als Größenangabe.
Typ: `string`.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### track
Darstellung der gesamten Schiene.
Typ: `ArcWidgetSliderTrackStyle`.
### fill
Darstellung des gefüllten Bereichs.
Typ: `ArcWidgetSliderFillStyle`.
### thumb
Darstellung des Reglers.
Typ: `ArcWidgetSliderThumbStyle`.
### valueDisplay
Anzeige und Formatierung des Werts.
Typ: `ArcWidgetSliderValueDisplay`.
### statusDisplay
Beschriftungen für Wertebereiche.
Typ: `ArcWidgetSliderStatusDisplay[]`.
## Verhalten und Grenzen
- `onChange` liefert eine Zahl. Übernimm sie in deinen State und gib sie als `data.value` zurück.
- Setze sinnvolle `min`, `max` und `step`. Änderungen im Widget speichern noch keine Daten.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetSliderTrackStyle {
height?: string;
backgroundColor?: string;
borderRadius?: string;
[key: string]: unknown;
}
export interface ArcWidgetSliderFillStyle {
backgroundColor?: string;
[key: string]: unknown;
}
export interface ArcWidgetSliderThumbStyle {
width?: string;
height?: string;
backgroundColor?: string;
borderColor?: string;
borderWidth?: string;
borderRadius?: string;
[key: string]: unknown;
}
export interface ArcWidgetSliderValueDisplay {
show?: boolean;
color?: string;
fontSize?: string;
[key: string]: unknown;
}
export interface ArcWidgetSliderStatusDisplay {
label?: string;
value?: number;
color?: string;
track?: ArcWidgetSliderTrackStyle;
fill?: ArcWidgetSliderFillStyle;
thumb?: ArcWidgetSliderThumbStyle;
[key: string]: unknown;
}
export interface ArcWidgetSliderData extends ArcWidgetBaseData {
value?: number;
min?: number;
max?: number;
step?: number;
width?: string;
height?: string;
track?: ArcWidgetSliderTrackStyle;
fill?: ArcWidgetSliderFillStyle;
thumb?: ArcWidgetSliderThumbStyle;
valueDisplay?: ArcWidgetSliderValueDisplay;
statusDisplay?: ArcWidgetSliderStatusDisplay[];
}
export interface ArcWidgetSliderProps extends ArcReactWidgetProps {
onChange?: (value: number) => void;
}
```
## Einsatzbeispiele
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Slider
## AI Defaults (read first)
- **Function name**: `arcCustomSlider`.
- **Purpose**: Ein Wertregler (0–100 oder eigener Bereich) zum Ziehen per Maus/Touch – **kein** Bild-/Content-Slideshow-Widget. Für Bildergalerien: [`arcCustomSlideshow`](/documentation/custom-slideshow).
- **recordId + fieldId**: Nur nötig, wenn der Wert automatisch gespeichert werden soll. Ohne beide Felder wird beim Loslassen **nicht** persistiert.
- **Persistence**: Speichern läuft über **Action Performer** (`type: "update"` mit `recordId` / `field` / `value`). React: `onAction` — kein globales `database`.
- **value / min / max / step**: Default `0` / `0` / `100` / `1`.
- **valueDisplay.show**: Default `true` (Zahlenwert wird angezeigt). `false` blendet die Zahl aus.
- **statusDisplay**: Optionales Array für Icons + dynamische Einfärbung je Schwellenwert (z. B. 🔥 ab 80). Leeres Array oder weglassen = keine Icons.
# Custom Slider
Mit `arcCustomSlider` baust du einen interaktiven Wertregler in Ninox – auf Basis von reinem JavaScript, nicht dem nativen HTML-Range-Input. Der Nutzer zieht den Regler-Knopf (Thumb) per Maus oder Touch, oder klickt direkt auf die Leiste (Track), um den Wert zu setzen.
**Das kannst du steuern:**
- Wertebereich (`min`, `max`, `step`)
- Aussehen von Track, Fill (gefüllter Bereich) und Thumb
- Anzeige des aktuellen Zahlenwerts (ein-/ausblenden)
- Dynamische Icons + Einfärbung je Schwellenwert (z. B. Status-Ampel)
- Automatisches Speichern in ein Ninox-Feld beim Loslassen
## Anwendungscode
```javascript
arcCustomSlider({
value: current.Fortschritt,
min: 0,
max: 100,
step: 1,
width: "300px",
height: "50px",
recordId: current.Nr,
fieldId: fieldId("Aufgaben", "Fortschritt"),
track: {
height: "6px",
borderRadius: "3px",
backgroundColor: "#E9ECF4"
},
fill: {
backgroundColor: "#4970ff"
},
thumb: {
width: "20px",
height: "20px",
backgroundColor: "#ffffff",
borderColor: "#ccc",
borderWidth: "2px",
borderRadius: "50%"
},
valueDisplay: {
show: true,
color: "#515971",
fontSize: "14px"
},
statusDisplay: [{
label: "🔥",
value: 80,
color: "#ff4444"
}, {
label: "✓",
value: 50,
color: "#4CAF50"
}, {
label: "⚠",
value: 20,
color: "#ff9800"
}]
})
```
## Parameter
### value / min / max / step
**Typ:** `number`
**Default:** `0` / `0` / `100` / `1`
Aktueller Wert, Wertebereich und Schrittweite. `value` wird beim Laden einmalig gesetzt – Ninox-Feldbindung übernimmst du selbst (z. B. `value: current.Fortschritt`).
```javascript
value: 50,
min: 0,
max: 100,
step: 1,
```
### width / height
**Typ:** `text`
Größe des gesamten Slider-Containers.
```javascript
width: "300px", // oder "100%"
height: "50px",
```
### recordId / fieldId
**Typ:** `text`
**Optional, aber beide zusammen nötig zum automatischen Speichern**
Beim Loslassen des Reglers (`mouseup`/`touchend`) wird – **nur wenn beide gesetzt sind** – eine Action-Performer-Action `{ type: "update", recordId, field: fieldId, value }` ausgelöst (Ninox mappt das auf `database.update`; React über `onAction`).
```javascript
recordId: current.Nr,
fieldId: fieldId("Aufgaben", "Fortschritt"),
```
💡 **Hinweis:** Fehlt eines der beiden Felder, wird **nicht** persistiert – der Wert geht sonst **nicht** verloren im UI.
### Block: track{}
**Typ:** `object`
**Optional**
Styling der Regler-Leiste (Hintergrund der gesamten Spur).
Feld
Beschreibung
`height`
Höhe des Tracks, z. B. `"6px"`
`backgroundColor`
Farbe des Tracks, z. B. `"#E9ECF4"`
`borderRadius`
Border-Radius des Tracks, z. B. `"3px"`
### Block: fill{}
**Typ:** `object`
**Optional**
Styling des **gefüllten** Bereichs zwischen Start und aktuellem Wert.
```javascript
fill: {
backgroundColor: "#4970ff"
}
```
### Block: thumb{}
**Typ:** `object`
**Optional**
Styling des Regler-Knopfs.
Feld
Beschreibung
`width` / `height`
Größe des Knopfs, z. B. `"20px"`
`backgroundColor`
Füllfarbe des Knopfs
`borderColor` / `borderWidth` / `borderRadius`
Rahmen des Knopfs, z. B. `borderRadius: "50%"` für rund
### Block: valueDisplay{}
**Typ:** `object`
**Default:** `{ show: true }`
Steuert die Anzeige des aktuellen Zahlenwerts neben/unter dem Regler.
```javascript
valueDisplay: {
show: true, // false blendet die Zahl komplett aus
color: "#515971",
fontSize: "14px"
}
```
### statusDisplay
**Typ:** `array of objects`
**Optional**
Zeigt ein Icon/Symbol an, sobald der aktuelle Wert einen Schwellenwert erreicht – zusätzlich kann jeder Status Track/Fill/Thumb umfärben. Die Einträge werden intern nach `value` absteigend sortiert; der **höchste erreichte** Schwellenwert gewinnt.
Feld
Beschreibung
`label`
Icon oder Text, z. B. `"🔥"`, `"✓"`, `"⚠"`, `"✕"`
`value`
Schwellenwert – ab diesem Wert wird der Status aktiv
`color`
Farbe des Icon-Texts
`track` / `fill` / `thumb`
Optional: gleiche Struktur wie oben, überschreibt das Standard-Styling für diesen Status (mit `!important`)
```javascript
statusDisplay: [{
label: "🔥",
value: 80,
color: "#ff4444",
fill: { backgroundColor: "#ff4444" }
}, {
label: "✓",
value: 50,
color: "#4CAF50"
}]
```
💡 **Tipp:** Leeres Array (`statusDisplay: []`) oder Weglassen = keine Icons, nur der reine Regler mit Zahlenwert.
## Verwandtes Widget
Für Bildergalerien, Content-Karussells oder mehrseitige Text-Slides mit Swipe-Geste verwendest du stattdessen [`arcCustomSlideshow`](/documentation/custom-slideshow) – trotz ähnlichem Namen ein komplett anderes Widget.
---
# Custom Slideshow
Source: https://www.arc-rider.com/docs/widgets/custom-slideshow
# Slideshow in React
Text oder eigenes HTML als Folge von Slides anzeigen. Geeignet für einfache Bildgalerien oder wechselnde Hinweise.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetSlideshow } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const demoItems = [
{
value: `
01 · ${t('Entdecken', 'Discover', 'Descubrir')}
${t('Anforderungen und Ziele sammeln.', 'Collect requirements and goals.', 'Reúne requisitos y objetivos.')}
`,
backgroundColor: '#ecfdf5',
},
{
value: `
02 · ${t('Gestalten', 'Design', 'Diseñar')}
${t('Ansichten mit Widgets zusammensetzen.', 'Compose views with widgets.', 'Monta vistas con widgets.')}
`,
backgroundColor: '#fffbeb',
},
{
value: `
03 · ${t('Verbinden', 'Connect', 'Conectar')}
${t('State und Callbacks an eure API hängen.', 'Wire state and callbacks to your API.', 'Conecta estado y callbacks a tu API.')}
);
}
```
## Features ausprobieren
### Schritte anklicken und Fortschritt übernehmen
Die Schritte und der Weiter-Button verändern denselben aktiven Schritt. Alle bereits erreichten Schritte erhalten eine eigene Farbe.
```tsx
import { useState } from 'react';
import { ArcWidgetSteps, ArcWidgetButton } from '@arcrider/arcwidgets-react';
export default function Example() {
const [step, setStep] = useState(0);
const labels = ['Anfrage', 'Planung', 'Umsetzung', 'Abnahme'];
return (
<>
({
title,
value: String(i + 1),
clickable: true,
backgroundColor: i <= step ? '#18181b' : '#e4e4e7',
fontColor: i <= step ? '#ffffff' : '#52525b',
})),
}}
onClick={(_event, index) => setStep(index)}
/>
setStep((s) => (s + 1) % 4)}
/>
Aktuell: {labels[step]}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetStepsData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onClick
Meldet den Klick. Beachte die widgetspezifischen Argumente unten.
```typescript
onClick?: (event: unknown, stepIndex: number) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### settings
Gemeinsame Darstellung der Einträge.
Typ: `ArcWidgetStepsSettings`.
### steps
Schritte mit Titel, Status und optionaler Klickbarkeit.
Typ: `ArcWidgetStepsStep[]`.
## Verhalten und Grenzen
- Leite Beschriftung und Farben jedes Schritts aus deinem State ab; klickbare Schritte brauchen `clickable: true`.
- `onClick(event, stepIndex)` meldet den angeklickten Schritt. Prüfe vor dem Wechsel die Eingaben des aktuellen Schritts.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetStepsSettings {
embedded?: boolean;
height?: string;
colorLabel?: string;
fontSizeLabel?: string;
colorValue?: string;
fontSizeValue?: string;
backgroundColor?: string;
borderColor?: string;
alignX?: 'left' | 'center' | 'right' | string;
stepWidth?: string;
gapY?: string;
stepRadius?: string;
connectionLine?: {
show?: boolean;
height?: string;
};
[key: string]: unknown;
}
export interface ArcWidgetStepsStep {
title?: string;
value?: string;
subtitle?: string;
colorLabel?: string;
fontSizeLabel?: string;
colorValue?: string;
fontSizeValue?: string;
backgroundColor?: string;
width?: string;
clickable?: boolean;
}
export interface ArcWidgetStepsData extends Omit {
settings?: ArcWidgetStepsSettings;
steps?: ArcWidgetStepsStep[];
}
export interface ArcWidgetStepsProps extends ArcReactWidgetProps {
onClick?: (event: unknown, stepIndex: number) => void;
}
```
## Einsatzbeispiele
- [Status auswählen und speichern](/docs/react/examples/status-als-buttons-ausgeben)
- [Ein Formular in Schritten](/docs/react/examples/datenaufnahme-in-schritten)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Steps
## AI Defaults (read first)
- **uniqueId**: Required, `"steps-" + Nr`.
- **steps**: Array of `{ title: "...", value: "..." }` objects.
- **height**: `"100%"` when embedded. Fixed height (e.g. `"80px"`) when standalone.
- **embedded**: Lives inside `settings: { embedded: true }`, NOT at root level.
- **Klick (Ninox):** `actions: [...]` auf dem Step — der Adapter setzt intern `clickable: true`. `type: "update"` mit `recordId: Nr`, `field: fieldId(Nr, "Feldname")`.
- **Klick (React):** `clickable: true` auf dem Step; `onClick(event, stepIndex)` am Host (`stepIndex` = 0-basierter Index in `steps`) — **kein** `actions` in `data`.
- **stepWidth**: Default `"80px"`, set wider for longer labels.
- **connectionLine**: `{ show: true, height: "3px" }` for visual step connections.
# Visualisiere Fortschritte oder Status – mit Stil.
Mit dem `arcCustomSteps`-Widget kannst du mehrstufige Prozesse, Status- oder Fortschrittsanzeigen direkt in deinem Ninox-Interface umsetzen – klar strukturiert, visuell ansprechend und vollständig anpassbar. Ob Projektphasen, Prozessstatus oder Ampelsysteme: Die Steps lassen sich flexibel in Breite, Farben, Abständen und Aktionen konfigurieren.
Die einzelnen Schritte können dynamisch aus deinen Datensätzen aufgebaut und optional mit Aktionen (z. B. `update`, `delete`, `popup`) versehen werden. So entsteht eine interaktive Fortschrittsanzeige, die nicht nur informiert, sondern auch steuert.
In dieser Dokumentation zeigen wir dir:
- wie das Widget aufgebaut ist,
- welche Parameter du anpassen kannst,
- und wie du es Schritt für Schritt in dein System integrierst.
👉 **Scroll weiter für Beispielcode, Parameterübersicht und Anwendungstipps.**
## Anwendungscode
```javascript
let current := this;
let list := (select 'Auftrag Steps');
let data := {
uniqueId: "Auftragsphase",
settings: {
embedded: true,
height: "150px",
fontSizeLabel: "10px",
fontSizeValue: "20px",
colorValue: "",
colorLabel: "#ffffff",
borderColor: "transparent",
backgroundColor: "transparent",
alignX: "center",
stepWidth: "80px",
gapY: "10px",
stepRadius: "8px",
connectionLine: {
show: true,
height: "3px"
}
},
steps: list.[{
title: title,
value: value,
subtitle: "Test",
colorValue: "",
backgroundColor: "",
actions: [{
recordId: current.Nr,
type: "update",
field: "",
value: number(Nr)
}]
}]
};
arcCustomSteps(data)
```
## Parameter
Das Widget erhält ein Objekt mit folgenden Hauptbestandteilen:
- `uniqueId` – eine eindeutige Kennung für das Widget
- `settings` – allgemeine Darstellungseinstellungen für alle Steps
- `steps[]` – eine Liste von Einzelschritten mit optionalen Detailwerten
Die Werte aus `settings` gelten für alle Steps, können aber pro Step gezielt überschrieben werden (z. B. Farbe oder Breite).
## Settings-Block
### embedded
Typ: `boolean`
Default: `false`
Legt fest, ob das Widget in ein bestehendes Layout eingebettet wird.
- Bei `true` wird auf äußere Rahmen, Hintergrundfarben und Standard-Abstände verzichtet.
- Ideal, wenn das Widget in einem größeren Komponenten-Container liegt, der selbst das Layout steuert.
💡 **Tipp: **Wenn du `embedded: true` setzt, musst du sicherstellen, dass das umgebende Element eine passende Höhe und ggf. ein eigenes Layout mitbringt. Das Widget passt sich dann vollständig diesem Rahmen an.
### height
**Typ:** `text`
**Default:** `"100%"`
Definiert die Höhe des gesamten Steps-Widgets. Akzeptiert klassische CSS-Werte wie `"150px"`, `"auto"` oder `"100%"`.
```javascript
height: "150px",
height: "",
```
💡 **Tipp: **Wenn du das Widget **nicht eingebettet** nutzt (`embedded: false`), solltest du eine feste Höhe setzen – insbesondere bei schmalen Step-Breiten, damit Layout und Scrollverhalten konsistent bleiben.
### fontsizeLabel
**Typ:** `text`
**Default:** `"13px"`
Bestimmt die Schriftgröße für `title` und `subtitle` innerhalb eines Steps. Dieser Wert wirkt sowohl auf die obere (`title`) als auch untere (`subtitle`) Beschriftung jedes Steps – sofern kein eigener Wert direkt im Step gesetzt ist.
```javascript
fontSizeLabel: "10px", // Pixel-Werte
```
💡 **Tipp: **Für kompakte Layouts empfiehlt sich eine kleinere Schriftgröße wie `"10px"` oder `"11px"` – besonders bei vielen Steps mit schmaler Breite.
### fontsizeValue
**Typ:** `text`
**Default:** `"35px"`
Gibt die Schriftgröße für den zentralen Wert (`value`) eines Steps an – also die Zahl oder Kennung im Kreis. Dieser Wert beeinflusst die Lesbarkeit und visuelle Gewichtung des zentralen Inhalts. Wird häufig für Statuszahlen, Zähler oder Phasen verwendet.
```javascript
fontSizeValue: "20px", // Pixel-Werte
```
💡 **Tipp: **Kleinere Werte wie `"20px"` eignen sich für sehr kompakte Steps, größere Größen wirken besonders bei wenigen, breit angelegten Schritten.
### colorValue
**Typ:** `text`
**Default:** `"#3E6FFF"`
Legt die Textfarbe des zentralen `value`-Elements im Step-Kreis fest. Die Farbe bezieht sich ausschließlich auf den Text (z. B. Zahl, Status oder Kennung) – nicht auf den Hintergrund des Kreises.
```javascript
colorValue: "#ddd", // HEX-Werte
```
💡 **Tipp: **Die Lesbarkeit hängt stark vom Hintergrund ab. Achte auf ausreichend Kontrast zur `backgroundColor`.
### colorLabel
**Typ:** `text`
**Default:** `"#566eb1"`
Definiert die Textfarbe für `title` und `subtitle` innerhalb eines Steps. Dieser Farbwert wird für die obere und untere Beschriftung verwendet – solange der Step selbst keine abweichende Farbe angibt.
```javascript
colorLabel: "#ffffff", // HEX-Werte
```
💡 **Tipp: **Verwende helle Schriftfarben wie `#ffffff` nur bei dunklem Hintergrund – ansonsten leidet die Lesbarkeit.
### borderColor
**Typ:** `text`
**Default:** `"#e5e5e5"`
Definiert die Farbe der Trennlinien zwischen den Steps. Diese Farbe wird als rechte Rahmenlinie jedes Steps gesetzt (außer beim letzten Step). Sie hilft, die Schritte visuell voneinander abzugrenzen.
💡 **Tipp: **Wenn du eine besonders reduzierte oder fließende Darstellung möchtest, setze `borderColor: "transparent"` – so verschwinden die Trennlinien vollständig.
### backgroundColor
**Typ:** `text`
**Default:** `"#f7f8fc"`
Bestimmt die Hintergrundfarbe der Step-Kreise **und** der Verbindungslinien. Diese Farbe wird auf die mittleren Kreise (`value`) sowie die Linien zwischen den Steps angewendet – nicht jedoch auf den äußeren Hintergrund des gesamten Widgets (dieser ist meist transparent oder durch Container geregelt).
```javascript
backgroundColor: "transparent", // Transparenter Hintergrund
backgroundColor: "#ededed", // HEX-Werte
```
💡 **Tipp: **Ein heller Hintergrund sorgt für einen klaren, modernen Look. Für Spezialeffekte kannst du auch `"transparent"` oder leicht getönte Farben einsetzen.
### alignX
**Typ:** `text`
**Werte:** `"left"`, `"center"` (default), `"right"`
Steuert die horizontale Ausrichtung der Steps innerhalb des Widgets.
```javascript
alignX: "center", // left, center, right
algnX: "", // default: center
```
Diese Einstellung beeinflusst, **wo die Steps innerhalb der Leiste ausgerichtet werden**, insbesondere wenn weniger Steps vorhanden sind als Platz zur Verfügung steht.
- `"left"` → Steps starten ganz links
- `"center"` → Steps zentriert
- `"right"` → Steps rechtsbündig
💡 **Hinweis: **Diese Ausrichtung gilt sowohl für das gesamte Widget als auch für die Inhalte in jedem Step (z. B. Titel, Subtitle, Value).
### stepWidth
**Typ:** `text`
**Beispiel:** `"80px"`
**Default:** *(leer)*
Legt die Mindestbreite jedes Steps fest. Wird kein Wert angegeben, passen sich die Steps automatisch an die Breite ihres Inhalts oder Containers an. Die Breite betrifft sowohl den sichtbaren Bereich des Steps als auch dessen Klickfläche.
```javascript
stepWidth: "80px", // Pixel-Werte
```
💡 **Tipp: **Verwende feste Breiten bei vielen Steps mit kurzen Texten, um ein gleichmäßiges Layout zu erzielen. Bei variierenden Inhalten lieber leer lassen und auf automatische Skalierung setzen.
### gapY
**Typ:** `text`
**Beispiel:** `"10px"`
**Default:** *(leer)*
Definiert den vertikalen Abstand (`gap`) zwischen den Elementen innerhalb eines Steps – also zwischen `title`, `value` und `subtitle`. Dieser Wert wirkt innerhalb des einzelnen Steps, nicht zwischen den Steps.
```javascript
gapY: "10px", // Pixel-Werte
```
💡 **Tipp: **Mit einem kleineren Wert erzeugst du eine kompaktere Darstellung, größere Gaps wirken luftiger und lesbarer – besonders bei größeren Schriftgrößen.
### stepRadius
**Typ:** `text`
**Beispiel:** `"8px"`
**Default:** *(leer)*
Bestimmt die Abrundung des Step-Kreises (`value`) über den CSS-Wert `border-radius`. Ein hoher Wert wie `"50px"` erzeugt einen perfekt runden Kreis – niedrigere Werte führen zu weicheren Rechtecken oder Pillenformen.
```javascript
stepRadius: "8px", // Pixel-Werte
```
💡 **Tipp: **Für klassische runde Zähler-Designs setze `"50%"` oder `"999px"` – für eckigere Varianten kannst du mit Werten wie `"4px"` oder `"8px"` experimentieren.
### connectionLine Block
In der Setting-Gruppe `connectionLine` bestimmst du Parameter zu der Linie zwischen deinen Steps. Mit dem Parameter show bestimmst du, ob die Linie überhaupt sichtbar sein soll (Mögliche Werte: true / false; default: true). Mit dem Parameter height, definierst du die Pixel-Höhe der Linie (default: 3px).
```javascript
connectionLine: {
show: true, // true, false
height: "3px" // Pixel-Werte
}
```
## steps[]: Einzelne Schritte konfigurieren
Jeder Eintrag in `steps` ist ein Objekt, das einen einzelnen Step beschreibt. Neben Titel, Wert und Aktionen kannst du auch viele Designparameter direkt je Step setzen – sie überschreiben dann die allgemeinen Einstellungen aus `settings`.
```javascript
{
title: "In Bearbeitung",
value: "2",
subtitle: "laufend",
width: "90px",
colorLabel: "#ffffff",
fontSizeLabel: "11px",
colorValue: "#00cc99",
fontSizeValue: "28px",
backgroundColor: "#222",
borderColor: "transparent",
actions: [...]
}
```
Feld
Typ
Beschreibung
`title`
`text`
Titel oberhalb des Kreises
`value`
`text`/`number`
Zentrale Anzeige im Kreis
`subtitle`
`text`
Text unterhalb des Kreises
`width`
`text`
Individuelle Breite des Steps
`colorLabel`
`text`
Textfarbe für `title` und `subtitle`
`fontSizeLabel`
`text`
Schriftgröße für `title` und `subtitle`
`colorValue`
`text`
Textfarbe des zentralen Werts
`fontSizeValue`
`text`
Schriftgröße des Werts
`backgroundColor`
`text`
Hintergrundfarbe des Kreises und der Verbindungslinien
`borderColor`
`text`
Farbe der Step-Trennlinie
`actions[]`
`array`
Aktionen, die beim Klick ausgelöst werden können (siehe unten)
💡 **Tipp: **Du musst nicht alle Felder angeben. Jeder Step übernimmt automatisch die Werte aus `settings`, wenn keine eigenen Angaben gemacht werden.
## actions[]: Interaktive Schritte (Ninox)
Jeder Step kann mit einer oder mehreren Aktionen versehen werden, die beim Klick auf den `value`-Kreis ausgelöst werden. Der Ninox-Adapter setzt daraus `clickable: true` für das Widget-Core. Alle definierten Aktionstypen (`update`, `delete`, `popup` usw.) werden dabei ausgeführt — nicht nur `update` und `delete`. Aktionen werden über ein Array von Objekten definiert:
# Custom Steps
## AI Defaults (read first)
- **uniqueId**: Required, `"steps-" + Nr`.
- **steps**: Array of `{ title: "...", value: "..." }` objects.
- **height**: `"100%"` when embedded. Fixed height (e.g. `"80px"`) when standalone.
- **embedded**: Lives inside `settings: { embedded: true }`, NOT at root level.
- **Klick (Ninox):** `actions: [...]` auf dem Step — der Adapter setzt intern `clickable: true`. `type: "update"` mit `recordId: Nr`, `field: fieldId(Nr, "Feldname")`.
- **Klick (React):** `clickable: true` auf dem Step; `onClick(event, stepIndex)` am Host (`stepIndex` = 0-basierter Index in `steps`) — **kein** `actions` in `data`.
- **stepWidth**: Default `"80px"`, set wider for longer labels.
- **connectionLine**: `{ show: true, height: "3px" }` for visual step connections.
# Visualisiere Fortschritte oder Status – mit Stil.
Mit dem `arcCustomSteps`-Widget kannst du mehrstufige Prozesse, Status- oder Fortschrittsanzeigen direkt in deinem Ninox-Interface umsetzen – klar strukturiert, visuell ansprechend und vollständig anpassbar. Ob Projektphasen, Prozessstatus oder Ampelsysteme: Die Steps lassen sich flexibel in Breite, Farben, Abständen und Aktionen konfigurieren.
Die einzelnen Schritte können dynamisch aus deinen Datensätzen aufgebaut und optional mit Aktionen (z. B. `update`, `delete`, `popup`) versehen werden. So entsteht eine interaktive Fortschrittsanzeige, die nicht nur informiert, sondern auch steuert.
In dieser Dokumentation zeigen wir dir:
- wie das Widget aufgebaut ist,
- welche Parameter du anpassen kannst,
- und wie du es Schritt für Schritt in dein System integrierst.
👉 **Scroll weiter für Beispielcode, Parameterübersicht und Anwendungstipps.**
## Anwendungscode
```javascript
let current := this;
let list := (select 'Auftrag Steps');
let data := {
uniqueId: "Auftragsphase",
settings: {
embedded: true,
height: "150px",
fontSizeLabel: "10px",
fontSizeValue: "20px",
colorValue: "",
colorLabel: "#ffffff",
borderColor: "transparent",
backgroundColor: "transparent",
alignX: "center",
stepWidth: "80px",
gapY: "10px",
stepRadius: "8px",
connectionLine: {
show: true,
height: "3px"
}
},
steps: list.[{
title: title,
value: value,
subtitle: "Test",
colorValue: "",
backgroundColor: "",
actions: [{
recordId: current.Nr,
type: "update",
field: "",
value: number(Nr)
}]
}]
};
arcCustomSteps(data)
```
## Parameter
Das Widget erhält ein Objekt mit folgenden Hauptbestandteilen:
- `uniqueId` – eine eindeutige Kennung für das Widget
- `settings` – allgemeine Darstellungseinstellungen für alle Steps
- `steps[]` – eine Liste von Einzelschritten mit optionalen Detailwerten
Die Werte aus `settings` gelten für alle Steps, können aber pro Step gezielt überschrieben werden (z. B. Farbe oder Breite).
## Settings-Block
### embedded
Typ: `boolean`
Default: `false`
Legt fest, ob das Widget in ein bestehendes Layout eingebettet wird.
- Bei `true` wird auf äußere Rahmen, Hintergrundfarben und Standard-Abstände verzichtet.
- Ideal, wenn das Widget in einem größeren Komponenten-Container liegt, der selbst das Layout steuert.
💡 **Tipp: **Wenn du `embedded: true` setzt, musst du sicherstellen, dass das umgebende Element eine passende Höhe und ggf. ein eigenes Layout mitbringt. Das Widget passt sich dann vollständig diesem Rahmen an.
### height
**Typ:** `text`
**Default:** `"100%"`
Definiert die Höhe des gesamten Steps-Widgets. Akzeptiert klassische CSS-Werte wie `"150px"`, `"auto"` oder `"100%"`.
```javascript
height: "150px",
height: "",
```
💡 **Tipp: **Wenn du das Widget **nicht eingebettet** nutzt (`embedded: false`), solltest du eine feste Höhe setzen – insbesondere bei schmalen Step-Breiten, damit Layout und Scrollverhalten konsistent bleiben.
### fontsizeLabel
**Typ:** `text`
**Default:** `"13px"`
Bestimmt die Schriftgröße für `title` und `subtitle` innerhalb eines Steps. Dieser Wert wirkt sowohl auf die obere (`title`) als auch untere (`subtitle`) Beschriftung jedes Steps – sofern kein eigener Wert direkt im Step gesetzt ist.
```javascript
fontSizeLabel: "10px", // Pixel-Werte
```
💡 **Tipp: **Für kompakte Layouts empfiehlt sich eine kleinere Schriftgröße wie `"10px"` oder `"11px"` – besonders bei vielen Steps mit schmaler Breite.
### fontsizeValue
**Typ:** `text`
**Default:** `"35px"`
Gibt die Schriftgröße für den zentralen Wert (`value`) eines Steps an – also die Zahl oder Kennung im Kreis. Dieser Wert beeinflusst die Lesbarkeit und visuelle Gewichtung des zentralen Inhalts. Wird häufig für Statuszahlen, Zähler oder Phasen verwendet.
```javascript
fontSizeValue: "20px", // Pixel-Werte
```
💡 **Tipp: **Kleinere Werte wie `"20px"` eignen sich für sehr kompakte Steps, größere Größen wirken besonders bei wenigen, breit angelegten Schritten.
### colorValue
**Typ:** `text`
**Default:** `"#3E6FFF"`
Legt die Textfarbe des zentralen `value`-Elements im Step-Kreis fest. Die Farbe bezieht sich ausschließlich auf den Text (z. B. Zahl, Status oder Kennung) – nicht auf den Hintergrund des Kreises.
```javascript
colorValue: "#ddd", // HEX-Werte
```
💡 **Tipp: **Die Lesbarkeit hängt stark vom Hintergrund ab. Achte auf ausreichend Kontrast zur `backgroundColor`.
### colorLabel
**Typ:** `text`
**Default:** `"#566eb1"`
Definiert die Textfarbe für `title` und `subtitle` innerhalb eines Steps. Dieser Farbwert wird für die obere und untere Beschriftung verwendet – solange der Step selbst keine abweichende Farbe angibt.
```javascript
colorLabel: "#ffffff", // HEX-Werte
```
💡 **Tipp: **Verwende helle Schriftfarben wie `#ffffff` nur bei dunklem Hintergrund – ansonsten leidet die Lesbarkeit.
### borderColor
**Typ:** `text`
**Default:** `"#e5e5e5"`
Definiert die Farbe der Trennlinien zwischen den Steps. Diese Farbe wird als rechte Rahmenlinie jedes Steps gesetzt (außer beim letzten Step). Sie hilft, die Schritte visuell voneinander abzugrenzen.
💡 **Tipp: **Wenn du eine besonders reduzierte oder fließende Darstellung möchtest, setze `borderColor: "transparent"` – so verschwinden die Trennlinien vollständig.
### backgroundColor
**Typ:** `text`
**Default:** `"#f7f8fc"`
Bestimmt die Hintergrundfarbe der Step-Kreise **und** der Verbindungslinien. Diese Farbe wird auf die mittleren Kreise (`value`) sowie die Linien zwischen den Steps angewendet – nicht jedoch auf den äußeren Hintergrund des gesamten Widgets (dieser ist meist transparent oder durch Container geregelt).
```javascript
backgroundColor: "transparent", // Transparenter Hintergrund
backgroundColor: "#ededed", // HEX-Werte
```
💡 **Tipp: **Ein heller Hintergrund sorgt für einen klaren, modernen Look. Für Spezialeffekte kannst du auch `"transparent"` oder leicht getönte Farben einsetzen.
### alignX
**Typ:** `text`
**Werte:** `"left"`, `"center"` (default), `"right"`
Steuert die horizontale Ausrichtung der Steps innerhalb des Widgets.
```javascript
alignX: "center", // left, center, right
algnX: "", // default: center
```
Diese Einstellung beeinflusst, **wo die Steps innerhalb der Leiste ausgerichtet werden**, insbesondere wenn weniger Steps vorhanden sind als Platz zur Verfügung steht.
- `"left"` → Steps starten ganz links
- `"center"` → Steps zentriert
- `"right"` → Steps rechtsbündig
💡 **Hinweis: **Diese Ausrichtung gilt sowohl für das gesamte Widget als auch für die Inhalte in jedem Step (z. B. Titel, Subtitle, Value).
### stepWidth
**Typ:** `text`
**Beispiel:** `"80px"`
**Default:** *(leer)*
Legt die Mindestbreite jedes Steps fest. Wird kein Wert angegeben, passen sich die Steps automatisch an die Breite ihres Inhalts oder Containers an. Die Breite betrifft sowohl den sichtbaren Bereich des Steps als auch dessen Klickfläche.
```javascript
stepWidth: "80px", // Pixel-Werte
```
💡 **Tipp: **Verwende feste Breiten bei vielen Steps mit kurzen Texten, um ein gleichmäßiges Layout zu erzielen. Bei variierenden Inhalten lieber leer lassen und auf automatische Skalierung setzen.
### gapY
**Typ:** `text`
**Beispiel:** `"10px"`
**Default:** *(leer)*
Definiert den vertikalen Abstand (`gap`) zwischen den Elementen innerhalb eines Steps – also zwischen `title`, `value` und `subtitle`. Dieser Wert wirkt innerhalb des einzelnen Steps, nicht zwischen den Steps.
```javascript
gapY: "10px", // Pixel-Werte
```
💡 **Tipp: **Mit einem kleineren Wert erzeugst du eine kompaktere Darstellung, größere Gaps wirken luftiger und lesbarer – besonders bei größeren Schriftgrößen.
### stepRadius
**Typ:** `text`
**Beispiel:** `"8px"`
**Default:** *(leer)*
Bestimmt die Abrundung des Step-Kreises (`value`) über den CSS-Wert `border-radius`. Ein hoher Wert wie `"50px"` erzeugt einen perfekt runden Kreis – niedrigere Werte führen zu weicheren Rechtecken oder Pillenformen.
```javascript
stepRadius: "8px", // Pixel-Werte
```
💡 **Tipp: **Für klassische runde Zähler-Designs setze `"50%"` oder `"999px"` – für eckigere Varianten kannst du mit Werten wie `"4px"` oder `"8px"` experimentieren.
### connectionLine Block
In der Setting-Gruppe `connectionLine` bestimmst du Parameter zu der Linie zwischen deinen Steps. Mit dem Parameter show bestimmst du, ob die Linie überhaupt sichtbar sein soll (Mögliche Werte: true / false; default: true). Mit dem Parameter height, definierst du die Pixel-Höhe der Linie (default: 3px).
```javascript
connectionLine: {
show: true, // true, false
height: "3px" // Pixel-Werte
}
```
## steps[]: Einzelne Schritte konfigurieren
Jeder Eintrag in `steps` ist ein Objekt, das einen einzelnen Step beschreibt. Neben Titel, Wert und Aktionen kannst du auch viele Designparameter direkt je Step setzen – sie überschreiben dann die allgemeinen Einstellungen aus `settings`.
```javascript
{
title: "In Bearbeitung",
value: "2",
subtitle: "laufend",
width: "90px",
colorLabel: "#ffffff",
fontSizeLabel: "11px",
colorValue: "#00cc99",
fontSizeValue: "28px",
backgroundColor: "#222",
borderColor: "transparent",
actions: [...]
}
```
Feld
Typ
Beschreibung
`title`
`text`
Titel oberhalb des Kreises
`value`
`text`/`number`
Zentrale Anzeige im Kreis
`subtitle`
`text`
Text unterhalb des Kreises
`width`
`text`
Individuelle Breite des Steps
`colorLabel`
`text`
Textfarbe für `title` und `subtitle`
`fontSizeLabel`
`text`
Schriftgröße für `title` und `subtitle`
`colorValue`
`text`
Textfarbe des zentralen Werts
`fontSizeValue`
`text`
Schriftgröße des Werts
`backgroundColor`
`text`
Hintergrundfarbe des Kreises und der Verbindungslinien
`borderColor`
`text`
Farbe der Step-Trennlinie
`actions[]`
`array`
Aktionen, die beim Klick ausgelöst werden können (siehe unten)
{t(
'Leerer Zustand — über Daten auf Voll oder Demo wechseln.',
'Empty state — switch Data to Full or Demo.',
'Estado vacío — cambia Datos a Completo o Demo.',
)}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetTableData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onCellClick
Browser-Event und Zellenposition. Klickbarkeit muss an Zeile oder Zelle aktiviert sein.
```typescript
onCellClick?: (event: Event, payload: ArcWidgetTableCellPayload) => void;
```
### onCellHoverEnter
Position der betretenen Zelle; benötigt `hover_enterable`.
```typescript
onCellHoverEnter?: (payload: ArcWidgetTableCellPayload) => void;
```
### onCellHoverLeave
Position der verlassenen Zelle; benötigt `hover_leaveable`.
```typescript
onCellHoverLeave?: (payload: ArcWidgetTableCellPayload) => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### minHeight
Untere Höhengrenze.
Typ: `string`.
### minWidth
Untere Breitengrenze.
Typ: `string`.
### maxHeight
Obere Höhengrenze.
Typ: `string`.
### groupedBy
Gruppierungsschlüssel; weglassen für flache Tabellen.
Typ: `string`.
### groupsCollapsed
Anfangszustand der Gruppen.
Typ: `boolean`.
### collapsible
Aufklappen bzw. Einklappen; das konkrete Format steht im Typ.
Typ: `{ enabled?: boolean; expandColumn?: number; indentColumn?: number }`.
### theme
Widgetspezifische Theme-Konfiguration. Für React kannst du Farben direkt in `styles` und den Bereichen setzen.
Typ: `ArcWidgetTableTheme | ArcNestedWidgetDescriptor | string`.
### rowHoverAction
Darstellung beim Überfahren einer Zeile.
Typ: `ArcWidgetTableHoverAction`.
### header
Spaltenüberschriften, Breiten und Sortieroptionen.
Typ: `ArcWidgetTableHeader`.
### emptyTable
`title` ist der einfache Fallback-Text. Wenn `value` gesetzt ist, ersetzt dieser Inhalt den Fallback vollständig. Für Überschrift und Beschreibung zusammen verwende ein JSX-Element in `value`, wie im Live-Beispiel.
Darstellung bei leerer Zeilenliste.
Typ: `ArcWidgetTableEmpty`.
### scrollBar
Darstellung des Scrollbalkens.
Typ: `ArcWidgetTableScrollBar`.
### table
Datenzeilen mit `columns`; optionale Unterzeilen stehen in `items`.
Typ: `ArcWidgetTableRow[]`.
### footer
Inhalte und Sichtbarkeit des Tabellenfußes.
Typ: `ArcWidgetTableFooter`.
### styles
Gemeinsame Farben, Abstände und Rahmen; die angebotenen Felder sind widgetspezifisch.
Typ: `ArcWidgetTableStyles | string`.
### borders
Historische Rahmenkonfiguration. Bevorzuge `styles.borders`, sofern vom Widget angeboten.
Typ: `ArcWidgetTableBorders`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
## Verhalten und Grenzen
- Jede Spalte braucht eine Breite. Verwende mindestens einmal `width: "fraction"`; Header und Zellen müssen dieselbe Spaltenreihenfolge haben.
- Setze `clickable: true` auf der Zeile oder Zelle, damit `onCellClick` ausgelöst wird. `row_index` und `col_index` sind nullbare Indizes; prüfe sie vor dem Zugriff.
- Bei JSX-Zellinhalten braucht Sortierung einen skalaren `sort.value`. Verwende für Datumssortierung Millisekunden statt lokalisierter Datumsstrings.
- Verschachtelte Zeilen werden über `items` beschrieben; `collapsible` steuert Einrückung und Aufklappen. Flache Beispiele können `row_index` direkt auf die Datenliste abbilden.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetTableSort {
enabled?: boolean;
type?: 'text' | 'number' | 'date' | string;
value?: string | number;
}
export interface ArcWidgetTableHeaderColumn {
title?: ArcWidgetSlot;
width?: string;
sort?: ArcWidgetTableSort;
styles?: ArcWidgetStyles | string;
[key: string]: unknown;
}
export interface ArcWidgetTableHeader {
showHeader?: boolean;
height?: string;
fontColor?: string;
backgroundColor?: string;
fontSize?: string;
styles?: ArcWidgetStyles | string;
columns?: ArcWidgetTableHeaderColumn[];
sortIcons?: {
color?: string;
activeColor?: string;
hoverColor?: string;
};
[key: string]: unknown;
}
export interface ArcWidgetTableCellPayload {
row_index?: number | null;
col_index?: number | null;
flat_index?: number | null;
group_value?: string | null;
}
export interface ArcWidgetTableColumn {
title?: ArcWidgetSlot;
value?: ArcWidgetSlot;
color?: string;
backgroundColor?: string;
width?: string;
align?: 'left' | 'center' | 'right' | string;
paddingX?: string;
paddingY?: string;
groupExpandAction?: boolean;
groupValue?: ArcWidgetSlot;
groupByValue?: ArcWidgetSlot;
clickable?: boolean;
hover_enterable?: boolean;
hover_leaveable?: boolean;
popup_button?: { content?: ArcWidgetSlot };
sort?: ArcWidgetTableSort;
styles?: ArcWidgetStyles | string;
[key: string]: unknown;
}
export interface ArcWidgetTableRow {
id?: string | number;
rowColor?: string;
rowHeight?: string;
rowPaddingY?: string;
groupRowColor?: string;
groupRowSettings?: { height?: string; [key: string]: unknown };
columns?: ArcWidgetTableColumn[];
items?: ArcWidgetTableRow[];
clickable?: boolean;
styles?: ArcWidgetStyles | string;
[key: string]: unknown;
}
export interface ArcWidgetTableEmpty {
title?: ArcWidgetSlot;
value?: ArcWidgetSlot;
backgroundColor?: string;
[key: string]: unknown;
}
export interface ArcWidgetTableTheme {
[key: string]: unknown;
}
export interface ArcWidgetTableFooter {
showFooter?: boolean;
showActionButton?: boolean;
backgroundColor?: string;
actionButtonTitle?: ArcWidgetSlot;
leftSideContent?: ArcWidgetSlot;
rightSideContent?: ArcWidgetSlot;
[key: string]: unknown;
}
export interface ArcWidgetTableScrollBar {
showScrollBar?: boolean;
height?: string;
backgroundColor?: string;
handle?: {
height?: string;
borderRadius?: string;
backgroundColor?: string;
[key: string]: unknown;
};
[key: string]: unknown;
}
export type ArcWidgetTableBorderLine = boolean | {
color?: string;
width?: string;
borderColor?: string;
borderWidth?: string;
borderSize?: string;
enabled?: boolean;
};
export interface ArcWidgetTableBorders {
color?: string;
width?: string;
outer?: ArcWidgetTableBorderLine;
columns?: ArcWidgetTableBorderLine;
rows?: ArcWidgetTableBorderLine;
}
export interface ArcWidgetTableStyles extends ArcWidgetStyles {
borders?: ArcWidgetTableBorders;
}
export interface ArcWidgetTableHoverAction {
hoverActive?: boolean;
backgroundColor?: string;
fontColor?: string;
[key: string]: unknown;
}
export interface ArcWidgetTableData extends ArcWidgetBaseData {
height?: string;
minHeight?: string;
minWidth?: string;
maxHeight?: string;
groupedBy?: string;
groupsCollapsed?: boolean;
collapsible?: { enabled?: boolean; expandColumn?: number; indentColumn?: number };
theme?: ArcWidgetTableTheme | ArcNestedWidgetDescriptor | string;
rowHoverAction?: ArcWidgetTableHoverAction;
header?: ArcWidgetTableHeader;
emptyTable?: ArcWidgetTableEmpty;
scrollBar?: ArcWidgetTableScrollBar;
table?: ArcWidgetTableRow[];
footer?: ArcWidgetTableFooter;
styles?: ArcWidgetTableStyles | string;
borders?: ArcWidgetTableBorders;
borderRadius?: string;
}
export interface ArcWidgetTableProps extends ArcReactWidgetProps {
onCellClick?: (event: Event, payload: ArcWidgetTableCellPayload) => void;
onCellHoverEnter?: (payload: ArcWidgetTableCellPayload) => void;
onCellHoverLeave?: (payload: ArcWidgetTableCellPayload) => void;
}
```
## Einsatzbeispiele
- [Auftragsliste mit Suche und Status](/docs/react/examples/custom-table-mit-mini-widgets)
- [Text, Zahlen und Datum sortieren](/docs/react/examples/sortierung-innerhalb-einer-table)
- [Eigene Prioritätsreihenfolge](/docs/react/examples/customsort-einbinden)
- [Tabellendesign und Dark Mode](/docs/react/examples/custom-table-look)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Table
## AI Defaults (read first)
- **Column widths**: Every column MUST have explicit `width`. At least one column MUST use `width: "fraction"`.
- **Height**: Use `height: "100%"` (not `calc()`). Especially when `embedded: true`.
- **uniqueListId**: Required, use `"my-table-" + Nr`.
- **tableId**: Required (e.g. from `tableId("Tabellenname")`).
- **recordId**: Always raw `Nr`, NEVER `number(Nr)`.
- **Empty state**: Use `emptyTable: { title: "...", value: "..." }`, do NOT wrap table in if/else.
- **theme.uniqueId**: Must match `uniqueListId`.
- **Columns value**: Each column needs `recordId: Nr` inside the mapping.
- **Row actions**: Use `actions` array with `type: "popup"` or `type: "update"`, recordId = `Nr`.
- **Sort**: Client-side only; `header.columns[n].sort: { enabled: true, type: "text"|"number"|"date" }`; optional `columns[n].sort.value` for sort key when `value` is not plain text. Optional `header.sortIcons: { color, activeColor, hoverColor }` for caret colors (defaults: muted gray / black active / stronger on header hover).
- **Hover**: `actions: [{ type: "hover", fontColor, backgroundColor, ... }]` on table root, row, or column; `type: "hover"` is not passed to click handlers. Legacy `rowHoverAction` still supported.
- **Borders**: Live under `styles.borders`. Default is a rounded frame + row lines, **no vertical cell lines**. Hide the frame with `styles: { borders: { outer: false } }`. Opt into a grid with `columns: true`. Set `styles.borderColor` for dark backgrounds; a line may be `{ color, width }` instead of a boolean.
- **styles hierarchy**: Same `styles` bag on table, header, row, and column — prefer `{ backgroundColor, fontColor, … }` over a CSS string. Table `styles.backgroundColor` is the default surface. A row or column overrides with its own `styles.backgroundColor`. Header uses `header.backgroundColor` / `header.styles`. Do not invent extra props like `rowBackgroundColor`.
# Custom Table
Das **Custom Table**-Widget ermöglicht dir die Darstellung dynamischer, interaktiver Tabellen direkt auf deiner Ninox-Oberfläche – maßgeschneidert nach deinen Anforderungen. Es eignet sich ideal, um strukturierte Daten übersichtlich darzustellen, individuell zu formatieren und mit Aktionen zu verknüpfen (z. B. für Bearbeiten, Löschen, Öffnen von Datensätzen oder API-Aufrufe).
## Beispiel:
## Gesamter Anwendungscode
Im Folgenden siehst du einen beispielhaften Anwendungscode, der die Basis deiner **Custom Table** definiert. Da der Code – je nach Anwendungsfall – sehr umfangreich werden kann, führen wir dich schrittweise **von einer einfachen Basis** zu **komplexeren Varianten**.
Der Aufbau gliedert sich in zwei zentrale Bereiche:
- `**data**` – definiert den Inhalt und die Struktur deiner Tabelle (Zeilen und Spalten)
- `**arcCustomTable()**` – ist die globale Funktion, die das Widget rendert. Ihr übergibst du die `data`
```javascript
let current := this;
let projectList := Artikel;
let data := {
uniqueListId: "beispiel" + Nr,
tableId: "",
height: "500px",
minHeight: "",
groupedBy: "",
groupsCollapsed: false,
theme: arcCustomThemeCleanWhite({
uniqueId: "beispiel"
}),
embedded: false,
rowHoverAction: {
hoverActive: true,
backgroundColor: "",
fontColor: ""
},
header: {
showHeader: true,
height: "",
fontColor: "",
backgroundColor: "",
fontSize: "",
columns: [{
title: "Prio",
width: ""
}]
},
emptyTable: {
title: "Keine Ergebnisse",
backgroundColor: "",
value: ""
},
scrollBar: {
showScrollBar: false,
height: "",
backgroundColor: "",
handle: {
height: "",
borderRadius: "",
backgroundColor: ""
}
},
table: projectList.[{
recordId: Nr,
rowColor: "",
rowHeight: "auto",
rowPaddingY: "10px",
groupRowColor: "",
groupRowSettings: {
height: "",
},
columns: [{
field: "",
title: "",
value: "",
color: "",
backgroundColor: "",
width: "",
align: "left",
paddingX: "",
paddingY: "",
groupExpandAction: false,
groupValue: arcCustomIcon({
name: "caret-down"
}),
groupByValue: "",
actions: [{
type: "popup",
showPopupButton: false,
recordId: Nr
}]
}]
}],
footer: {
showFooter: false,
showActionButton: true,
backgroundColor: "",
actionButtonTitle: "",
leftSideContent: "",
rightSideContent: "Gesamt: " + cnt(projectList) + " Projekte"
}
};
arcCustomTable(data)
```
### uniqueListId
Der Parameter `**uniqueListId**` ist die **individuelle Bezeichnung deiner Tabelle**. Er sorgt dafür, dass deine Tabelle intern eindeutig identifiziert wird – besonders dann, wenn **mehrere Tabellen gleichzeitig auf einer Seite** angezeigt werden.
**Warum ist das wichtig?**
- Style-Einstellungen (z. B. Farben, Schriftarten, Hover-Effekte) werden gezielt nur auf die Tabelle mit der angegebenen `uniqueListId` angewendet.
- Bei mehreren Tabellen auf einer Ansicht kann es sonst zu **Konflikten bei CSS-Klassen oder Zuständen** kommen.
**✅ Best Practice:**
Verwende **sprechende, eindeutige Namen** – am besten in camelCase oder mit Unterstrichen.
```javascript
uniqueListId: "Projektliste Offen", // Text
```
### tableId
Mit `**tableId**` gibst du die **interne ID der Tabelle in Ninox** an, auf die sich das Widget bezieht. Diese ID wird z. B. benötigt, um:
- neue Datensätze über den **„+“-Button** im Footer anzulegen (`create`)
- bestehende Datensätze zu öffnen oder bearbeiten zu können (`popup`, `openFullscreen`, `update`)
- Aktionen korrekt auf Datensätze dieser Tabelle zu beziehen
```javascript
tableId: "AB", // Die ID als Textform
tableId: tableId("Kontakte"), // Ninox Funktion zum Herausfinden der Table ID deiner darzustellenden Tabelle
```
### height
Mit `**height**` bestimmst du die **Höhe des Tabellen-Widgets** in **Pixeln**. So kannst du die Darstellung flexibel an das Layout deiner Seite anpassen – egal, wie viele Daten enthalten sind.
**💡 Werte**
- Der Wert wird in Pixeln angegeben – z. B. `"300px"`, `"500px"` oder `"800px"`.
- `**"auto"**`: Die Höhe passt sich automatisch an den Inhalt an. Perfekt für dynamische Inhalte – beachte aber mögliche Sprünge im Layout.
- In Kombination mit `maxHeight` kannst du die automatische Höhe begrenzen.
```javascript
height: "500px", // Pixel Werte
```
### minWidth
Mit `**minWidth**` legst du die **minimale Breite** deiner Tabelle fest – unabhängig davon, wie viele Spalten oder Daten enthalten sind. So stellst du sicher, dass die Tabelle nicht zu schmal dargestellt wird, z. B. bei schmalen Containern, Tabs oder eingebetteten Ansichten.
🔍 **Format**
- Der Wert wird als **Text mit Einheit** übergeben, z. B. `"600px"`
- Ohne Angabe kann die Tabelle bei zu wenig Inhalt schmal zusammenfallen – was das Layout stören kann.
💡 **Hinweis:**
`minWidth` wirkt sich auf die äußere Tabellenhülle aus – nicht auf die Spaltenbreiten im Inneren. Für Spalten gibt es separate Optionen wie `width` und `minWidth` direkt im `columns`-Block.
### groupedBy
Mit `**groupedBy**` definierst du, nach welchem **Feld (Spalten-Key bzw. **`**field**`**)** deine Tabelle gruppiert werden soll. Gruppen werden dabei visuell als **separate Zeilen mit eigener Formatierung** dargestellt – die darunterliegenden Einträge lassen sich ein- und ausklappen.
🔍 **Verhalten**
- Du gibst hier den **Spaltennamen (**`**field**`**)** an, der in deinem `columns`-Block definiert ist.
- Ist das Feld leer (`"`) oder fehlt ganz, **findet keine Gruppierung statt**.
- Gruppierung kann auch auf komplexen Werten basieren (z. B. `Typ`, `Kategorie`, `Verantwortlicher` etc.).
- Die Gruppen lassen sich dynamisch durch Klick auf die Gruppenzeile **auf- und zuklappen** – dieser Zustand wird **lokal gespeichert**.
```javascript
groupedBy: "", // default: keine Gruppierung ausgewählt
groupedby: "Status", // Text des Feldtitels, nach dem gruppiert werden soll
groupedBy: Gruppierung, // Ninox Feld, das angesprochen wird. In diesem Fall: Ein Auswahlfeld, in dem die Optionen den Titel verschiedener Ninox-felder tragen, nach denen gruppiert werden kann. (z.B. Status, Mitarbeiter, Aufgabe)
```
### groupsCollapsed
Mit `**groupsCollapsed**` legst du fest, ob gruppierte Zeilen **standardmäßig eingeklappt** oder **ausgeklappt** dargestellt werden. Die Gruppenüberschrift (groupRow) ist dabei immer sichtbar – nur die zugehörigen Einträge (valueRows) werden bei Bedarf ein- oder ausgeblendet.
**Dieser Parameter wirkt nur, wenn **`**groupedBy**`** gesetzt ist.**
`**true**` = Gruppen sind beim Laden **eingeklappt** (kompakte Ansicht).
`**false**` = Gruppen sind beim Laden **vollständig geöffnet**.
**Der Zustand (ein-/ausgeklappt) wird lokal gespeichert**, d. h. bei erneutem Öffnen merkt sich das Widget den letzten Zustand pro Benutzer.
**Standardwert: **`**false**`** (Gruppen sind offen)** – wenn nicht angegeben, zeigt die Tabelle alle Gruppeneinträge vollständig an.
```javascript
groupscollapsed: "", // default: false
groupsCollapsed: true,
```
### embedded
Mit `**embedded**` aktivierst du den **eingebetteten Modus** der Tabelle. In diesem Modus passt sich die Tabelle optimal an bestehende Layoutstrukturen an – z. B. in einem Container, Tab oder einem flexiblen UI-Bereich.
**Standardwert: **`**false**` – die Tabelle nimmt dann ihren eigenen, festen Platz auf der Seite ein.
**Wenn **`**embedded: true**`** gesetzt ist, wird das Widget nicht absolut, sondern relativ im Container positioniert** und übernimmt dessen Breite und ggf. auch andere Stilvorgaben. Kombiniert mit Parametern wie `height` und `minWidth` sorgt das für ein sauberes, integriertes Erscheinungsbild.
**Besonders nützlich ist **`**embedded**`** in Dashboards, Tab-Ansichten oder Modalfenstern.**
```javascript
embedded: false,
embedded: true,
embedded: "", // default: false
```
### styles.borders
Rahmen und Gitterlinien leben in **`styles`** — zusammen mit Hintergrund, Radius und Linienfarbe.
Default: abgerundeter Außenrahmen, feine Zeilenlinien, **keine vertikalen Zelllinien**.
Jedes Linienfeld ist `true` / `false` **oder** `{ color, width }`.
| Prop | Default | Bedeutung |
|---|---|---|
| `styles.borderColor` | `#e4e4e7` | Farbe für alle angeschalteten Linien |
| `styles.borderRadius` | `12px` | Eckenradius (nur wenn `outer` an) |
| `styles.borders.outer` | `true` | Außenrahmen. `false` = bündig im Layout |
| `styles.borders.columns` | `false` | Vertikale Linien |
| `styles.borders.rows` | `true` | Horizontale Linien |
| `styles.borders.color` / `width` | — | Gemeinsame Linie, überschreibt `borderColor` / Default-Stärke |
```javascript
styles: {
borderRadius: "12px",
borderColor: "#e4e4e7",
borders: {
outer: true,
columns: false,
rows: true
}
}
// In einem Layout / Card:
styles: { borders: { outer: false } }
// Dunkler Hintergrund — Fläche auf styles, Kopf auf header:
styles: {
backgroundColor: "#2a2822",
fontColor: "#f5f0e6",
borderColor: "#3f3c34"
},
header: {
backgroundColor: "#1c1b16",
fontColor: "#f5f0e6"
}
// Klassisches Gitter:
styles: { borders: { columns: true } }
```
Fertige Varianten (Default, Card, Gitter, flush, Dark): [Custom Table Look](/documentation/custom-table-look).
### rowHoverAction
Mit dem `**rowHoverAction**`-Block bestimmst du, ob das **Hover-Verhalten auf Tabellenzeilen** aktiv sein soll – und falls ja, **welche Farben** beim Überfahren mit der Maus verwendet werden.
- `**hoverActive: true**` aktiviert den Effekt, andernfalls bleibt die Zeile beim Hover unverändert.
- `**backgroundColor**` definiert die **Hintergrundfarbe** der Zeile im Hover-Zustand,
- `**fontColor**` legt die **Textfarbe** während des Hoverns fest.
**Standardwert bei **`**hoverActive**`** ist **`**true**`, falls der Block gesetzt ist. Ohne `rowHoverAction` ist das Verhalten neutral – keine Hover-Effekte.
**Tipp: Setze gedeckte Farben ein**, um den Effekt dezent und UX-freundlich zu halten.
```javascript
rowHoverAction: { hoverActive: true, // wenn hovern an sein soll, und false, wenn nicht
backgroundColor: "#9ca4a9", // default: #f4f6ff
fontColor: "#fff" } // default: #000
```
**Empfehlung:** Für neue Projekte nutze `actions: [{ type: "hover", ... }]` (siehe unten) – `rowHoverAction` bleibt aus Backwards-Compatibility erhalten.
### actions mit type: "hover"
Hover-Styling und optionale Hover-Actions über dasselbe `actions`-Array wie `update` / `popup`. Eintrag mit `**type: "hover"**` wird **nicht** an Klick-Actions weitergegeben, sondern nur vom Widget ausgewertet.
**Merge-Reihenfolge:** `rowHoverAction` (Legacy) → `actions` auf Tabellen-Root → `row.actions` → `columns[n].actions`.
| Sub-Prop | Bedeutung |
|---|---|
| `enabled` | `false` = keine Hover-Hervorhebung für diese Zeile/Zelle. |
| `backgroundColor` | Hintergrundfarbe bei Hover. |
| `fontColor` | Textfarbe bei Hover. |
| `styles` | Zusätzliches CSS (String) für die Zelle bei gehoverter Zeile. |
| `actions` | Optional: bei **mouseenter** an den Action-Handler (z. B. `update`). |
| `leaveActions` | Optional: bei **mouseleave**. |
**Row-Level:** `actions: [{ type: 'hover', backgroundColor: '#eff6ff', fontColor: '#0f172a' }]` auf dem Zeilenobjekt.
**Column-Level:** z. B. `{ type: 'hover', enabled: false }` um eine einzelne Spalte von der Hover-Hervorhebung auszunehmen.
**`row.actions`** (ohne `hover`) – zusätzliche `update`/`popup`-Einträge gelten für die **ganze Zeile** (Klick auf eine Zelle führt Row- und Cell-Actions zusammen aus).
### header
Mit dem ***header***-Block steuerst du die Darstellung deiner **Tabellenkopfzeile** (Spaltenüberschriften).
**Standardverhalten:** Wenn `showHeader` nicht angegeben ist, wird die Header-Zeile **angezeigt**. Ohne weitere Einstellungen gelten Standardwerte für Größe, Farbe und Hintergrund.
Tipp: Wenn du `showHeader: false` setzt, sollte die Bedeutung der Daten trotzdem klar erkennbar bleiben (Position, Farbschema der Spalten).
#### showHeader
Blendet die gesamte Header-Zeile ein oder aus.
```javascript
header: {
showHeader: false, // default: true
}
```
#### height
Höhe der Headerzeile (z. B. `"48px"` oder `"auto"`).
```javascript
header: {
height: "70px", // default: 36px
}
```
#### fontColor
Schriftfarbe der Spaltenüberschriften.
```javascript
header: {
fontColor: "#fff", // default: #000
}
```
#### fontSize
Schriftgröße der Überschriften.
```javascript
header: {
fontSize: "17px", // default: 12px
}
```
#### backgroundColor
Hintergrund der Headerzeile.
```javascript
header: {
backgroundColor: "#3a4a54", // default: #f8f9fc
}
```
#### styles
CSS-String für freies Styling des Header-Containers (überschreibt `fontColor`, `backgroundColor` etc.).
```javascript
header: {
styles: "border-bottom: 1px solid #eee;",
}
```
Vollständiges Beispiel:
```javascript
header: {
showHeader: false, // default: true
height: "70px", // default: 36px
fontColor: "#fff", // default: #52525b
backgroundColor: "#3a4a54", // default: #fafafa
fontSize: "17px", // default: 12px
}
```
### sort (Client-Side)
Sortierung erfolgt **vollständig im Browser** (kein Ninox-Update, kein Helper-Feld). Der Zustand (aktive Spalte, Richtung) wird **intern** verwaltet und wie Scroll/Gruppen im **localStorage** persistiert.
**Header-Spalte** – `sort` aktivieren und Typ setzen:
- `**sort.enabled**`: `true` – Spaltenkopf ist klickbar, zeigt Sort-Icons.
- `**sort.type**`: `'text'` (Standard), `'number'` oder `'date'`.
**Zeilen-Zelle** – optionaler Rohwert für den Vergleich:
- `**sort.value**`: Wert, nach dem sortiert wird. Wenn nicht gesetzt, wird `value` der Zelle verwendet (bei Widgets/HTML in `value` ungeeignet – dann immer `sort.value` setzen).
**Klick-Zyklus:** erste Klick → aufsteigend, zweiter → absteigend, dritter → Sortierung aus.
**Sort-Icons (Outline-Chevrons):** Farben optional über `header.sortIcons` (werden als CSS-Variablen am Header gesetzt):
| Prop | Bedeutung | Standard (CSS-Fallback) |
|------|-----------|-------------------------|
| `color` | Farbe der **inaktiven** Carets | `rgba(0,0,0,0.35)` |
| `activeColor` | Farbe des **aktiven** Carets (aktuelle Sortierrichtung) | `#000000` |
| `hoverColor` | Farbe beider Carets bei **Hover** über den sortierbaren Header (inaktive Carets; aktiver Caret bleibt `activeColor`) | `rgba(0,0,0,0.55)` |
Bei **Gruppierung** (`groupedBy`) wird nur **innerhalb jeder Gruppe** sortiert, nicht über Gruppen hinweg.
```javascript
header: {
showHeader: true,
sortIcons: {
color: 'rgba(0,0,0,0.4)',
activeColor: '#000000',
hoverColor: 'rgba(0,0,0,0.6)'
},
columns: [{
title: 'Name',
width: 'fraction',
sort: { enabled: true, type: 'text' }
}, {
title: 'Betrag',
width: '120px',
sort: { enabled: true, type: 'number' }
}]
},
table: myList.[{
recordId: Nr,
columns: [{
field: 'Name',
value: Name,
width: 'fraction'
}, {
field: 'Betrag',
value: text(Betrag) + ' €',
sort: { value: number(Betrag) },
width: '120px'
}]
}]
```
### emptyTable
Mit dem `**emptyTable**`-Block legst du fest, **was angezeigt werden soll, wenn keine Daten vorhanden sind** – also wenn `data: []` leer ist. Du kannst Text und Gestaltung des leeren Zustands anpassen und so die Nutzererfahrung deutlich verbessern.
- `**title**`: Der Haupttext, der angezeigt wird (meist prominent, z. B. „Keine Einträge gefunden“).
- `**value**`: Optionaler zusätzlicher Text oder HTML-Elemente im Inneren des leeren Bereichs.
- `**backgroundColor**`: Hintergrundfarbe für den leeren Bereich – z. B. `"white"` oder `"#f4f6ff"`.
**Standardverhalten:**
Ohne `emptyTable` wird ein schlichter Text „Keine Ergebnisse“ angezeigt.
💡 **Pro-Tipp:**
Leere Zustände sind keine Fehler – sie sind deine Bühne. Nutze sie für Erklärungen, motivierende Hinweise oder einen klaren Call-to-Action („Jetzt neuen Eintrag erstellen“). So bleiben deine Nutzer nicht im Leeren hängen – im wahrsten Sinne.
```javascript
emptyTable: {
title: "", // Text der bei einer leeren Tabelle in einem abgerundeten Badge dargestellt wird.
backgroundColor: "", // Hintergrundfarbe in HEX angeben
value: "" // Hier kannst du eigene Widgets oder komplexe Ansichten einfügen, die den Title überschreiben.
},
```
### scrollBar
Mit dem `**scrollBar**`-Block konfigurierst du die **horizontale Scrollbar** deiner Tabelle. Diese wird angezeigt, wenn deine Tabelle mehr Spalten enthält, als in den verfügbaren Bereich passen.
- `**showScrollBar**`: `true` oder `false` – bestimmt, ob die Scrollbar überhaupt angezeigt wird.
- `**height**`: Höhe des Scrollbar-Containers (z. B. `"10px"`).
- `**backgroundColor**`: Hintergrundfarbe des Containers.
- `**handle.height**`: Höhe des Schiebers („Handle“) innerhalb der Leiste.
- `**handle.backgroundColor**`: Farbe des Scroll-Handles.
- `**handle.borderRadius**`: Abgerundete Ecken des Schiebers (z. B. `"5px"` oder `"50%"`).
**Standardverhalten:**
Ohne `scrollBar` wird **keine sichtbare Scrollbar angezeigt** – auch wenn Inhalte horizontal überlaufen.
💡 **Pro-Tipp:**
Gerade bei vielen Spalten hilft eine dezente, gut sichtbare Scrollbar, um Orientierung zu geben. Nutze weiche Farben und eine runde Handle-Form, damit die UI nicht „technisch“ wirkt – besonders auf Touch-Geräten zahlt sich das aus.
```javascript
scrollBar: { showScrollbar: true, // default: false (Scrollbar ist standardmäßig ausgeblendet)
height: 40px, // Höhe des Containers. default: 10px
backgroundColor: "#3a4a54" // default: #f0f0f0
handle: { height: "20px", // Höhe des Schiebers. default: 90%
borderRadius: 20px // default: 20px
backgroundColor: "#fff", } // default: #ccc
```
### theme
Mit dem `**theme**`-Parameter kannst du ein **vordefiniertes Design-Template** für deine Tabelle aktivieren. Das Theme beeinflusst das **gesamte visuelle Erscheinungsbild** – von Farben über Schriftarten bis hin zum Layout. Aktuell verfügbar sind:
- `**"clean-white"**`
- `**"naked"**`
**Wichtig:**
Damit das Theme korrekt greift, muss die `theme`-uniqueId **die gleiche **`**uniqueListId**`** verwenden wie deine Tabelle**. Nur so überschreibt das Theme gezielt die richtigen Style-Regeln per CSS.
**Standardverhalten:**
Wird kein `theme` gesetzt, wird das Standarddesign des arcCustomTable-Widgets verwendet (leicht schattiert, kontrastreich).
```javascript
theme: arcCustomThemeCleanWhite({
uniqueId: "Projektliste Demo 1"
}),
```
### styles
Dieselbe `styles`-Tasche auf jeder Ebene. Bevorzugt ein Objekt mit CSS-ähnlichen Namen (`backgroundColor`, `fontColor`, `paddingX`). Ein CSS-String geht weiter.
| Ebene | Prop | Wirkt auf |
|---|---|---|
| Tabelle | `styles: { backgroundColor, borders, … }` | Fläche + Rahmen. Default für alle Zeilen |
| Header | `header: { backgroundColor }` oder `header.styles` | Kopfzeile |
| Header-Zelle | `header.columns[n].styles` | Eine Kopfzelle |
| Zeile | `table: [{ styles: { backgroundColor } }]` | Alle Zellen dieser Zeile |
| Spalte / Zelle | `table: [{ columns: [{ styles: { backgroundColor } }] }]` | Eine Zelle |
| Footer | `footer.styles` | Footer |
Spalte überschreibt Zeile, Zeile überschreibt Tabelle. `styles` gewinnt gegen `rowColor` / flaches `backgroundColor`.
```javascript
styles: {
backgroundColor: "#ffffff",
borderColor: "#e4e4e7",
borders: { outer: true, columns: false, rows: true }
},
header: {
backgroundColor: "#fafafa"
},
table: myList.[{
recordId: Nr,
styles: {
backgroundColor: "#f4f4f5"
},
columns: [{
value: Name,
width: "fraction",
styles: {
fontWeight: "600"
}
}]
}]
```
### footer
Mit dem `**footer**`-Block kannst du einen **unteren Bereich** unterhalb der Tabelle anzeigen lassen – z. B. für Buttons oder Informationen. Er eignet sich ideal für **Aktionsflächen** wie „Neuen Eintrag anlegen“ oder zur Anzeige von Summen, Filtern oder Statusinfos.
- `**showFooter**`: `true` oder `false` – aktiviert oder deaktiviert den Footer.
- `**showActionButton**`: Zeigt den Standard-Button *„Neuen Datensatz erstellen“* an.
- `**actionButtonTitle**`: Individueller Text für den Action-Button.
- `**backgroundColor**`: Hintergrundfarbe des Footers.
- `**leftSideContent**`: Freier Inhalt (z. B. Text, HTML, Icons) für die linke Seite.
- `**rightSideContent**`: Inhalt für die rechte Seite – z. B. Statusanzeigen, Summen oder Infos.
**Standardverhalten:**
Ohne `footer`-Block wird kein Footer angezeigt. Wird `showFooter: true` gesetzt, aber keine weiteren Optionen, erscheint ein leerer Footerbereich.
```javascript
footer: {
showFooter: true,
showActionButton: true,
backgroundColor: "",
actionButtonTitle: "Neue Aufgabe hinzufügen",
leftSideContent: "",
rightSideContent: "Gesamt: " + cnt(filteredList) + " Aufgaben"
}
```
So sieht der oben definierte Footer aus:
## table
Im **Detail-Bereich **`**table**` definierst du alle **Spalten (columns)** und deren **Darstellung, Inhalte und Verhalten**. Du legst hier fest, **welche Datenfelder angezeigt werden sollen**, wie sie aussehen und was beim Klicken passieren soll.
- Jede Spalte kann **individuell formatiert** werden (z. B. Farbe, Ausrichtung, Padding, Aktionen).
- Die hier gesetzten Werte **überschreiben** ggf. globale Einstellungen aus dem `settings`-Block (z. B. `fontColor`, `backgroundColor`, `align` etc.).
- Du kannst hier auch **fixierte Spalten**, **Gruppierungen**, **Interaktionen** und **Inline-Editing** steuern.
## Zeilen- und Gruppenparameter
```javascript
projectList.[{
recordId: Nr,
rowColor: "",
rowHeight: "auto",
rowPaddingY: "10px",
groupRowColor: "",
groupRowSettings: {
height: "",
},
```
- `**recordId**`:
Muss die `**Nr**` des Datensatzes sein (also die interne ID in Ninox).
*Wichtig für die Zuordnung von Aktionen, z. B. Öffnen, Bearbeiten, Löschen.*
- `**rowColor**`:
Setzt die **Hintergrundfarbe** der jeweiligen Zeile.
*Akzeptiert HEX-Werte wie *`*"#f4f6ff"*`* oder *`*"transparent"*`*.*
- `**rowHeight**`:
Bestimmt die **Höhe der Zeile**.
*Wert kann *`*"auto"*`* sein oder eine feste Pixelangabe wie *`*"60px"*`*.*
- `**rowPaddingY**`
→ Vertikales **Innenabstands-Polster** (top/bottom) innerhalb der Zellen dieser Zeile.
Wird auf alle Zellen angewendet, **sofern dort kein individuelles Padding gesetzt ist**.
- `**groupRowColor**`:
Setzt die Hintergrundfarbe für eine **Gruppen-Zeile** (wenn `groupedBy` aktiv ist).
*Du kannst entweder HEX-Werte verwenden oder dynamisch auf Felder zugreifen (z. B. *`*row.farbe*`*).*
- `**groupRowSettings.height**`
→ Legt die **Höhe der Gruppenzeile** fest.
Wert z. B. `"40px"` oder `"auto"`. Wirkt nur, wenn die Zeile eine **Gruppenzeile** ist.
- `**styles**`: CSS-String für freies Styling – wird auf jede Zelle der Zeile angewendet. Langfristiger Ersatz für `rowColor` und `rowHeight`.
💡 **Pro-Tipp:**
Du kannst **dynamisch berechnete Farben** einsetzen, um Status-Feedback direkt sichtbar zu machen – z. B. grün für „alle erledigt“, grau für „in Arbeit“:
```javascript
groupRowColor: if cnt(Firma.Projekte) = cnt(Firma.Projekte[Abgeschlossen != null]) then
"#F0FFF1"
else
"#eee"
end,
```
## Nested rows (`items[]`)
Hierarchical tables use the **same row shape** as flat `table[]`, plus optional nested children on each row.
### Top-level input (either/or)
| Form | Use case |
|------|----------|
| **`table: [...]`** | Classic — existing projects, flat + nested |
| **`items: [...]`** | Greenfield — same row objects, Timeline-style root |
Do **not** set both `table` and root `items` at once. If both are present, `table` wins (dev warning).
Each row may contain **`items: [...]`** for children (unlimited depth). Collapse/expand is **client-side** (persisted in `localStorage` per `uniqueListId`).
### Example — `table[]` with nested children
```javascript
arcCustomTable({
uniqueListId: "tasks-" + Nr,
header: {
columns: [
{ title: " ", width: "40px" },
{ title: "Aufgabe", width: "fraction" },
{ title: "Status", width: "120px" }
]
},
collapsible: {
enabled: true,
expandColumn: 0,
indentColumn: 1,
indentSize: "16px"
},
table: [{
id: "p1",
recordId: Nr,
columns: [
{ value: "" },
{ value: Bezeichnung },
{ value: Status }
],
items: Unteraufgaben.[{
id: format(number(Nr), "0000"),
recordId: Nr,
columns: [ /* same column layout */ ],
items: /* deeper levels */
}]
}]
})
```
### Example — root `items[]`
Same row objects; replace `table:` with `items:` at the root.
### `collapsible`
| Property | Meaning |
|----------|---------|
| `enabled` | `true`: parent rows with children show expand toggle |
| `defaultCollapsed` | `true`: all parent rows start collapsed |
| `expandColumn` | Column index for toggle (default `0`) |
| `indentColumn` | Column index for depth padding (default `1`) |
| `indentSize` | Padding per level, e.g. `"16px"` |
| `iconSize` | Default caret size when no custom icons — e.g. `"16px"` (default) |
| `iconExpand` / `iconCollapse` | Optional nested widget descriptors (e.g. `arcCustomIcon`) — replaces default caret |
**Not combinable with `groupedBy`** in the same table config.
Client-side sort is disabled when nested rows are present — order comes from Ninox (`table` / `items` structure).
### `span` / `colspan` on cells
All rows share the **same number of header columns**. To show a parent row with one wide cell across multiple columns, use **`span`** (alias **`colspan`**) on the cell:
```javascript
// Header: 4 columns (Expand | Name | Status | Date)
columns: [
{ value: "" },
{ value: "Team Nord — 3 members", span: 3 } // 1 + 3 = 4
]
// Child row: four normal cells (span defaults to 1)
columns: [
{ value: "" },
{ value: "Anna M." },
{ value: badgeWidget },
{ value: "14.06.2026" }
]
```
**Invalid:** parent row with 2 `columns` entries and child row with 4 entries **without** `span` — columns will misalign.
Optional **`width`** / **`minWidth`** on a cell still override min-width on that cell; grid tracks come from `header.columns`.
## columns
Im `columns`-Array definierst du die **einzelnen Spalten deiner Tabelle** – also wie sie aussehen, heißen und was darin angezeigt wird. Jede Spalte wird über ein eigenes Objekt innerhalb von `columns` beschrieben.
**Basics, die du einstellen kannst:**
- `**field**`: Das Datenfeld, das angezeigt werden soll – muss zu den Werten in `data.table.columns` passen.
- `**title**`: Der sichtbare Name der Spalte im Header.
- `**width**`: Die Breite der Spalte — fix z. B. `"200px"` / `"10%"`. Für flexible Spalte: `"fraction"`, `"auto"` oder `""` (leer) — gleiche Grid-Logik (`minmax(30px, 1fr)` bzw. gemischt mit fixen Spalten).
- `**align**`: Ausrichtung des Inhalts – `"left"`, `"center"` oder `"right"`.
- `**backgroundColor**`** / **`**color**`: Hintergrund- und Textfarbe der Spalte.
- `**paddingX**`** / **`**paddingY**`: Innenabstände horizontal und vertikal.
- `**truncate**`: Ob der Text abgeschnitten und mit „…“ versehen werden soll.
- `**fixed**`: `"left"` oder `"right"`, um eine Spalte zu fixieren.
- `**styles**`: CSS-String für freies Styling der Zelle (Header-Cell oder Body-Cell). Überschreibt alle anderen Style-Props.
- `**actions**`: Aktionen wie `update`, `popup`, `change`, `openFullscreen`, `delete`.
```javascript
columns: [{
field: "",
title: "",
value: "",
width: "",
align: "",
fixed: "",
paddingX: "",
paddingY: "",
groupExpandAction: "",
groupValue: "",
actions: [{
recordId: "",
type: "",
field: "",
value: ""
}]
}
```
### Gruppen ausklappen mit groupExpandAction
Mit ***groupExpandAction*** kannst du bestimmen, bei welchen Spalten die Funktion des Ausklappens aktiviert sein soll. Das funktioniert nur, wenn du eine Gruppierung in deiner Tabelle eingestellt hast. Aktivierst du es bei mindestens einer Spalte (mit groupExpandAction:true), ist es bei den anderen Spalten automatisch deaktiviert, sofern du es dort nicht auch mit aktivierst in den Parametern.
```javascript
groupExpandAction: true, // Aktiviert das Ausklappen der Tabellenzeilen durch Klick auf die Spalte.
groupExpandAction: false, // Deaktiviert das Ausklappen der Tabellenzeilen durch Klick auf die Spalte.
groupExpandAction: "", // default: true
```
### actions
Mit dem Parameter `**actions**` kannst du festlegen, **was passieren soll, wenn ein Nutzer auf eine Zelle klickt oder diese bearbeitet**. Aktionen werden auf **Zellebene innerhalb von **`**columns**` (in `data.table`) gesetzt und machen deine Tabelle interaktiv.
**💡 Hinweis:** Du kannst **mehrere Aktionen kombinieren**, indem du sie als Array einfügst.
Beispiel:
```javascript
actions: [{
recordId: Nr,
type: "popup"
}, {
recordId: Nr,
type: "change",
field: "A"
}],
```
#### Aktion: popup
Mit `**type: "popup"**` definierst du eine Aktion, die beim Klick auf die Zelle den verknüpften **Datensatz als Popup** öffnet – direkt innerhalb von Ninox. Dadurch können Nutzer Details einsehen oder bearbeiten, ohne die aktuelle Ansicht zu verlassen.
- `**recordId**` muss die `Nr` des jeweiligen Datensatzes sein.
- Diese Aktion gilt **immer für die ganze Zelle**, nicht nur für den Text.
- Du kannst mit `showPopupButton: true` zusätzlich einen Button anzeigen lassen, der den Popup explizit auslöst – nützlich, wenn du Editieren und Öffnen visuell trennen möchtest.
```javascript
actions: [{
recordId: Nr,
type: "popup", // Text. Muss genau so geschrieben werden.
showPopupButton: true, // true oder false zum Ein- oder Ausblenden des Open-Buttons
popupButton: arcCustomButton({
uniqueId: "ButtonProjekt" + Nr,
icon: "",
title: "Open",
fontSize: "13px",
fontColor: "",
iconColor: "",
backgroundColor: "",
borderColor: ""
})
}]
```
Statt die gesamte Zelle klickbar zu machen, kannst du auch einen **individuellen Button innerhalb der Zelle anzeigen lassen** – z. B. mit dem Widget `arcCustomButton`.
Dazu verwendest du:
- `**showPopupButton: true**` – aktiviert die Schaltfläche.
- `**popupButton**` – enthält das gerenderte Button-Element, z. B. per `arcCustomButton()`.
#### Aktion: delete
Mit `**type: "delete"**` kannst du beim Klick auf eine Zelle den zugehörigen Datensatz **löschen**. Die Aktion wirkt sich – wie bei `popup` – **auf die gesamte Zelle aus**.
- `**recordId**` muss auf die `Nr` des Datensatzes zeigen, der gelöscht werden soll.
- Es wird kein zusätzlicher Bestätigungsdialog eingebaut – das Löschen erfolgt direkt.
💡 **Hinweis:** Diese Aktion sollte **nur mit Bedacht** und **klar visualisiert** eingesetzt werden – z. B. durch eine spezielle Icon-Spalte oder einen rot markierten Button innerhalb der Zelle.
```javascript
actions: [{
recordId: Nr,
type: "delete" // Text. Muss genau so geschrieben werden.
}]
```
#### Aktion: update
Mit `**type: "update"**` kannst du beim Klick auf eine Zelle direkt ein **Feld des verknüpften Datensatzes ändern** – ohne Popup, ohne Edit-Modus.
- `**recordId**`: Die `Nr` des Datensatzes, der verändert werden soll.
- `**field**`: Das Feld, das aktualisiert wird (als Text).
- `**value**`: Der neue Wert, der gesetzt werden soll (Text, Zahl, Bool, etc.).
```javascript
actions: [{
recordId: Nr,
type: "update",
field: "G", // Gibt die genaue Field ID des Feldes an, auf das die Aktion angewendet wird.
value: if erledigt=true then null else true end, // Gibt den Wert an, der bei dem referenzierten Feld eingesetzt werden soll.
}]
```
💡 **Pro-Tipp:**
Wenn du das **Löschen nicht direkt**, sondern erst **nach einer Sicherheitsabfrage** durchführen möchtest, kannst du einen kleinen Umweg über ein **Hilfsfeld + Trigger** nehmen:
- Erzeuge ein **Ja/Nein-Feld** namens z. B. `trigger_delete`.
- Füge in der Tabelle eine `update`-Aktion ein, die `trigger_delete` auf `true` setzt.
- Im Trigger dieses Feldes nutzt du folgenden Dialog:
```javascript
if dialog("Eintrag Löschen", "Soll der Eintrag wirklich gelöscht werden?", ["Ja, löschen!", "Abbrechen"]) = "Ja, löschen!" then
delete this
end;
trigger_delete := false
```
#### Aktion: openFullscreen
Mit `**type: "openFullscreen"**` öffnest du den verknüpften Datensatz direkt im **Vollbildmodus** – also so, als würde man ihn klassisch in Ninox vollständig aufrufen.
- `**recordId**`: Die `Nr` des Datensatzes, der geöffnet werden soll.
**Einsatzszenario:**
Wenn du komplexe Datensätze mit vielen Tabs oder Untertabellen hast, ist `openFullscreen` die bessere Wahl gegenüber `popup`.
```javascript
actions: [{
recordId: Nr,
type: "openFullscreen", // Text. Muss genau so geschrieben werden.
}]
```
#### Aktion: openRecord
Mit `**type: "**openRecord**"**` öffnest du das Formular des gegebenen Datensatzes zusammen mit der entsprechenden Tabelle.
- `**recordId**`: Die `Nr` des Datensatzes, der geöffnet werden soll.
```javascript
actions: [{
recordId: Nr,
type: "openRecord",
showPopupButton: true
}]
```
### groupValue
Mit `**groupValue**` definierst du den **Inhalt der Gruppierungszeile** in einer bestimmten Spalte – also das, was in der Zeile angezeigt wird, die z. B. mehrere Datensätze zu einem Projekt, Kunden oder Status bündelt.
- Du kannst `groupValue` **in jeder Spalte** verwenden – auch mehrfach pro Gruppe, wenn gewünscht.
- Du kannst einfachen **Text**, HTML oder auch **Mini-Widgets** einbauen (z. B. Buttons, Layouts oder Statusanzeigen).
- Die Gruppierungszeile wird automatisch angezeigt, wenn `groupedBy` im `settings`-Block gesetzt ist.
```javascript
groupValue: Projekte.Bezeichnung // Ninox-Felder & -Schreibweisen möglich
groupValue: "Projekt:" + Projekte.Bezeichnung // Text + Ninox-Feld
groupValue: arcCustomProgressBar({
uniqueId: "",
width: "",
fontSize: "",
fontColor: "",
backgroundColor: "",
progressColor: "",
valueTotal: "",
valueProgress: "",
valueText: ""
}) // Andere Mini-Widgets
```
### groupByValue
Der `**groupByValue**`-Parameter erlaubt es, deine Tabelle nach **einem anderen Wert als dem angezeigten **`**value**` zu gruppieren. So kannst du die Anzeige der Zelle unabhängig von der Logik der Gruppierung steuern.
- `**value**`: Was der Nutzer in der Zelle sieht (z. B. ein Icon, ein Label, ein HTML-Element).
- `**groupByValue**`: Nach diesem Wert wird die Zeile gruppiert.
**Fallback:**
Wenn `**value**` oder `**groupByValue**` leer ist, wird die Zeile automatisch der Gruppe `**arc-no-value**` zugeordnet.
Diese Gruppe wird ganz normal dargestellt, kann aber auch gezielt angesprochen oder ausgeblendet werden.
```javascript
groupByValue: Projekte.Nr //
groupByValue: Typ // Ninox-Felder
groupByValue: "" // default: es wird nach value gruppiert
```
## Beispiele
Folgend findest du einige Praxisbeispiele, die dir den unterschiedlichen Einsatz der Custom Table veranschaulichen.
### Custom Table Simple
```javascript
let current := this;
let projectList := (select Projekte);
let data := {
uniqueListId: "Projektliste Offen",
tableId: tableId(first(projectList)),
height: "auto",
groupedBy: "",
popupButtonTitle: "Open",
table: projectList.[{
recordId: Nr,
rowColor: "",
groupRowColor: "#eee",
columns: [{
field: "Feldname für Feld-ID",
title: "Titel",
value: "Ninox Wert",
width: "10%"
}, {
field: "Feldname für Feld-ID",
title: "Titel",
value: "Ninox Wert",
width: "15%"
}, {
field: "Feldname für Feld-ID",
title: "Titel",
value: "Ninox Wert",
width: "10%"
}, {
field: "Firma.Name",
title: "Firma",
value: Firma.Name,
width: "10%"
}, {
field: "Bezeichnung",
title: "Projekt",
value: Bezeichnung,
width: "15%",
actions: [{
type: "popup",
recordId: Nr
}, {
type: "change",
recordId: Nr,
field: "A"
}]
}, {
field: "Umsatz",
title: "Umsatz",
value: text(Umsatz + 1000),
width: "20%"
}, {
field: "Aufgaben",
title: "Status Aufgaben",
value: "
",
width: "100px"
}, {
field: "Abgeschlossen",
title: "Abgeschlossen am",
value: text(Abgeschlossen),
width: "100px"
}]
}],
footer: {
showFooter: false,
actionButtonTitle: "",
rightSideContent: "Gesamt: " + cnt(projectList) + " Projekte"
}
};
arcCustomTable(data)
```
### Custom Table Complex
```javascript
let current := this;
arcCustomTable(data);
let list := do as transaction
select Aufgaben
end;
let filteredList := list[if current.Suche != null then
testx(Mitarbeiter.'First Name' + "," + text(Mitarbeiter.'Last Name') + "," +
text(Aufgabe) +
"," +
text(Projekte.Bezeichnung) +
"," +
", "(?:" + current.Suche + ")\.*[^]", "gi")
else
true
end and
if current.'Erledigte einblenden' = true then
true
else
Erledigt != true
end];
let data := {
uniqueListId: "Projektliste A",
tableId: tableId(first(list)),
height: "500px",
theme: "",
groupedBy: text('Gruppieren nach'),
embedded: false,
table: filteredList.[{
recordId: Nr,
rowColor: "",
rowHeight: "60px",
groupRowColor: let currentRecord := this;
if cnt(filteredList[Projekte.Bezeichnung = currentRecord.Projekte.Bezeichnung and Erledigt = true]) = cnt(filteredList[Projekte.Bezeichnung = currentRecord.Projekte.Bezeichnung]) then
"#dcf2de"
else
"#eee"
end,
columns: [{
field: "Erledigt",
title: arcCheckBox({
uniqueId: "checkbox all check",
value: Erledigt,
embedded: true,
clickAction: {
recordId: Nr,
fieldId: "G",
value: if cnt(list[Erledigt = true]) != cnt(list) then
false
else
if cnt(list[Erledigt = null]) = cnt(list) then
null
else
if cnt(list[Erledigt = true]) = cnt(list) then
true
end
end
end
}
}),
value: arcCheckBox({
uniqueId: "checkbox single check",
value: Erledigt,
embedded: true,
clickAction: {
recordId: Nr,
fieldId: "G",
value: if Erledigt = true then null else true end
}
}),
width: "100px",
align: "center",
fixed: "left",
groupValue: arcCustomIcon({
name: "caret-down"
})
}, {
field: "Bild",
title: "Logo",
width: "150px",
value:",
actions: [{
recordId: Projekte.Nr,
type: "popup"
}],
groupValue: "",
}, {
field: "Projekt",
title: "Projekt",
width: "",
value: Projekte.Bezeichnung,
actions: [{
recordId: Projekte.Nr,
type: "popup"
}],
groupValue: Projekte.Bezeichnung,
}, {
field: "Aufgaben",
title: "Aufgabe",
value: Aufgabe,
align: "left",
width: "200px",
actions: [{
recordId: Nr,
type: "popup"
}, {
recordId: Nr,
type: "change",
field: "A"
}],
groupValue: if current.'Gruppieren nach' = 3 then
html(---
**{ Aufgabe }**
---)
end
}, {
field: "Mitarbeiter",
title: "Mitarbeiter",
value:",
actions: [{
recordId: Mitarbeiter.Nr,
type: "popup"
}]
}, {
field: "delete",
title: "",
width: "40px",
align: "center",
value: "",
actions: [{
recordId: Nr,
type: "delete"
}]
}]
}],
footer: {
showFooter: true,
showActionButton: true,
actionButtonTitle: "Neue Aufgabe hinzufügen",
rightSideContent: "Gesamt: " + cnt(filteredList) + " Aufgaben"
}
};
arcCustomTable(data)
```
# Custom Table
## AI Defaults (read first)
- **Column widths**: Every column MUST have explicit `width`. At least one column MUST use `width: "fraction"`.
- **Height**: Use `height: "100%"` (not `calc()`). Especially when `embedded: true`.
- **uniqueListId**: Required, use `"my-table-" + Nr`.
- **tableId**: Required (e.g. from `tableId("Tabellenname")`).
- **recordId**: Always raw `Nr`, NEVER `number(Nr)`.
- **Empty state**: Use `emptyTable: { title: "...", value: "..." }`, do NOT wrap table in if/else.
- **theme.uniqueId**: Must match `uniqueListId`.
- **Columns value**: Each column needs `recordId: Nr` inside the mapping.
- **Row actions**: Use `actions` array with `type: "popup"` or `type: "update"`, recordId = `Nr`.
- **Sort**: Client-side only; `header.columns[n].sort: { enabled: true, type: "text"|"number"|"date" }`; optional `columns[n].sort.value` for sort key when `value` is not plain text. Optional `header.sortIcons: { color, activeColor, hoverColor }` for caret colors (defaults: muted gray / black active / stronger on header hover).
- **Hover**: `actions: [{ type: "hover", fontColor, backgroundColor, ... }]` on table root, row, or column; `type: "hover"` is not passed to click handlers. Legacy `rowHoverAction` still supported.
- **Borders**: Live under `styles.borders`. Default is a rounded frame + row lines, **no vertical cell lines**. Hide the frame with `styles: { borders: { outer: false } }`. Opt into a grid with `columns: true`. Set `styles.borderColor` for dark backgrounds; a line may be `{ color, width }` instead of a boolean.
- **styles hierarchy**: Same `styles` bag on table, header, row, and column — prefer `{ backgroundColor, fontColor, … }` over a CSS string. Table `styles.backgroundColor` is the default surface. A row or column overrides with its own `styles.backgroundColor`. Header uses `header.backgroundColor` / `header.styles`. Do not invent extra props like `rowBackgroundColor`.
# Custom Table
Das **Custom Table**-Widget ermöglicht dir die Darstellung dynamischer, interaktiver Tabellen direkt auf deiner Ninox-Oberfläche – maßgeschneidert nach deinen Anforderungen. Es eignet sich ideal, um strukturierte Daten übersichtlich darzustellen, individuell zu formatieren und mit Aktionen zu verknüpfen (z. B. für Bearbeiten, Löschen, Öffnen von Datensätzen oder API-Aufrufe).
## Beispiel:
## Gesamter Anwendungscode
Im Folgenden siehst du einen beispielhaften Anwendungscode, der die Basis deiner **Custom Table** definiert. Da der Code – je nach Anwendungsfall – sehr umfangreich werden kann, führen wir dich schrittweise **von einer einfachen Basis** zu **komplexeren Varianten**.
Der Aufbau gliedert sich in zwei zentrale Bereiche:
- `**data**` – definiert den Inhalt und die Struktur deiner Tabelle (Zeilen und Spalten)
- `**arcCustomTable()**` – ist die globale Funktion, die das Widget rendert. Ihr übergibst du die `data`
```javascript
let current := this;
let projectList := Artikel;
let data := {
uniqueListId: "beispiel" + Nr,
tableId: "",
height: "500px",
minHeight: "",
groupedBy: "",
groupsCollapsed: false,
theme: arcCustomThemeCleanWhite({
uniqueId: "beispiel"
}),
embedded: false,
rowHoverAction: {
hoverActive: true,
backgroundColor: "",
fontColor: ""
},
header: {
showHeader: true,
height: "",
fontColor: "",
backgroundColor: "",
fontSize: "",
columns: [{
title: "Prio",
width: ""
}]
},
emptyTable: {
title: "Keine Ergebnisse",
backgroundColor: "",
value: ""
},
scrollBar: {
showScrollBar: false,
height: "",
backgroundColor: "",
handle: {
height: "",
borderRadius: "",
backgroundColor: ""
}
},
table: projectList.[{
recordId: Nr,
rowColor: "",
rowHeight: "auto",
rowPaddingY: "10px",
groupRowColor: "",
groupRowSettings: {
height: "",
},
columns: [{
field: "",
title: "",
value: "",
color: "",
backgroundColor: "",
width: "",
align: "left",
paddingX: "",
paddingY: "",
groupExpandAction: false,
groupValue: arcCustomIcon({
name: "caret-down"
}),
groupByValue: "",
actions: [{
type: "popup",
showPopupButton: false,
recordId: Nr
}]
}]
}],
footer: {
showFooter: false,
showActionButton: true,
backgroundColor: "",
actionButtonTitle: "",
leftSideContent: "",
rightSideContent: "Gesamt: " + cnt(projectList) + " Projekte"
}
};
arcCustomTable(data)
```
### uniqueListId
Der Parameter `**uniqueListId**` ist die **individuelle Bezeichnung deiner Tabelle**. Er sorgt dafür, dass deine Tabelle intern eindeutig identifiziert wird – besonders dann, wenn **mehrere Tabellen gleichzeitig auf einer Seite** angezeigt werden.
**Warum ist das wichtig?**
- Style-Einstellungen (z. B. Farben, Schriftarten, Hover-Effekte) werden gezielt nur auf die Tabelle mit der angegebenen `uniqueListId` angewendet.
- Bei mehreren Tabellen auf einer Ansicht kann es sonst zu **Konflikten bei CSS-Klassen oder Zuständen** kommen.
**✅ Best Practice:**
Verwende **sprechende, eindeutige Namen** – am besten in camelCase oder mit Unterstrichen.
```javascript
uniqueListId: "Projektliste Offen", // Text
```
### tableId
Mit `**tableId**` gibst du die **interne ID der Tabelle in Ninox** an, auf die sich das Widget bezieht. Diese ID wird z. B. benötigt, um:
- neue Datensätze über den **„+“-Button** im Footer anzulegen (`create`)
- bestehende Datensätze zu öffnen oder bearbeiten zu können (`popup`, `openFullscreen`, `update`)
- Aktionen korrekt auf Datensätze dieser Tabelle zu beziehen
```javascript
tableId: "AB", // Die ID als Textform
tableId: tableId("Kontakte"), // Ninox Funktion zum Herausfinden der Table ID deiner darzustellenden Tabelle
```
### height
Mit `**height**` bestimmst du die **Höhe des Tabellen-Widgets** in **Pixeln**. So kannst du die Darstellung flexibel an das Layout deiner Seite anpassen – egal, wie viele Daten enthalten sind.
**💡 Werte**
- Der Wert wird in Pixeln angegeben – z. B. `"300px"`, `"500px"` oder `"800px"`.
- `**"auto"**`: Die Höhe passt sich automatisch an den Inhalt an. Perfekt für dynamische Inhalte – beachte aber mögliche Sprünge im Layout.
- In Kombination mit `maxHeight` kannst du die automatische Höhe begrenzen.
```javascript
height: "500px", // Pixel Werte
```
### minWidth
Mit `**minWidth**` legst du die **minimale Breite** deiner Tabelle fest – unabhängig davon, wie viele Spalten oder Daten enthalten sind. So stellst du sicher, dass die Tabelle nicht zu schmal dargestellt wird, z. B. bei schmalen Containern, Tabs oder eingebetteten Ansichten.
🔍 **Format**
- Der Wert wird als **Text mit Einheit** übergeben, z. B. `"600px"`
- Ohne Angabe kann die Tabelle bei zu wenig Inhalt schmal zusammenfallen – was das Layout stören kann.
💡 **Hinweis:**
`minWidth` wirkt sich auf die äußere Tabellenhülle aus – nicht auf die Spaltenbreiten im Inneren. Für Spalten gibt es separate Optionen wie `width` und `minWidth` direkt im `columns`-Block.
### groupedBy
Mit `**groupedBy**` definierst du, nach welchem **Feld (Spalten-Key bzw. **`**field**`**)** deine Tabelle gruppiert werden soll. Gruppen werden dabei visuell als **separate Zeilen mit eigener Formatierung** dargestellt – die darunterliegenden Einträge lassen sich ein- und ausklappen.
🔍 **Verhalten**
- Du gibst hier den **Spaltennamen (**`**field**`**)** an, der in deinem `columns`-Block definiert ist.
- Ist das Feld leer (`"`) oder fehlt ganz, **findet keine Gruppierung statt**.
- Gruppierung kann auch auf komplexen Werten basieren (z. B. `Typ`, `Kategorie`, `Verantwortlicher` etc.).
- Die Gruppen lassen sich dynamisch durch Klick auf die Gruppenzeile **auf- und zuklappen** – dieser Zustand wird **lokal gespeichert**.
```javascript
groupedBy: "", // default: keine Gruppierung ausgewählt
groupedby: "Status", // Text des Feldtitels, nach dem gruppiert werden soll
groupedBy: Gruppierung, // Ninox Feld, das angesprochen wird. In diesem Fall: Ein Auswahlfeld, in dem die Optionen den Titel verschiedener Ninox-felder tragen, nach denen gruppiert werden kann. (z.B. Status, Mitarbeiter, Aufgabe)
```
### groupsCollapsed
Mit `**groupsCollapsed**` legst du fest, ob gruppierte Zeilen **standardmäßig eingeklappt** oder **ausgeklappt** dargestellt werden. Die Gruppenüberschrift (groupRow) ist dabei immer sichtbar – nur die zugehörigen Einträge (valueRows) werden bei Bedarf ein- oder ausgeblendet.
**Dieser Parameter wirkt nur, wenn **`**groupedBy**`** gesetzt ist.**
`**true**` = Gruppen sind beim Laden **eingeklappt** (kompakte Ansicht).
`**false**` = Gruppen sind beim Laden **vollständig geöffnet**.
**Der Zustand (ein-/ausgeklappt) wird lokal gespeichert**, d. h. bei erneutem Öffnen merkt sich das Widget den letzten Zustand pro Benutzer.
**Standardwert: **`**false**`** (Gruppen sind offen)** – wenn nicht angegeben, zeigt die Tabelle alle Gruppeneinträge vollständig an.
```javascript
groupscollapsed: "", // default: false
groupsCollapsed: true,
```
### embedded
Mit `**embedded**` aktivierst du den **eingebetteten Modus** der Tabelle. In diesem Modus passt sich die Tabelle optimal an bestehende Layoutstrukturen an – z. B. in einem Container, Tab oder einem flexiblen UI-Bereich.
**Standardwert: **`**false**` – die Tabelle nimmt dann ihren eigenen, festen Platz auf der Seite ein.
**Wenn **`**embedded: true**`** gesetzt ist, wird das Widget nicht absolut, sondern relativ im Container positioniert** und übernimmt dessen Breite und ggf. auch andere Stilvorgaben. Kombiniert mit Parametern wie `height` und `minWidth` sorgt das für ein sauberes, integriertes Erscheinungsbild.
**Besonders nützlich ist **`**embedded**`** in Dashboards, Tab-Ansichten oder Modalfenstern.**
```javascript
embedded: false,
embedded: true,
embedded: "", // default: false
```
### styles.borders
Rahmen und Gitterlinien leben in **`styles`** — zusammen mit Hintergrund, Radius und Linienfarbe.
Default: abgerundeter Außenrahmen, feine Zeilenlinien, **keine vertikalen Zelllinien**.
Jedes Linienfeld ist `true` / `false` **oder** `{ color, width }`.
| Prop | Default | Bedeutung |
|---|---|---|
| `styles.borderColor` | `#e4e4e7` | Farbe für alle angeschalteten Linien |
| `styles.borderRadius` | `12px` | Eckenradius (nur wenn `outer` an) |
| `styles.borders.outer` | `true` | Außenrahmen. `false` = bündig im Layout |
| `styles.borders.columns` | `false` | Vertikale Linien |
| `styles.borders.rows` | `true` | Horizontale Linien |
| `styles.borders.color` / `width` | — | Gemeinsame Linie, überschreibt `borderColor` / Default-Stärke |
```javascript
styles: {
borderRadius: "12px",
borderColor: "#e4e4e7",
borders: {
outer: true,
columns: false,
rows: true
}
}
// In einem Layout / Card:
styles: { borders: { outer: false } }
// Dunkler Hintergrund — Fläche auf styles, Kopf auf header:
styles: {
backgroundColor: "#2a2822",
fontColor: "#f5f0e6",
borderColor: "#3f3c34"
},
header: {
backgroundColor: "#1c1b16",
fontColor: "#f5f0e6"
}
// Klassisches Gitter:
styles: { borders: { columns: true } }
```
Fertige Varianten (Default, Card, Gitter, flush, Dark): [Custom Table Look](/documentation/custom-table-look).
### rowHoverAction
Mit dem `**rowHoverAction**`-Block bestimmst du, ob das **Hover-Verhalten auf Tabellenzeilen** aktiv sein soll – und falls ja, **welche Farben** beim Überfahren mit der Maus verwendet werden.
- `**hoverActive: true**` aktiviert den Effekt, andernfalls bleibt die Zeile beim Hover unverändert.
- `**backgroundColor**` definiert die **Hintergrundfarbe** der Zeile im Hover-Zustand,
- `**fontColor**` legt die **Textfarbe** während des Hoverns fest.
**Standardwert bei **`**hoverActive**`** ist **`**true**`, falls der Block gesetzt ist. Ohne `rowHoverAction` ist das Verhalten neutral – keine Hover-Effekte.
**Tipp: Setze gedeckte Farben ein**, um den Effekt dezent und UX-freundlich zu halten.
```javascript
rowHoverAction: { hoverActive: true, // wenn hovern an sein soll, und false, wenn nicht
backgroundColor: "#9ca4a9", // default: #f4f6ff
fontColor: "#fff" } // default: #000
```
**Empfehlung:** Für neue Projekte nutze `actions: [{ type: "hover", ... }]` (siehe unten) – `rowHoverAction` bleibt aus Backwards-Compatibility erhalten.
### actions mit type: "hover"
Hover-Styling und optionale Hover-Actions über dasselbe `actions`-Array wie `update` / `popup`. Eintrag mit `**type: "hover"**` wird **nicht** an Klick-Actions weitergegeben, sondern nur vom Widget ausgewertet.
**Merge-Reihenfolge:** `rowHoverAction` (Legacy) → `actions` auf Tabellen-Root → `row.actions` → `columns[n].actions`.
| Sub-Prop | Bedeutung |
|---|---|
| `enabled` | `false` = keine Hover-Hervorhebung für diese Zeile/Zelle. |
| `backgroundColor` | Hintergrundfarbe bei Hover. |
| `fontColor` | Textfarbe bei Hover. |
| `styles` | Zusätzliches CSS (String) für die Zelle bei gehoverter Zeile. |
| `actions` | Optional: bei **mouseenter** an den Action-Handler (z. B. `update`). |
| `leaveActions` | Optional: bei **mouseleave**. |
**Row-Level:** `actions: [{ type: 'hover', backgroundColor: '#eff6ff', fontColor: '#0f172a' }]` auf dem Zeilenobjekt.
**Column-Level:** z. B. `{ type: 'hover', enabled: false }` um eine einzelne Spalte von der Hover-Hervorhebung auszunehmen.
**`row.actions`** (ohne `hover`) – zusätzliche `update`/`popup`-Einträge gelten für die **ganze Zeile** (Klick auf eine Zelle führt Row- und Cell-Actions zusammen aus).
### header
Mit dem ***header***-Block steuerst du die Darstellung deiner **Tabellenkopfzeile** (Spaltenüberschriften).
**Standardverhalten:** Wenn `showHeader` nicht angegeben ist, wird die Header-Zeile **angezeigt**. Ohne weitere Einstellungen gelten Standardwerte für Größe, Farbe und Hintergrund.
Tipp: Wenn du `showHeader: false` setzt, sollte die Bedeutung der Daten trotzdem klar erkennbar bleiben (Position, Farbschema der Spalten).
#### showHeader
Blendet die gesamte Header-Zeile ein oder aus.
```javascript
header: {
showHeader: false, // default: true
}
```
#### height
Höhe der Headerzeile (z. B. `"48px"` oder `"auto"`).
```javascript
header: {
height: "70px", // default: 36px
}
```
#### fontColor
Schriftfarbe der Spaltenüberschriften.
```javascript
header: {
fontColor: "#fff", // default: #000
}
```
#### fontSize
Schriftgröße der Überschriften.
```javascript
header: {
fontSize: "17px", // default: 12px
}
```
#### backgroundColor
Hintergrund der Headerzeile.
```javascript
header: {
backgroundColor: "#3a4a54", // default: #f8f9fc
}
```
#### styles
CSS-String für freies Styling des Header-Containers (überschreibt `fontColor`, `backgroundColor` etc.).
```javascript
header: {
styles: "border-bottom: 1px solid #eee;",
}
```
Vollständiges Beispiel:
```javascript
header: {
showHeader: false, // default: true
height: "70px", // default: 36px
fontColor: "#fff", // default: #52525b
backgroundColor: "#3a4a54", // default: #fafafa
fontSize: "17px", // default: 12px
}
```
### sort (Client-Side)
Sortierung erfolgt **vollständig im Browser** (kein Ninox-Update, kein Helper-Feld). Der Zustand (aktive Spalte, Richtung) wird **intern** verwaltet und wie Scroll/Gruppen im **localStorage** persistiert.
**Header-Spalte** – `sort` aktivieren und Typ setzen:
- `**sort.enabled**`: `true` – Spaltenkopf ist klickbar, zeigt Sort-Icons.
- `**sort.type**`: `'text'` (Standard), `'number'` oder `'date'`.
**Zeilen-Zelle** – optionaler Rohwert für den Vergleich:
- `**sort.value**`: Wert, nach dem sortiert wird. Wenn nicht gesetzt, wird `value` der Zelle verwendet (bei Widgets/HTML in `value` ungeeignet – dann immer `sort.value` setzen).
**Klick-Zyklus:** erste Klick → aufsteigend, zweiter → absteigend, dritter → Sortierung aus.
**Sort-Icons (Outline-Chevrons):** Farben optional über `header.sortIcons` (werden als CSS-Variablen am Header gesetzt):
| Prop | Bedeutung | Standard (CSS-Fallback) |
|------|-----------|-------------------------|
| `color` | Farbe der **inaktiven** Carets | `rgba(0,0,0,0.35)` |
| `activeColor` | Farbe des **aktiven** Carets (aktuelle Sortierrichtung) | `#000000` |
| `hoverColor` | Farbe beider Carets bei **Hover** über den sortierbaren Header (inaktive Carets; aktiver Caret bleibt `activeColor`) | `rgba(0,0,0,0.55)` |
Bei **Gruppierung** (`groupedBy`) wird nur **innerhalb jeder Gruppe** sortiert, nicht über Gruppen hinweg.
```javascript
header: {
showHeader: true,
sortIcons: {
color: 'rgba(0,0,0,0.4)',
activeColor: '#000000',
hoverColor: 'rgba(0,0,0,0.6)'
},
columns: [{
title: 'Name',
width: 'fraction',
sort: { enabled: true, type: 'text' }
}, {
title: 'Betrag',
width: '120px',
sort: { enabled: true, type: 'number' }
}]
},
table: myList.[{
recordId: Nr,
columns: [{
field: 'Name',
value: Name,
width: 'fraction'
}, {
field: 'Betrag',
value: text(Betrag) + ' €',
sort: { value: number(Betrag) },
width: '120px'
}]
}]
```
### emptyTable
Mit dem `**emptyTable**`-Block legst du fest, **was angezeigt werden soll, wenn keine Daten vorhanden sind** – also wenn `data: []` leer ist. Du kannst Text und Gestaltung des leeren Zustands anpassen und so die Nutzererfahrung deutlich verbessern.
- `**title**`: Der Haupttext, der angezeigt wird (meist prominent, z. B. „Keine Einträge gefunden“).
- `**value**`: Optionaler zusätzlicher Text oder HTML-Elemente im Inneren des leeren Bereichs.
- `**backgroundColor**`: Hintergrundfarbe für den leeren Bereich – z. B. `"white"` oder `"#f4f6ff"`.
**Standardverhalten:**
Ohne `emptyTable` wird ein schlichter Text „Keine Ergebnisse“ angezeigt.
💡 **Pro-Tipp:**
Leere Zustände sind keine Fehler – sie sind deine Bühne. Nutze sie für Erklärungen, motivierende Hinweise oder einen klaren Call-to-Action („Jetzt neuen Eintrag erstellen“). So bleiben deine Nutzer nicht im Leeren hängen – im wahrsten Sinne.
```javascript
emptyTable: {
title: "", // Text der bei einer leeren Tabelle in einem abgerundeten Badge dargestellt wird.
backgroundColor: "", // Hintergrundfarbe in HEX angeben
value: "" // Hier kannst du eigene Widgets oder komplexe Ansichten einfügen, die den Title überschreiben.
},
```
### scrollBar
Mit dem `**scrollBar**`-Block konfigurierst du die **horizontale Scrollbar** deiner Tabelle. Diese wird angezeigt, wenn deine Tabelle mehr Spalten enthält, als in den verfügbaren Bereich passen.
- `**showScrollBar**`: `true` oder `false` – bestimmt, ob die Scrollbar überhaupt angezeigt wird.
- `**height**`: Höhe des Scrollbar-Containers (z. B. `"10px"`).
- `**backgroundColor**`: Hintergrundfarbe des Containers.
- `**handle.height**`: Höhe des Schiebers („Handle“) innerhalb der Leiste.
- `**handle.backgroundColor**`: Farbe des Scroll-Handles.
- `**handle.borderRadius**`: Abgerundete Ecken des Schiebers (z. B. `"5px"` oder `"50%"`).
**Standardverhalten:**
Ohne `scrollBar` wird **keine sichtbare Scrollbar angezeigt** – auch wenn Inhalte horizontal überlaufen.
💡 **Pro-Tipp:**
Gerade bei vielen Spalten hilft eine dezente, gut sichtbare Scrollbar, um Orientierung zu geben. Nutze weiche Farben und eine runde Handle-Form, damit die UI nicht „technisch“ wirkt – besonders auf Touch-Geräten zahlt sich das aus.
```javascript
scrollBar: { showScrollbar: true, // default: false (Scrollbar ist standardmäßig ausgeblendet)
height: 40px, // Höhe des Containers. default: 10px
backgroundColor: "#3a4a54" // default: #f0f0f0
handle: { height: "20px", // Höhe des Schiebers. default: 90%
borderRadius: 20px // default: 20px
backgroundColor: "#fff", } // default: #ccc
```
### theme
Mit dem `**theme**`-Parameter kannst du ein **vordefiniertes Design-Template** für deine Tabelle aktivieren. Das Theme beeinflusst das **gesamte visuelle Erscheinungsbild** – von Farben über Schriftarten bis hin zum Layout. Aktuell verfügbar sind:
- `**"clean-white"**`
- `**"naked"**`
**Wichtig:**
Damit das Theme korrekt greift, muss die `theme`-uniqueId **die gleiche **`**uniqueListId**`** verwenden wie deine Tabelle**. Nur so überschreibt das Theme gezielt die richtigen Style-Regeln per CSS.
**Standardverhalten:**
Wird kein `theme` gesetzt, wird das Standarddesign des arcCustomTable-Widgets verwendet (leicht schattiert, kontrastreich).
```javascript
theme: arcCustomThemeCleanWhite({
uniqueId: "Projektliste Demo 1"
}),
```
### styles
Dieselbe `styles`-Tasche auf jeder Ebene. Bevorzugt ein Objekt mit CSS-ähnlichen Namen (`backgroundColor`, `fontColor`, `paddingX`). Ein CSS-String geht weiter.
| Ebene | Prop | Wirkt auf |
|---|---|---|
| Tabelle | `styles: { backgroundColor, borders, … }` | Fläche + Rahmen. Default für alle Zeilen |
| Header | `header: { backgroundColor }` oder `header.styles` | Kopfzeile |
| Header-Zelle | `header.columns[n].styles` | Eine Kopfzelle |
| Zeile | `table: [{ styles: { backgroundColor } }]` | Alle Zellen dieser Zeile |
| Spalte / Zelle | `table: [{ columns: [{ styles: { backgroundColor } }] }]` | Eine Zelle |
| Footer | `footer.styles` | Footer |
Spalte überschreibt Zeile, Zeile überschreibt Tabelle. `styles` gewinnt gegen `rowColor` / flaches `backgroundColor`.
```javascript
styles: {
backgroundColor: "#ffffff",
borderColor: "#e4e4e7",
borders: { outer: true, columns: false, rows: true }
},
header: {
backgroundColor: "#fafafa"
},
table: myList.[{
recordId: Nr,
styles: {
backgroundColor: "#f4f4f5"
},
columns: [{
value: Name,
width: "fraction",
styles: {
fontWeight: "600"
}
}]
}]
```
### footer
Mit dem `**footer**`-Block kannst du einen **unteren Bereich** unterhalb der Tabelle anzeigen lassen – z. B. für Buttons oder Informationen. Er eignet sich ideal für **Aktionsflächen** wie „Neuen Eintrag anlegen“ oder zur Anzeige von Summen, Filtern oder Statusinfos.
- `**showFooter**`: `true` oder `false` – aktiviert oder deaktiviert den Footer.
- `**showActionButton**`: Zeigt den Standard-Button *„Neuen Datensatz erstellen“* an.
- `**actionButtonTitle**`: Individueller Text für den Action-Button.
- `**backgroundColor**`: Hintergrundfarbe des Footers.
- `**leftSideContent**`: Freier Inhalt (z. B. Text, HTML, Icons) für die linke Seite.
- `**rightSideContent**`: Inhalt für die rechte Seite – z. B. Statusanzeigen, Summen oder Infos.
**Standardverhalten:**
Ohne `footer`-Block wird kein Footer angezeigt. Wird `showFooter: true` gesetzt, aber keine weiteren Optionen, erscheint ein leerer Footerbereich.
```javascript
footer: {
showFooter: true,
showActionButton: true,
backgroundColor: "",
actionButtonTitle: "Neue Aufgabe hinzufügen",
leftSideContent: "",
rightSideContent: "Gesamt: " + cnt(filteredList) + " Aufgaben"
}
```
So sieht der oben definierte Footer aus:
## table
Im **Detail-Bereich **`**table**` definierst du alle **Spalten (columns)** und deren **Darstellung, Inhalte und Verhalten**. Du legst hier fest, **welche Datenfelder angezeigt werden sollen**, wie sie aussehen und was beim Klicken passieren soll.
- Jede Spalte kann **individuell formatiert** werden (z. B. Farbe, Ausrichtung, Padding, Aktionen).
- Die hier gesetzten Werte **überschreiben** ggf. globale Einstellungen aus dem `settings`-Block (z. B. `fontColor`, `backgroundColor`, `align` etc.).
- Du kannst hier auch **fixierte Spalten**, **Gruppierungen**, **Interaktionen** und **Inline-Editing** steuern.
## Zeilen- und Gruppenparameter
```javascript
projectList.[{
recordId: Nr,
rowColor: "",
rowHeight: "auto",
rowPaddingY: "10px",
groupRowColor: "",
groupRowSettings: {
height: "",
},
```
- `**recordId**`:
Muss die `**Nr**` des Datensatzes sein (also die interne ID in Ninox).
*Wichtig für die Zuordnung von Aktionen, z. B. Öffnen, Bearbeiten, Löschen.*
- `**rowColor**`:
Setzt die **Hintergrundfarbe** der jeweiligen Zeile.
*Akzeptiert HEX-Werte wie *`*"#f4f6ff"*`* oder *`*"transparent"*`*.*
- `**rowHeight**`:
Bestimmt die **Höhe der Zeile**.
*Wert kann *`*"auto"*`* sein oder eine feste Pixelangabe wie *`*"60px"*`*.*
- `**rowPaddingY**`
→ Vertikales **Innenabstands-Polster** (top/bottom) innerhalb der Zellen dieser Zeile.
Wird auf alle Zellen angewendet, **sofern dort kein individuelles Padding gesetzt ist**.
- `**groupRowColor**`:
Setzt die Hintergrundfarbe für eine **Gruppen-Zeile** (wenn `groupedBy` aktiv ist).
*Du kannst entweder HEX-Werte verwenden oder dynamisch auf Felder zugreifen (z. B. *`*row.farbe*`*).*
- `**groupRowSettings.height**`
→ Legt die **Höhe der Gruppenzeile** fest.
Wert z. B. `"40px"` oder `"auto"`. Wirkt nur, wenn die Zeile eine **Gruppenzeile** ist.
- `**styles**`: CSS-String für freies Styling – wird auf jede Zelle der Zeile angewendet. Langfristiger Ersatz für `rowColor` und `rowHeight`.
💡 **Pro-Tipp:**
Du kannst **dynamisch berechnete Farben** einsetzen, um Status-Feedback direkt sichtbar zu machen – z. B. grün für „alle erledigt“, grau für „in Arbeit“:
```javascript
groupRowColor: if cnt(Firma.Projekte) = cnt(Firma.Projekte[Abgeschlossen != null]) then
"#F0FFF1"
else
"#eee"
end,
```
## Nested rows (`items[]`)
Hierarchical tables use the **same row shape** as flat `table[]`, plus optional nested children on each row.
### Top-level input (either/or)
| Form | Use case |
|------|----------|
| **`table: [...]`** | Classic — existing projects, flat + nested |
| **`items: [...]`** | Greenfield — same row objects, Timeline-style root |
Do **not** set both `table` and root `items` at once. If both are present, `table` wins (dev warning).
Each row may contain **`items: [...]`** for children (unlimited depth). Collapse/expand is **client-side** (persisted in `localStorage` per `uniqueListId`).
### Example — `table[]` with nested children
```javascript
arcCustomTable({
uniqueListId: "tasks-" + Nr,
header: {
columns: [
{ title: " ", width: "40px" },
{ title: "Aufgabe", width: "fraction" },
{ title: "Status", width: "120px" }
]
},
collapsible: {
enabled: true,
expandColumn: 0,
indentColumn: 1,
indentSize: "16px"
},
table: [{
id: "p1",
recordId: Nr,
columns: [
{ value: "" },
{ value: Bezeichnung },
{ value: Status }
],
items: Unteraufgaben.[{
id: format(number(Nr), "0000"),
recordId: Nr,
columns: [ /* same column layout */ ],
items: /* deeper levels */
}]
}]
})
```
### Example — root `items[]`
Same row objects; replace `table:` with `items:` at the root.
### `collapsible`
| Property | Meaning |
|----------|---------|
| `enabled` | `true`: parent rows with children show expand toggle |
| `defaultCollapsed` | `true`: all parent rows start collapsed |
| `expandColumn` | Column index for toggle (default `0`) |
| `indentColumn` | Column index for depth padding (default `1`) |
| `indentSize` | Padding per level, e.g. `"16px"` |
| `iconSize` | Default caret size when no custom icons — e.g. `"16px"` (default) |
| `iconExpand` / `iconCollapse` | Optional nested widget descriptors (e.g. `arcCustomIcon`) — replaces default caret |
**Not combinable with `groupedBy`** in the same table config.
Client-side sort is disabled when nested rows are present — order comes from Ninox (`table` / `items` structure).
### `span` / `colspan` on cells
All rows share the **same number of header columns**. To show a parent row with one wide cell across multiple columns, use **`span`** (alias **`colspan`**) on the cell:
```javascript
// Header: 4 columns (Expand | Name | Status | Date)
columns: [
{ value: "" },
{ value: "Team Nord — 3 members", span: 3 } // 1 + 3 = 4
]
// Child row: four normal cells (span defaults to 1)
columns: [
{ value: "" },
{ value: "Anna M." },
{ value: badgeWidget },
{ value: "14.06.2026" }
]
```
**Invalid:** parent row with 2 `columns` entries and child row with 4 entries **without** `span` — columns will misalign.
Optional **`width`** / **`minWidth`** on a cell still override min-width on that cell; grid tracks come from `header.columns`.
## columns
Im `columns`-Array definierst du die **einzelnen Spalten deiner Tabelle** – also wie sie aussehen, heißen und was darin angezeigt wird. Jede Spalte wird über ein eigenes Objekt innerhalb von `columns` beschrieben.
**Basics, die du einstellen kannst:**
- `**field**`: Das Datenfeld, das angezeigt werden soll – muss zu den Werten in `data.table.columns` passen.
- `**title**`: Der sichtbare Name der Spalte im Header.
- `**width**`: Die Breite der Spalte — fix z. B. `"200px"` / `"10%"`. Für flexible Spalte: `"fraction"`, `"auto"` oder `""` (leer) — gleiche Grid-Logik (`minmax(30px, 1fr)` bzw. gemischt mit fixen Spalten).
- `**align**`: Ausrichtung des Inhalts – `"left"`, `"center"` oder `"right"`.
- `**backgroundColor**`** / **`**color**`: Hintergrund- und Textfarbe der Spalte.
- `**paddingX**`** / **`**paddingY**`: Innenabstände horizontal und vertikal.
- `**truncate**`: Ob der Text abgeschnitten und mit „…“ versehen werden soll.
- `**fixed**`: `"left"` oder `"right"`, um eine Spalte zu fixieren.
- `**styles**`: CSS-String für freies Styling der Zelle (Header-Cell oder Body-Cell). Überschreibt alle anderen Style-Props.
- `**actions**`: Aktionen wie `update`, `popup`, `change`, `openFullscreen`, `delete`.
```javascript
columns: [{
field: "",
title: "",
value: "",
width: "",
align: "",
fixed: "",
paddingX: "",
paddingY: "",
groupExpandAction: "",
groupValue: "",
actions: [{
recordId: "",
type: "",
field: "",
value: ""
}]
}
```
### Gruppen ausklappen mit groupExpandAction
Mit ***groupExpandAction*** kannst du bestimmen, bei welchen Spalten die Funktion des Ausklappens aktiviert sein soll. Das funktioniert nur, wenn du eine Gruppierung in deiner Tabelle eingestellt hast. Aktivierst du es bei mindestens einer Spalte (mit groupExpandAction:true), ist es bei den anderen Spalten automatisch deaktiviert, sofern du es dort nicht auch mit aktivierst in den Parametern.
```javascript
groupExpandAction: true, // Aktiviert das Ausklappen der Tabellenzeilen durch Klick auf die Spalte.
groupExpandAction: false, // Deaktiviert das Ausklappen der Tabellenzeilen durch Klick auf die Spalte.
groupExpandAction: "", // default: true
```
### actions
Mit dem Parameter `**actions**` kannst du festlegen, **was passieren soll, wenn ein Nutzer auf eine Zelle klickt oder diese bearbeitet**. Aktionen werden auf **Zellebene innerhalb von **`**columns**` (in `data.table`) gesetzt und machen deine Tabelle interaktiv.
**💡 Hinweis:** Du kannst **mehrere Aktionen kombinieren**, indem du sie als Array einfügst.
Beispiel:
```javascript
actions: [{
recordId: Nr,
type: "popup"
}, {
recordId: Nr,
type: "change",
field: "A"
}],
```
#### Aktion: popup
Mit `**type: "popup"**` definierst du eine Aktion, die beim Klick auf die Zelle den verknüpften **Datensatz als Popup** öffnet – direkt innerhalb von Ninox. Dadurch können Nutzer Details einsehen oder bearbeiten, ohne die aktuelle Ansicht zu verlassen.
- `**recordId**` muss die `Nr` des jeweiligen Datensatzes sein.
- Diese Aktion gilt **immer für die ganze Zelle**, nicht nur für den Text.
- Du kannst mit `showPopupButton: true` zusätzlich einen Button anzeigen lassen, der den Popup explizit auslöst – nützlich, wenn du Editieren und Öffnen visuell trennen möchtest.
```javascript
actions: [{
recordId: Nr,
type: "popup", // Text. Muss genau so geschrieben werden.
showPopupButton: true, // true oder false zum Ein- oder Ausblenden des Open-Buttons
popupButton: arcCustomButton({
uniqueId: "ButtonProjekt" + Nr,
icon: "",
title: "Open",
fontSize: "13px",
fontColor: "",
iconColor: "",
backgroundColor: "",
borderColor: ""
})
}]
```
Statt die gesamte Zelle klickbar zu machen, kannst du auch einen **individuellen Button innerhalb der Zelle anzeigen lassen** – z. B. mit dem Widget `arcCustomButton`.
Dazu verwendest du:
- `**showPopupButton: true**` – aktiviert die Schaltfläche.
- `**popupButton**` – enthält das gerenderte Button-Element, z. B. per `arcCustomButton()`.
#### Aktion: delete
Mit `**type: "delete"**` kannst du beim Klick auf eine Zelle den zugehörigen Datensatz **löschen**. Die Aktion wirkt sich – wie bei `popup` – **auf die gesamte Zelle aus**.
- `**recordId**` muss auf die `Nr` des Datensatzes zeigen, der gelöscht werden soll.
- Es wird kein zusätzlicher Bestätigungsdialog eingebaut – das Löschen erfolgt direkt.
💡 **Hinweis:** Diese Aktion sollte **nur mit Bedacht** und **klar visualisiert** eingesetzt werden – z. B. durch eine spezielle Icon-Spalte oder einen rot markierten Button innerhalb der Zelle.
```javascript
actions: [{
recordId: Nr,
type: "delete" // Text. Muss genau so geschrieben werden.
}]
```
#### Aktion: update
Mit `**type: "update"**` kannst du beim Klick auf eine Zelle direkt ein **Feld des verknüpften Datensatzes ändern** – ohne Popup, ohne Edit-Modus.
- `**recordId**`: Die `Nr` des Datensatzes, der verändert werden soll.
- `**field**`: Das Feld, das aktualisiert wird (als Text).
- `**value**`: Der neue Wert, der gesetzt werden soll (Text, Zahl, Bool, etc.).
```javascript
actions: [{
recordId: Nr,
type: "update",
field: "G", // Gibt die genaue Field ID des Feldes an, auf das die Aktion angewendet wird.
value: if erledigt=true then null else true end, // Gibt den Wert an, der bei dem referenzierten Feld eingesetzt werden soll.
}]
```
💡 **Pro-Tipp:**
Wenn du das **Löschen nicht direkt**, sondern erst **nach einer Sicherheitsabfrage** durchführen möchtest, kannst du einen kleinen Umweg über ein **Hilfsfeld + Trigger** nehmen:
- Erzeuge ein **Ja/Nein-Feld** namens z. B. `trigger_delete`.
- Füge in der Tabelle eine `update`-Aktion ein, die `trigger_delete` auf `true` setzt.
- Im Trigger dieses Feldes nutzt du folgenden Dialog:
```javascript
if dialog("Eintrag Löschen", "Soll der Eintrag wirklich gelöscht werden?", ["Ja, löschen!", "Abbrechen"]) = "Ja, löschen!" then
delete this
end;
trigger_delete := false
```
#### Aktion: openFullscreen
Mit `**type: "openFullscreen"**` öffnest du den verknüpften Datensatz direkt im **Vollbildmodus** – also so, als würde man ihn klassisch in Ninox vollständig aufrufen.
- `**recordId**`: Die `Nr` des Datensatzes, der geöffnet werden soll.
**Einsatzszenario:**
Wenn du komplexe Datensätze mit vielen Tabs oder Untertabellen hast, ist `openFullscreen` die bessere Wahl gegenüber `popup`.
```javascript
actions: [{
recordId: Nr,
type: "openFullscreen", // Text. Muss genau so geschrieben werden.
}]
```
#### Aktion: openRecord
Mit `**type: "**openRecord**"**` öffnest du das Formular des gegebenen Datensatzes zusammen mit der entsprechenden Tabelle.
- `**recordId**`: Die `Nr` des Datensatzes, der geöffnet werden soll.
```javascript
actions: [{
recordId: Nr,
type: "openRecord",
showPopupButton: true
}]
```
### groupValue
Mit `**groupValue**` definierst du den **Inhalt der Gruppierungszeile** in einer bestimmten Spalte – also das, was in der Zeile angezeigt wird, die z. B. mehrere Datensätze zu einem Projekt, Kunden oder Status bündelt.
- Du kannst `groupValue` **in jeder Spalte** verwenden – auch mehrfach pro Gruppe, wenn gewünscht.
- Du kannst einfachen **Text**, HTML oder auch **Mini-Widgets** einbauen (z. B. Buttons, Layouts oder Statusanzeigen).
- Die Gruppierungszeile wird automatisch angezeigt, wenn `groupedBy` im `settings`-Block gesetzt ist.
```javascript
groupValue: Projekte.Bezeichnung // Ninox-Felder & -Schreibweisen möglich
groupValue: "Projekt:" + Projekte.Bezeichnung // Text + Ninox-Feld
groupValue: arcCustomProgressBar({
uniqueId: "",
width: "",
fontSize: "",
fontColor: "",
backgroundColor: "",
progressColor: "",
valueTotal: "",
valueProgress: "",
valueText: ""
}) // Andere Mini-Widgets
```
### groupByValue
Der `**groupByValue**`-Parameter erlaubt es, deine Tabelle nach **einem anderen Wert als dem angezeigten **`**value**` zu gruppieren. So kannst du die Anzeige der Zelle unabhängig von der Logik der Gruppierung steuern.
- `**value**`: Was der Nutzer in der Zelle sieht (z. B. ein Icon, ein Label, ein HTML-Element).
- `**groupByValue**`: Nach diesem Wert wird die Zeile gruppiert.
**Fallback:**
Wenn `**value**` oder `**groupByValue**` leer ist, wird die Zeile automatisch der Gruppe `**arc-no-value**` zugeordnet.
Diese Gruppe wird ganz normal dargestellt, kann aber auch gezielt angesprochen oder ausgeblendet werden.
```javascript
groupByValue: Projekte.Nr //
groupByValue: Typ // Ninox-Felder
groupByValue: "" // default: es wird nach value gruppiert
```
## Beispiele
Folgend findest du einige Praxisbeispiele, die dir den unterschiedlichen Einsatz der Custom Table veranschaulichen.
### Custom Table Simple
```javascript
let current := this;
let projectList := (select Projekte);
let data := {
uniqueListId: "Projektliste Offen",
tableId: tableId(first(projectList)),
height: "auto",
groupedBy: "",
popupButtonTitle: "Open",
table: projectList.[{
recordId: Nr,
rowColor: "",
groupRowColor: "#eee",
columns: [{
field: "Feldname für Feld-ID",
title: "Titel",
value: "Ninox Wert",
width: "10%"
}, {
field: "Feldname für Feld-ID",
title: "Titel",
value: "Ninox Wert",
width: "15%"
}, {
field: "Feldname für Feld-ID",
title: "Titel",
value: "Ninox Wert",
width: "10%"
}, {
field: "Firma.Name",
title: "Firma",
value: Firma.Name,
width: "10%"
}, {
field: "Bezeichnung",
title: "Projekt",
value: Bezeichnung,
width: "15%",
actions: [{
type: "popup",
recordId: Nr
}, {
type: "change",
recordId: Nr,
field: "A"
}]
}, {
field: "Umsatz",
title: "Umsatz",
value: text(Umsatz + 1000),
width: "20%"
}, {
field: "Aufgaben",
title: "Status Aufgaben",
value: "
",
width: "100px"
}, {
field: "Abgeschlossen",
title: "Abgeschlossen am",
value: text(Abgeschlossen),
width: "100px"
}]
}],
footer: {
showFooter: false,
actionButtonTitle: "",
rightSideContent: "Gesamt: " + cnt(projectList) + " Projekte"
}
};
arcCustomTable(data)
```
### Custom Table Complex
```javascript
let current := this;
arcCustomTable(data);
let list := do as transaction
select Aufgaben
end;
let filteredList := list[if current.Suche != null then
testx(Mitarbeiter.'First Name' + "," + text(Mitarbeiter.'Last Name') + "," +
text(Aufgabe) +
"," +
text(Projekte.Bezeichnung) +
"," +
", "(?:" + current.Suche + ")\.*[^]", "gi")
else
true
end and
if current.'Erledigte einblenden' = true then
true
else
Erledigt != true
end];
let data := {
uniqueListId: "Projektliste A",
tableId: tableId(first(list)),
height: "500px",
theme: "",
groupedBy: text('Gruppieren nach'),
embedded: false,
table: filteredList.[{
recordId: Nr,
rowColor: "",
rowHeight: "60px",
groupRowColor: let currentRecord := this;
if cnt(filteredList[Projekte.Bezeichnung = currentRecord.Projekte.Bezeichnung and Erledigt = true]) = cnt(filteredList[Projekte.Bezeichnung = currentRecord.Projekte.Bezeichnung]) then
"#dcf2de"
else
"#eee"
end,
columns: [{
field: "Erledigt",
title: arcCheckBox({
uniqueId: "checkbox all check",
value: Erledigt,
embedded: true,
clickAction: {
recordId: Nr,
fieldId: "G",
value: if cnt(list[Erledigt = true]) != cnt(list) then
false
else
if cnt(list[Erledigt = null]) = cnt(list) then
null
else
if cnt(list[Erledigt = true]) = cnt(list) then
true
end
end
end
}
}),
value: arcCheckBox({
uniqueId: "checkbox single check",
value: Erledigt,
embedded: true,
clickAction: {
recordId: Nr,
fieldId: "G",
value: if Erledigt = true then null else true end
}
}),
width: "100px",
align: "center",
fixed: "left",
groupValue: arcCustomIcon({
name: "caret-down"
})
}, {
field: "Bild",
title: "Logo",
width: "150px",
value:",
actions: [{
recordId: Projekte.Nr,
type: "popup"
}],
groupValue: "",
}, {
field: "Projekt",
title: "Projekt",
width: "",
value: Projekte.Bezeichnung,
actions: [{
recordId: Projekte.Nr,
type: "popup"
}],
groupValue: Projekte.Bezeichnung,
}, {
field: "Aufgaben",
title: "Aufgabe",
value: Aufgabe,
align: "left",
width: "200px",
actions: [{
recordId: Nr,
type: "popup"
}, {
recordId: Nr,
type: "change",
field: "A"
}],
groupValue: if current.'Gruppieren nach' = 3 then
html(---
**{ Aufgabe }**
---)
end
}, {
field: "Mitarbeiter",
title: "Mitarbeiter",
value:",
actions: [{
recordId: Mitarbeiter.Nr,
type: "popup"
}]
}, {
field: "delete",
title: "",
width: "40px",
align: "center",
value: "",
actions: [{
recordId: Nr,
type: "delete"
}]
}]
}],
footer: {
showFooter: true,
showActionButton: true,
actionButtonTitle: "Neue Aufgabe hinzufügen",
rightSideContent: "Gesamt: " + cnt(filteredList) + " Aufgaben"
}
};
arcCustomTable(data)
```
## Vue
Das `data`-Objekt wird direkt in die Vue-Komponente als Prop übergeben.
```vue
```
---
# Custom Upload
Source: https://www.arc-rider.com/docs/widgets/custom-upload
# Upload in React
Dateien auswählen, Bilder verkleinern und die Ergebnisse an deine Anwendung übergeben. Das Widget führt selbst keinen Backend-Upload durch.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetUpload } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [preview, setPreview] = useState('');
const [name, setName] = useState(t('Keine Datei', 'No file', 'Sin archivo'));
return (
<>
{
setPreview(file.src);
setName(file.name);
}}
/>
{name}
{preview && (
)}
);
}
```
## Features ausprobieren
### Mehrfachauswahl und Bildkonvertierung
Wähle eigene Bilder und vergleiche die Qualitätseinstellungen. Die Dateien werden ausschließlich lokal im Browser verarbeitet.
```tsx
import { useState } from 'react';
import { ArcWidgetUpload } from '@arcrider/arcwidgets-react';
export default function Example() {
const [quality, setQuality] = useState(80);
const [multiple, setMultiple] = useState(true);
const [files, setFiles] = useState<{ name: string; src: string }[]>([]);
return (
<>
setFiles((previous) => [
...previous,
{ name: file.name, src: file.src },
])
}
/>
{files.length} Bilder lokal verarbeitet. Es erfolgt kein Upload auf
einen Server.
{files.map((file, i) => (
{file.name}
))}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetUploadData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onUpload
Eine aufbereitete Datei je Callback.
```typescript
onUpload?: (payload: ArcWidgetUploadPayload) => void | Promise;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### image
Verkleinerung, Bildformat und Qualität.
Typ: `ArcWidgetUploadImage`.
### container
Größe und Beschriftung der Upload-Fläche.
Typ: `ArcWidgetUploadContainer`.
### multiupload
Erlaubt die Auswahl mehrerer Dateien.
Typ: `boolean`.
### capture
Fordert auf unterstützten Geräten die Kamera an.
Typ: `boolean`.
### clipboard
Einfügen aus der Zwischenablage.
Typ: `boolean | { tooltip?: string | { value?: string; position?: string } }`.
### drag
Dateien per Drag & Drop auswählen.
Typ: `boolean | ArcWidgetUploadDrag`.
### logs
Zusätzliche Vorschau und Größeninformationen.
Typ: `boolean`.
### filename
Eigener Name für das Ergebnis.
Typ: `string`.
### showLoadingPopup
Ladeanzeige während der Verarbeitung.
Typ: `boolean`.
### convertSettings
Zusätzliche Konvertierungsoptionen, etwa die Rückgabe des Originals.
Typ: `{ originalFile?: boolean | Record; [key: string]: unknown }`.
## Verhalten und Grenzen
- `onUpload` wird pro Datei aufgerufen und erhält `name`, `src` sowie bei Bildern Abmessungen. `src` ist die aufbereitete Data-URL.
- `image` steuert maximale Bildgröße, Format und Qualität. `multiupload` erlaubt mehrere Dateien.
- Übertrage die Datei im Callback an deine eigene API und behandle Erfolg und Fehler dort. Das Widget liefert keinen fertigen Speicherdienst.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetUploadImage {
width?: number;
height?: number;
format?: 'jpeg' | 'webp' | 'original' | string;
quality?: number;
}
export interface ArcWidgetUploadDrag {
enabled?: boolean;
label?: string;
target?: string;
targetId?: string;
}
export interface ArcWidgetUploadContainer {
height?: string;
width?: string;
label?: string;
icon?: string;
value?: unknown;
}
export interface ArcWidgetUploadData extends ArcWidgetBaseData {
image?: ArcWidgetUploadImage;
container?: ArcWidgetUploadContainer;
multiupload?: boolean;
capture?: boolean;
clipboard?: boolean | { tooltip?: string | { value?: string; position?: string } };
drag?: boolean | ArcWidgetUploadDrag;
logs?: boolean;
filename?: string;
showLoadingPopup?: boolean;
convertSettings?: { originalFile?: boolean | Record; [key: string]: unknown };
}
export interface ArcWidgetUploadPayload {
name: string;
src: string;
width?: number;
height?: number;
original?: string | null;
}
export interface ArcWidgetUploadProps extends ArcReactWidgetProps {
onUpload?: (payload: ArcWidgetUploadPayload) => void | Promise;
}
```
## Einsatzbeispiele
- [Ein Bild annotieren und exportieren](/docs/react/examples/custom-drawing-zeichnen-im-bild-teil1)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Custom Upload
## AI Defaults (read first)
- **uniqueId**: Required, `"upload-" + Nr`.
- **image.tableId**: Required – target table for new records. Ninox-handler only — core emits semantic file payload.
- **image.fieldId**: The text field for Base64 data. Platform-dependent (Web vs. App may differ). Adapter-only.
- **Persistence**: Core emits `upload` with `{ name, src, width?, height?, original? }` where `original` is an optional Base64 string (PDF source when `convertSettings.originalFile` is set). Ninox handler builds `update` / `create` / `popup` from `ui.data.image.*` and resolves `originalFile.fieldId` / `recordId` from `convertSettings`. React: `onUpload(payload)`.
- **container**: `height: "500px"`, `width: "100%"`.
- **multiupload**: Default `false`, set `true` for multiple files at once.
- **capture**: Default `false`, set `true` to open camera directly.
- **clipboard**: Optional `clipboard: true` — Einfügen per Strg/Cmd+V oder Klick, wenn Dateien in der Zwischenablage liegen.
- **drag**: Default **on** for the empty dropzone (hover + drop). Custom `container.value` stays opt-in via `drag: true` or `{ enabled, label?, target?, targetId? }`. `drag: false` opts out.
- **image.format / image.quality**: Optional encode — `format: "jpeg"` | `"webp"` | `"original"`, `quality: 0–1` (default `0.8` when format is set). Offline im Browser; gut für viele Fotos in PDF-Reports.
- **logs**: Optional `logs: true` — Encode-Größen + Bildvorschau (Console + Preview unter dem Widget).
- **Two Base64 fields**: Some setups need separate fields for Web and App – check your schema.
# Custom Upload
Mit `arcCustomUpload` kannst du Bilder und Dateien direkt in Ninox hochladen – einzeln oder als Mehrfachauswahl. Dabei wird automatisch für jede Datei ein eigener Datensatz erzeugt, inklusive Base64-Inhalt, Dateiname und optionalen Zusatzinformationen.
Das Widget löst eine der größten Einschränkungen in Ninox: den umständlichen Mehrfach-Upload. Statt komplizierter Workarounds öffnet sich nun mit einem Klick der Datei-Explorer oder die Kamera – und das **in jeder beliebigen Oberfläche**: ob in einem Dashboard, über einen Custom Button oder innerhalb eines eigenen Layouts.
Die hochgeladenen Bilder landen zunächst als Base64-Text in einem Feld deiner Wahl und können dort:
- direkt mit dem Widget [Custom Image](/documentation/images) angezeigt werden,
- per Skript in ein Ninox-Bildfeld überführt werden (empfohlen),
- oder einfach als Datei abgespeichert werden.
Auch auf **mobilen Geräten** ist das Widget ideal: Du kannst wahlweise per Kamera fotografieren oder mehrere Bilder aus der Galerie auswählen und hochladen. Das spart dem Nutzer viele Klicks und vereinfacht die Datenpflege spürbar.
⚠️ **Hinweis:** Auf der **MacOS App** sowie auf der **Android App** funktioniert aktuell leider die Multi-Upload Funktion nicht. Hier sind die Restriktionen von Ninox Seite her eingeschränkt.
## Unterstützte Formate
- **Bilder**: JPG, PNG, SVG
- **Dokumente**: PDF
- **Tabellen & Daten**: CSV, XML, XLS, XLSX
**Hinweis:** PNG- und SVG-Dateien werden aktuell automatisch in JPG konvertiert. Für hochwertige Weiterverarbeitung empfehlen wir, die Base64-Daten zeitnah in echte Dateien umzuwandeln und als Dateifeld in Ninox zu speichern.
### HEIC/HEIF (iPhone-Fotos)
Moderne iPhones speichern Fotos standardmäßig im **HEIC-Format**. Hier gilt:
| Upload-Methode | Funktioniert? | Erklärung |
|----------------|---------------|-----------|
| **Direkt vom iPhone/iPad** | ✅ Ja | iOS konvertiert automatisch zu JPEG |
| **Desktop → Safari (macOS)** | ✅ Ja | Safari unterstützt HEIC nativ |
| **Desktop → Chrome/Firefox/Edge** | ❌ Nein | Diese Browser können HEIC nicht dekodieren |
💡 **Tipp für Desktop-Uploads:** Falls Nutzer regelmäßig Fotos vom iPhone auf den Desktop übertragen und dort hochladen möchten, empfehlen wir folgende iPhone-Einstellung:
> **Einstellungen → Kamera → Formate → Maximale Kompatibilität**
Damit werden Fotos direkt als JPEG gespeichert und sind mit allen Browsern kompatibel.
## Anwendungscode
Hier ein einfaches Beispiel, wie du `arcCustomUpload` in einer Funktion verwenden kannst – zum Beispiel eingebunden in einer [Tabelle](https://www.arc-rider.de/documentation/custom-table) (`embedded:true`) oder eigenständig auf einem Ninox Formular in einem Formelfeld (`embedded:false`):
```javascript
let current := this;
arcCustomUpload({
uniqueId: "my-Files-" + Nr,
embedded: true,
capture: false,
multiupload: true,
container: {
icon: "",
label: "Files Upload",
height: "500px",
width: "100%",
value: ""
},
image: {
tableId: "B",
fieldId: if ninoxApp() = "web" then
fieldId("Bilder", "base64_web")
else
fieldId("Bilder", "base64_app")
end,
width: 1500,
height: 1500,
widthFieldId: "J",
heightFieldId: "K"
},
filename: {
tableId: "B",
fieldId: fieldId("Bilder", "Dateiname")
},
convertSettings: {
type: ""
},
changeFieldValues: [{
fieldId: "B",
value: number(current.Nr)
}, {
fieldId: "E",
value: 12
}],
setNewRecordId: [{
recordId: current.Nr,
fieldId: fieldId(current.Nr, "triggerField_saveForBrowser")
}]
})
```
## Parameter
### uniqueId
**Typ:** `text`
**Pflichtfeld:** ja
***uniqueId*** vergibst du individuell und sollte einzigartig sein. Sinn dahinter ist: Wenn du mehrere Uploads mit unterschiedlichen Settings auf deiner Oberfläche erstellst, verhinderst du das Überschreiben der Styles.
**📌 Achtung: **Wenn zwei Upload-Widgets auf derselben Seite die gleiche `uniqueId` verwenden, kann das zu Fehlern führen (z. B. werden Uploads überschrieben oder nicht korrekt geladen).
```javascript
uniqueId: "my-Image-" + Nr,
```
### embedded
**Typ:** `boolean`
**Default:** `false`
Mit dem Parameter `embedded` bestimmst du, ob das Upload-Widget **eingebettet in ein bestehendes Element** (z. B. ein `Custom Layout`, `Custom Button`, etc.) angezeigt werden soll – oder ob es als eigenständiges Element auf der Oberfläche steht.
- `true` → Das Widget passt sich dem umgebenden Container an (z. B. bei festen Layout-Rahmen).
- `false` → Das Widget wird frei auf der Ninox-Oberfläche dargestellt (z. B. als alleinstehendes Element).
💡 **Hinweis: **Wenn du `embedded: true` verwendest, achte darauf, dass das umgebende Element (z. B. ein Layout-Block) eine definierte Höhe/Breite hat. Das Upload-Feld übernimmt diese Maße automatisch.
### capture
**Typ:** `boolean`
**Default:** `false`
Mit dem Parameter `capture` steuerst du, ob das Widget auf **mobilen Geräten direkt die Kamera** öffnet oder ob der Nutzer eine Datei manuell auswählen kann.
- `true` → Auf unterstützten Smartphones öffnet sich beim Klick direkt die Kamera-App.
- `false` → Es wird wie gewohnt der Datei-Explorer oder die Fotogalerie geöffnet.
💡 **Hinweis: **Diese Funktion funktioniert nur auf mobilen Geräten (Apple) und in Kombination mit bestimmten Browsern. Auf Desktop wird der Parameter ignoriert.
```javascript
capture: "", // Default: false
capture: false,
```
### multiupload
**Typ:** `boolean`
**Default:** `false`
Mit `multiupload` kannst du festlegen, ob **mehrere Dateien gleichzeitig** hochgeladen werden dürfen.
- `true` → Der Nutzer kann im Dateidialog mehrere Dateien auswählen (z. B. mehrere Bilder aus der Galerie).
- `false` → Es kann nur eine Datei pro Upload-Vorgang hochgeladen werden.
💡 **Tipp: **Besonders praktisch bei Formularen, in denen mehrere Fotos oder Dokumente auf einmal hochgeladen und als einzelne Datensätze gespeichert werden sollen.
### logs
**Typ:** `boolean` oder `{ enabled: true }`
**Default:** `false`
Mit `logs: true` schreibt das Widget **Encode-/Resize-Statistiken** in die Browser-Console (DevTools) und zeigt unter dem Upload eine **Bildvorschau** des Ergebnisses — nützlich zum Kalibrieren von `image.format` und `image.quality`:
- Dateiname und MIME
- Pixel vorher → nachher
- Größe vorher → nachher und Einsparung in %
```javascript
logs: true
```
Beispiel-Zeile:
```text
[arcCustomUpload:…] IMG_1234.JPG image/jpeg → jpeg q=0.7 | 4032×3024→1200×900 | 3.2 MB → 180 KB (−94%)
```
### clipboard
**Typ:** `boolean`
**Default:** `false`
Mit `clipboard: true` können Dateien aus der Zwischenablage eingefügt werden — per **Strg+V / Cmd+V** oder per Klick auf die Upload-Fläche, wenn im Finder/Explorer Dateien kopiert wurden.
- Es erscheint ein Badge-Hinweis, sobald die Zwischenablage **Dateien** (nicht nur Text) enthält.
- Enthält die Zwischenablage nur Text, öffnet ein Klick wie gewohnt den Datei-Dialog.
- Mehrere Upload-Widgets auf einer Seite: reagiert nur das fokussierte Widget.
```javascript
clipboard: true
```
### drag
**Typ:** `boolean` oder `object`
**Default:** aktiv auf der leeren Standard-Dropzone; aus, sobald `container.value` gesetzt ist
Die leere Dropzone (Icon + Label, kein `container.value`) nimmt Dateien per **Drag & Drop** an und zeigt Hover- sowie Drop-Feedback. Mit eigenem `container.value` bleibt Drag opt-in.
`drag: false` schaltet Drop überall aus. `drag: true` oder ein Objekt schaltet es auch für Custom-Layouts ein:
```javascript
drag: true
// oder mit Optionen:
drag: {
enabled: true,
label: "Datei hier ablegen",
target: "area", // "area" | "first-child" | "layout"
targetId: "meine-zeile-id" // optional: externe Drop-Zone per DOM-ID
}
```
| `target` | Verhalten |
|----------|-----------|
| `"area"` | Overlay über der Upload-Fläche |
| `"first-child"` | Standard mit `container.value` |
| `"layout"` | Erstes `arcCustomLayout` im Widget |
Mit `targetId` kann eine **externe Zeile oder Fläche** (z. B. eine Tabellenzeile) als Drop-Zone dienen — die ID wird zuerst im Upload-Label gesucht, sonst im gesamten Dokument.
### showLoadingPopup
**Typ:** `boolean`
**Default:** `false`
Mit `showLoadingPopup` kannst du ein **Loading-Popup während des Uploads** anzeigen lassen. Das ist besonders nützlich bei:
- großen Bilddateien
- langsamen Internetverbindungen
- Multi-Uploads mit vielen Dateien
Das Popup blockiert die Oberfläche und informiert den Nutzer, dass der Upload noch läuft. Es schließt sich automatisch, sobald alle Dateien hochgeladen wurden.
```javascript
showLoadingPopup: true,
```
💡 **Tipp:** Kombiniere `showLoadingPopup: true` mit `multiupload: true` für eine bessere UX bei Massen-Uploads.
Auf der **Ninox iOS App** erscheint das Popup zuverlässig, sobald der Upload startet (das Widget wartet auf die Anzeige des Modals, bevor Dateien verarbeitet werden).
### Block: container{}
**Typ:** `object`
**Optional**
Der `container`-Block definiert das **Erscheinungsbild und Verhalten des Upload-Feldes**. Du kannst hier z. B. die Größe festlegen oder einen eigenen Text im Upload-Bereich anzeigen lassen.
Wenn du keine Werte übergibst, wird ein Standard-Layout mit Upload-Icon und dem Text „Datei auswählen“ angezeigt.
```javascript
container: {
icon: "",
label: "Upload Image",
height: "100%",
value: "wert"
},
```
**Mögliche Parameter**
Feld
Typ
Beschreibung
`label`
`text`
Beschriftung (Text) im Upload-Feld. Wird in der Mitte angezeigt. Wird unter dem Icon angezeigt.
`value`
`widget` `text`
Mit value kannst du dein ganz eigenes Design des Uploads gestalten. Alles, was du bei value angibst, überschriebt das bestehende Standard-Design. Hier kannst du beispielsweise einen einfachen [Custom Button](/documentation/buttons) verwenden oder ein [eigenes Custom Layout](/documentation/custom-layout) gestalten, das sich deiner UI anpasst. Dieser Parameter ist optional und muss natürlich nicht befüllt werden.
`height`
`text`
Höhe des Upload-Feldes, z. B. `"80px"` oder `"100%"`.
`width`
`text`
Breite des Upload-Feldes, z. B. `"100%"`, `"300px"` oder `"auto"`.
`icon`
`widget`
Mit `[arcCustomIcon](https://www.arc-rider.de/documentation/custom-icon)` kann ein individuelles Icon bestimmt werden.
💡 **Tipp: **Vermeide zu lange Texte im `label`, da das Widget zentriert arbeitet und die Lesbarkeit sonst leidet. Ideal sind 1–2 Wörter oder ein Symbol mit kurzer Erklärung
### Block: image{}
**Typ:** `object`
**Pflichtfeld**
Im `image`-Block definierst du, **wohin das hochgeladene Bild gespeichert werden soll**. Das Bild wird automatisch in ein Base64-Textfeld in der angegebenen Tabelle geschrieben. Optional kannst du auch die Bildbreite und -höhe separat erfassen.
Feld
Typ
Beschreibung
`tableId`
`text`
Ziel-Tabelle, in der das Bild als Datensatz gespeichert wird.
`fieldId`
`text`
Feld-ID des Textfelds, in das der Base64-Bildinhalt geschrieben wird.
`widthFieldId`
`text`
*(optional)* Feld-ID für die gespeicherte Bildbreite (in Pixeln). Erstelle dafür ein Ninox-Zahlenfeld.
`heightFieldId`
`text`
*(optional)* Feld-ID für die gespeicherte Bildhöhe (in Pixeln). Erstelle dafür ein Ninox-Zahlenfeld.
`width` / `height`
`text`
*(optional)* Die width / height innerhalb des image{} Blocks gibt die Weite / Höhe deines Bildes in Pixelbreite an, in der du es speichern möchtest.
`format`
`text`
*(optional)* Ausgabeformat nach dem Upload (offline im Browser). `"jpeg"` / `"jpg"`, `"webp"` oder `"original"` (Default: weglassen / `"original"` = bisheriges Verhalten, MIME vom Eingang). Bei `"jpeg"`/`"webp"` wird das Bild immer neu encodiert — auch wenn es schon kleiner als `width`/`height` ist. Der Dateiname erhält die passende Extension (`.jpg` / `.webp`).
`quality`
`number`
*(optional)* Kompressionsqualität von `0` bis `1` (nur bei `format: "jpeg"` oder `"webp"`). Default `0.8`, wenn `format` gesetzt und `quality` fehlt. Gilt **nicht** bei `"original"`.
Die Encode-Schritte laufen **offline direkt im Widget** (Kamera und Galerie gleich). Kein Cloud-Dienst nötig. Hinweis: Bei `format: "jpeg"` geht PNG-Transparenz verloren (bewusst, für Fotos/PDF-Reports).
```javascript
image: {
tableId: "B",
fieldId: if ninoxApp() = "web" then
fieldId("Bilder", "base64_web")
else
fieldId("Bilder", "base64_app")
end,
width: 1500,
height: 1500,
widthFieldId: "J",
heightFieldId: "K"
},
```
**Beispiel Baustelle / PDF-Reports** (viele Fotos, PDF per E-Mail ca. 5–10 MB halten): Kamera (`capture: true`) und Galerie-Mehrfachupload (`multiupload: true`) nutzen denselben Encode-Pfad. Für Ninox/`importFile` eher **JPEG** als WebP:
```javascript
image: {
tableId: "B",
fieldId: if ninoxApp() = "web" then
fieldId("Bilder", "base64_web")
else
fieldId("Bilder", "base64_app")
end,
width: 1200,
height: 1200,
format: "jpeg",
quality: 0.7,
widthFieldId: "J",
heightFieldId: "K"
},
```
Bei sehr vielen Fotos pro Report (60+) `width`/`height` auf `1000` und/oder `quality` auf `0.6` testen. Die finale PDF-Größe hängt auch vom Report-Generator ab — nach dem Setup an einem echten Report kalibrieren.
#### Wichtiger Performance Hinweis
💡 **UI/UX-Tipp: **Base64-Daten können sehr groß werden – besonders bei hochauflösenden Bildern. Daher empfehlen wir folgenden Workflow:
- Hinterlege einen Trigger bei Änderung in dem Base64-Feld.
- Übertrage das Base64-Bild mit `importFile()` in ein echtes Bildfeld.
- Leere das Base64-Feld danach, um Speicherplatz zu sparen.
Diesen Trigger hinterlegst du:
```javascript
Datei := importFile(Nr, base64, Dateiname);
shareURL := shareFile(Datei);
base64:=null;
```
So bleiben Ladezeiten und Datenbankgröße im Rahmen – und du kannst trotzdem direkt mit den Bilddaten weiterarbeiten.
🧠 **Wichtig: **Ninox behandelt Trigger in der App und im Browser unterschiedlich. Damit dein Workflow **plattformübergreifend** zuverlässig funktioniert, nutze **zwei getrennte base64-Felder** (mit jeweils unterschiedlichen Speicher-Optionen) – eines für Web, eines für die App:
- **App** -> Zuweisung pro Datensatz im Browser
- **Web** -> Zuweisung pro Datensatz im Server
✅ So stellst du sicher, dass der Upload in **beiden Umgebungen** automatisch weiterverarbeitet wird.
### filename
**Typ:** `object`
**Optional**
Im `filename`-Block kannst du angeben, **in welchem Feld der Dateiname** gespeichert werden soll. Das ist hilfreich, wenn du später nach Dateien filtern oder sie in Listen anzeigen möchtest.
Feld
Typ
Beschreibung
`tableId`
`text`
Ziel-Tabelle, in der der Datensatz gespeichert wird
`fieldId`
`text`
Feld-ID, in das der Dateiname geschrieben wird
💡 **Tipp: **Falls du später mit `importFile()` weiterarbeitest oder die Datei wieder abrufen willst (z. B. in einer Galerie oder Download-Liste), ist der Dateiname oft notwendig – speichere ihn daher am besten immer mit.
### changeFieldValues
**Typ:** `array of objects`
**Optional**
Mit `changeFieldValues` kannst du **zusätzliche Felder im neu erstellten Upload-Datensatz automatisch befüllen** – z. B. mit einem Bezug zur aktuellen Tabelle, einem festen Typ oder Statuswert. Jeder Eintrag enthält:
Feld
Typ
Beschreibung
`fieldId`
`text`
Das Feld im neuen Datensatz, das gesetzt werden soll
`value`
`any`
Der Wert, der in das Feld geschrieben wird
```javascript
changeFieldValues: [{
fieldId: "B",
value: number(current.Nr)
}, {
fieldId: "E",
value: 10
}]
```
### setNewRecordId
**Typ:** `array of objects`
**Optional**
Mit `setNewRecordId` kannst du nach dem Upload den **neu erstellten Datensatz (z. B. das Bild)** direkt in einem vorhandenen Datensatz **verlinken** – etwa in einem Referenzfeld des aktuellen Formulars.
Das ist besonders nützlich, wenn du:
- eine **1:1-Verknüpfung** zu einem Bild oder Dokument brauchst,
- das Upload-Element **nicht in der Zieltabelle** eingebettet ist,
- oder gezielt Uploads außerhalb der `changeFieldValues` setzen willst.
Feld
Typ
Beschreibung
`recordId`
`text`
Der ID-Wert des bestehenden Datensatzes, in dem verlinkt werden soll
`fieldId`
`text`
Das Referenzfeld, das mit dem neuen Upload-Datensatz gefüllt werden soll
## Extra Konvertierungsservice
Die PDF-Konvertierung über `convertSettings` ist **kein Bestandteil des Standard-Uploads**, sondern ein **externer Service**, der über arcRider bereitgestellt wird.
Da bei jeder Konvertierung **Serverkosten** anfallen, ist die Nutzung **kostenpflichtig**. Die Abrechnung erfolgt **je Konvertierungsvorgang**.
💬 Für die Nutzung des Dienstes erstellen wir individuelle Preispläne – abhängig vom erwarteten Volumen und den konkreten Anforderungen. Bitte kontaktiere uns, wenn du den PDF-Konvertierungsdienst aktivieren möchtest oder Fragen zu den Konditionen hast. ([office@arc-rider.com](mailto:office@arc-rider.com))
### convertSettings
**Typ:** `object`
**Optional – nur bei PDF-Dateien relevant**
Wenn du PDF-Dateien hochlädst, kannst du mit `convertSettings` festlegen, dass sie **automatisch in JPG / PNG / SVG-Dateien umgewandelt** werden – z. B. für technische Zeichnungen oder Formular-PDFs, die in Ninox darstellbar sein sollen.
Feld
Typ
Beschreibung
`fileType`
`text`
Zielformat der Konvertierung. Aktuell unterstützt: `"jpg"`
`apiKey`
`text`
Dein persönlicher API-Schlüssel für den PDF-Konvertierungsdienst (Bitte anfragen bei arcRider)
`width`
`number`
Zielbreite in Pixeln (wenn `dpi` nicht gesetzt ist)
`height`
`number`
Zielhöhe in Pixeln (wenn `dpi` nicht gesetzt ist)
`dpi`
`number`
Auflösung der Konvertierung in **dpi (dots per inch)**
`originalFile`
`object`
Optional: Feld zur Speicherung der originalen PDF-Datei als Base64
## ✅ Fazit
Mit `arcCustomUpload` gestaltest du Upload-Prozesse in Ninox intuitiv, performant und flexibel – egal ob auf Desktop oder mobil. Durch gezielte Parametrierung steuerst du Darstellung, Zieltabellen, Automatisierungen und sogar die Konvertierung von PDFs.
Wenn du komplexe Uploads in dein System integrieren möchtest oder Hilfe beim Setup brauchst, melde dich gerne bei uns – wir unterstützen dich bei der optimalen Konfiguration.
---
# Badges
Source: https://www.arc-rider.com/docs/mini-widgets/badges
# Badge in React
Status oder kurze Kennzeichnungen in Tabellen, Karten und Formularen darstellen.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetBadge } from '@arcrider/arcwidgets-react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
return (
);
}
```
## Features ausprobieren
### Statusfarben und verschachtelte Icons
Wechsle den Status und blende das Icon ein. Beide Werte werden als neue Konfiguration an dasselbe Widget übergeben.
```tsx
import { useState } from 'react';
import { ArcWidgetBadge, ArcWidgetIcon } from '@arcrider/arcwidgets-react';
export default function Example() {
const [state, setState] = useState(0);
const [icon, setIcon] = useState(true);
const states = [
{ title: 'Offen', color: '#a16207' },
{ title: 'In Arbeit', color: '#52525b' },
{ title: 'Erledigt', color: '#15803d' },
];
return (
<>
) : undefined,
}}
/>
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetBadgeData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
Dieses Widget ist eine Darstellungskomponente und stellt keine eigenen Interaktions-Callbacks bereit.
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### value
Anzuzeigender bzw. aktuell bearbeiteter Wert.
Typ: `ArcWidgetSlot`.
### icon
Optionales Symbol bzw. unterstützter Inhaltsslot.
Typ: `ArcWidgetSlot`.
### width
Breite des Widgets als Größenangabe.
Typ: `string`.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### iconPosition
Position des Symbols relativ zur Beschriftung.
Typ: `'left' | 'right' | 0`.
### iconSize
Größe des Symbols.
Typ: `string`.
### iconColor
Farbe des Symbols.
Typ: `string`.
### fontColor
Schriftfarbe.
Typ: `string`.
### fontSize
Schriftgröße als CSS-Wert.
Typ: `string`.
### fontWeight
Schriftstärke.
Typ: `string`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### borderColor
Rahmenfarbe.
Typ: `string`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
### singleColor
Basisfarbe für eine abgestimmte Statusdarstellung.
Typ: `string`.
### paddingX
Innerer Abstand links und rechts.
Typ: `string`.
### paddingY
Innerer Abstand oben und unten.
Typ: `string`.
## Verhalten und Grenzen
- `value` unterstützt Text und JSX. Für einheitliche Statusfarben kannst du `singleColor` setzen oder Hintergrund und Schrift getrennt gestalten.
- Das Badge besitzt keinen eigenen Klick-Callback. Verwende einen umgebenden Button, wenn der Status interaktiv sein soll.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetBadgeData extends ArcWidgetBaseData {
value?: ArcWidgetSlot;
icon?: ArcWidgetSlot;
width?: string;
height?: string;
iconPosition?: 'left' | 'right' | 0;
iconSize?: string;
iconColor?: string;
fontColor?: string;
fontSize?: string;
fontWeight?: string;
backgroundColor?: string;
borderColor?: string;
borderRadius?: string;
singleColor?: string;
paddingX?: string;
paddingY?: string;
}
```
## Einsatzbeispiele
- [Dashboard mit CSS Grid](/docs/react/examples/dashboardansicht-mit-grid)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Badges
## AI Defaults (read first)
- **Function name**: `arcCustomBadge`.
- **value**: The badge text.
- **fontColor**: Text color (NOT `color` or `textColor`).
- **backgroundColor**: Background fill color.
- **borderColor**: Set same as `backgroundColor` for borderless look.
- **No uniqueId needed** for display-only badges.
- **icon** / **value**: May use `arcCustomIcon` or other mini-widgets (not only strings).
# Badge
Das Badge eignet sich, um besondere Merkmale von Datensätzen optisch hervorzuheben. Es kann losgelöst in der Datenbank verwendet oder in anderen Widgets, wie die [Custom Table](/documentation/custom-table), eingesetzt werden.
**icon** und **value** dürfen Mini-Widgets sein (z. B. `icon: arcCustomIcon({ name: "star", iconSize: "14px" })`), nicht nur Text – das Widget rendert sie wie in `arcCustomSelect` oder `arcCustomButton`.
## Anwendungscode
Der folgende Anwendungscode enthält alle möglichen Parameter für dieses Mini-Widget Badge.
```javascript
arcCustomBadge({
uniqueId: "customBadge",
embedded: true,
width: "220px",
icon: "",
iconPosition: "left",
fontSize: "",
fontWeight: "",
borderRadius: "",
singleColor: "",
fontColor: "",
backgroundColor: "",
borderColor: "",
paddingY: "",
paddingX: "",
value: "Löschen"
})
```
## Detaillierte Beschreibung der Parameter
***uniqueId*** vergibst du individuell und sollte einzigartig auf deiner Oberfläche sein. Sinn dahinter ist: Wenn du mehrere Badges mit unterschiedlichen Settings auf deiner Seite erstellst, überschrieben sich die Styles nicht.
```javascript
uniqueId: "",
```
***value*** gibt den Text-Wert in dem Badge aus.
```javascript
value: "Badge-Text" // Fixer Text-Wert in "
value: Projekt.Status // Ninox-Felder / -Berechnungen
```
***width*** gibt die Breite deines Badges an.
```javascript
width: "500px", // Pixel-Werte für festgelegte Breiten.
width: "fit-content", // Passt sich dem Inhalt automatisch an.
```
***iconPosition*** ist die Position des Icons innerhalb des Badges.
```javascript
iconPosition: "left", // Icon erscheint links vom Text.
iconPosition: "right", // Icon erscheint rechts vom Text.
```
***fontSize*** gibt die Schriftgröße des Textes im Badge an.
```javascript
fontSize: "14px", //Pixel-Wert
```
***fontWeight*** bestimmt die Dicke deines Textes.
```javascript
fontWeight: "400", // Zahlen-Wert | 400 entspricht regular
fontWeight: "700", // Zahlen-Wert | 700 entspricht bold
```
***borderRadius*** bestimmt die Abrundung der Ecken vom Badge.
```javascript
borderRadius: "0.3em", // Die Ecken passen sich proportional zur Größe des Badges an.
borderRadius: "4px", // Pixel-Werte für fixe Abrundung.
```
***embedded*** benutzt du, wenn du den Button ***nicht ***innerhalb eines anderen Widgets einsetzt. Standardmäßig ist dies aber auf true gesetzt.
```javascript
embedded: false, // ermöglicht den Standalone Einsatz des Widgets (nicht eingebettet in anderen Widgets)
embedded: true, // Fallback
```
### Eine Farbe mit Abstufungen
Gibst du eine ***singleColor*** an, so passen sich alle weiteren Farben (alle Werte mit Color) automatisch an diesem Wert an. Das heißt du brauchst die folgenden Color-Werte dann nicht mehr ausfüllen.
```javascript
singleColor: "#1D8C96", // HEX-Code für Farben.
```
### Individuelle Farbgestaltung
***fontColor*** gibt die Farbe der Schrift an
```javascript
fontColor: "#1D8C96", // HEX-Code für Farben.
```
***backgroundColor*** gibt die Farbe des Hintergrundes an.
```javascript
backgroundColor: "#1D8C96", // HEX-Code für Farben.
```
***borderColor*** gibt die Farbe der Umrandung an.
```javascript
borderColor: "#1D8C96", // HEX-Code für Farben.
```
## Standard-Werte als Fallback
💡 **Hinweis: **Trägst du keine Werte hinter die Parameter ein, so ist in den meisten Fällen ein Fallback-Wert im System hinterlegt. An manchen Stellen, wie Berechnungsfelder (Tatsächliche Zahlenwerte zum Beispiel) macht das keinen Sinn. In Style-Parametern, wie Farben oder Größen hingegen schon. Hier siehst du den Code ohne eingetragene Werte und in den Kommentaren dahinter die Standard-Werte:
```javascript
arcCustomBadge({
uniqueId: "",
width: "", // Fallback: "fit-content"
icon: "", // Fallback: kein Icon wird angezeigt
iconPosition: "",// Fallback: kein Icon wird angezeigt
fontSize: "", // Fallback: "12px"
fontWeight: "", // Fallback: "400"
borderRadius: "", // Fallback: "0.3em"
singleColor: "", // Fallback: "#3E6FFF"
iconColor: "", // Fallback ist die singleColor
fontColor: "", // Fallback ist die singleColor
backgroundColor: "", // Fallback ist die singleColor
borderColor: "", // Fallback ist die singleColor
value: "", // Kein Fallback
})
```
---
# Button
Source: https://www.arc-rider.com/docs/mini-widgets/buttons
# Button in React
Eine Aktion auslösen und während eines asynchronen Vorgangs einen Ladezustand anzeigen.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetButton } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [status, setStatus] = useState(t('Bereit', 'Ready', 'Listo'));
return (
<>
{
setStatus(t('Speichert …', 'Saving …', 'Guardando …'));
try {
localStorage.setItem('arc-demo-save', new Date().toISOString());
setStatus(
t('Lokal gespeichert', 'Saved locally', 'Guardado en local'),
);
} catch {
setStatus(
t('Speichern fehlgeschlagen', 'Save failed', 'Error al guardar'),
);
}
}}
/>
{status}
);
}
```
## Features ausprobieren
### Asynchron speichern, Ladezustand und Fehler
Speichere mehrfach oder simuliere einen Fehler. Der Button wartet auf das Promise; der Zähler wird nur bei Erfolg erhöht.
```tsx
import { useState } from 'react';
import { ArcWidgetButton, ArcWidgetIcon } from '@arcrider/arcwidgets-react';
export default function Example() {
const [count, setCount] = useState(0);
const [fail, setFail] = useState(false);
const [status, setStatus] = useState('Bereit');
return (
<>
),
backgroundColor: '#18181b',
fontColor: '#ffffff',
showBadge: true,
badgeTitle: String(count),
loading: {
show: true,
minDuration: 600,
indicator: { type: 'spinner' },
},
}}
onClick={async () => {
setStatus('Speichert …');
await new Promise((resolve) => setTimeout(resolve, 800));
if (fail) {
setStatus('Speichern fehlgeschlagen. Erneut versuchen.');
return;
}
setCount((n) => n + 1);
setStatus('Gespeichert');
}}
/>
{status} · Erfolgreich gespeichert: {count}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetButtonData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onClick
Meldet den Klick. Beachte die widgetspezifischen Argumente unten.
```typescript
onClick?: () => void | Promise;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### title
Beschriftung; als Slot auch mit JSX möglich.
Typ: `ArcWidgetSlot`.
### subtitle
Ergänzende Beschriftung.
Typ: `ArcWidgetSlot`.
### icon
Optionales Symbol bzw. unterstützter Inhaltsslot.
Typ: `ArcWidgetSlot`.
### prefix
Inhalt vor der Beschriftung.
Typ: `ArcWidgetSlot`.
### suffix
Inhalt nach der Beschriftung oder Einheit.
Typ: `ArcWidgetSlot`.
### width
Breite des Widgets als Größenangabe.
Typ: `string`.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### fontColor
Schriftfarbe.
Typ: `string`.
### fontSize
Schriftgröße als CSS-Wert.
Typ: `string`.
### showBadge
Blendet die zusätzliche Kennzeichnung ein.
Typ: `boolean`.
### badgeTitle
Inhalt der Kennzeichnung.
Typ: `ArcWidgetSlot`.
### badgeColor
Schriftfarbe der Kennzeichnung.
Typ: `string`.
### badgeBackground
Hintergrund der Kennzeichnung.
Typ: `string`.
### loading
Ladezustand während eines Promise-Callbacks, aktiviert durch `show: true`.
Typ: `ArcWidgetButtonLoading`.
## Verhalten und Grenzen
- `onClick` darf ein Promise zurückgeben. Mit `loading.show: true` bleibt der Ladezustand bis zum Ende dieses Vorgangs aktiv.
- Fange Speicherfehler in deinem Callback ab und zeige sie im eigenen State. Ein Ladeindikator ersetzt keine Erfolgs- oder Fehlermeldung.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetButtonLoading {
show?: boolean;
indicator?: {
type?: 'dots' | 'spinner' | 'pulse' | string;
color?: string;
width?: string;
height?: string;
[key: string]: unknown;
};
hideOnFinish?: boolean;
minDuration?: number;
position?: string;
hideTitle?: boolean;
hideIcon?: boolean;
hide?: {
icon?: boolean | 'auto';
title?: boolean | 'auto';
subtitle?: boolean | 'auto';
badge?: boolean | 'auto';
prefix?: boolean | 'auto';
suffix?: boolean | 'auto';
[key: string]: unknown;
};
overlay?: unknown;
styles?: ArcWidgetStyles | string | 'hover' | 'default';
[key: string]: unknown;
}
export interface ArcWidgetButtonData extends Omit {
title?: ArcWidgetSlot;
subtitle?: ArcWidgetSlot;
icon?: ArcWidgetSlot;
prefix?: ArcWidgetSlot;
suffix?: ArcWidgetSlot;
width?: string;
height?: string;
borderRadius?: string;
backgroundColor?: string;
fontColor?: string;
fontSize?: string;
showBadge?: boolean;
badgeTitle?: ArcWidgetSlot;
badgeColor?: string;
badgeBackground?: string;
loading?: ArcWidgetButtonLoading;
}
export interface ArcWidgetButtonProps extends ArcReactWidgetProps {
onClick?: () => void | Promise;
}
```
## Einsatzbeispiele
- [Status auswählen und speichern](/docs/react/examples/status-als-buttons-ausgeben)
- [Ein Formular in Schritten](/docs/react/examples/datenaufnahme-in-schritten)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Button
## AI Defaults (read first)
- **uniqueId**: Required, e.g. `"btn-save-" + Nr`.
- **title**: Button label (use `""` for icon-only buttons).
- **actions**: Array of `{ type: "update", recordId: Nr, field: fieldId(Nr, "Feld"), value: ... }`. Prefer `type: "update"` over `customJS`.
- **Icon-only button**: Use `arcCustomButton` with `icon: arcCustomIcon({...})`, NOT a layout wrapper with `clickAction`.
- **Nested widgets**: `icon`, `title`, `subtitle`, and badge text (`badgeTitle` with `showBadge: true`) may use `arcCustomIcon`, `arcCustomBadge`, or other mini-widgets – not only strings.
- **prefix / suffix**: Mini-widget slots rendered before (`prefix`) and after (`suffix`) the main content. `suffix` is automatically pushed to the right edge when the button has an explicit `width` (e.g. `"100%"`). Both accept any mini-widget (`arcCustomIcon`, `arcCustomBadge`, `arcCustomLayout`, plain text).
- **loading**: After click, `{ show: true, indicator: { type, color, width, height }, hideOnFinish, minDuration, position, hideTitle, hideIcon, styles }`; set **`overlay`** (`true`, `{ title, message }`, or `{ sequences: [...] }`) for fullscreen overlay. Types: `dots`, `spinner`, `pulse`. In-button loading keeps **hover colors** by default (`styles` omitted or `"hover"`); use `"default"` or a `styles` object to override. **`position`**: `left` / `right` (inline next to content), **`prefix`** / **`suffix`** (pinned to slot — use `suffix` when replacing a chevron on full-width buttons). Use **`loading.hide`** to control per-slot visibility: `{ icon, title, subtitle, badge, prefix, suffix }` — `true` always hides, `false` never, `"auto"` (icon only) hides when on the same side as the indicator. Legacy `hideIcon` / `hideTitle` still work.
- **Badge**: Use flat properties `showBadge`, `badgeTitle`, `badgeColor`, `badgeBackground` – NOT a nested `badge: {}` object.
- **width/height**: Set directly, e.g. `width: "30px"`, `height: "30px"` for icon buttons.
- **borderRadius**: `"50%"` for round buttons, `"8px"` for rounded rectangles.
# Interaktive Buttons
Das Button-Widget ist über ein Config-Objekt steuerbar: Label, Icon, Farben, Loading, Actions.
In Ninox heißt der Einstieg `arcCustomButton({ ... })` — solo im Formelfeld oder eingebettet in Table, Layout, Kanban.
Zusätzlich kannst du Aussehen und Verhalten des Buttons individuell gestalten: Farben, Schriftgrößen, Icons, Abstände, Ausrichtung und Hover-Effekte lassen sich per Konfigurationsobjekt steuern. Auch ein optionales Badge (z. B. zur Anzeige eines Counters) ist integrierbar.
Das Widget eignet sich besonders für:
- **interaktive Dashboards** (z. B. Schnellaktionen wie „neuen Auftrag anlegen“),
- **Kundencockpits** (z. B. „PDF herunterladen“, „Support kontaktieren“),
- **Workflow-Steuerung** (z. B. „Status ändern“, „Nächster Schritt“),
- oder jede andere Stelle, an der du Aktionen visuell zugänglich machen willst.
Wie bei allen arcWidgets erfolgt die Konfiguration direkt über einen Anwendungscode (JSON-Objekt) Formel-Feld solo, bzw. in einem anderen Widget integriert.
## Gesamter Anwendungscode
Folgend siehst du einen beispielhaften Anwendungscode für einen Button:
```javascript
arcCustomButton({
uniqueId: "Button " + Nr,
title: "Neuen Eintrag erstellen",
width: "",
height: "",
alignY: "",
alignX: "",
paddingX: "",
paddingY: "",
gap: "5px",
icon: arcCustomIcon({
name: "plus-bold",
color: "#fff"
}),
iconPosition: "left",
fontSize: "",
fontColor: "#fff",
backgroundColor: "#0062AA",
borderColor: "#0062AA",
borderRadius: "5px",
showBadge: false,
badgeTitle: "",
badgeColor: "",
badgeBackground: "",
badgeBorderColor: "",
badgePosition: "",
badgeGap: "6px",
hoverActions: {
fontColor: "",
iconColor: "",
backgroundColor: "",
borderColor: "",
animation: "0.25s"
},
actions: [{
type: "create",
tableId: "",
popup: true,
changeFieldValues: [{
fieldId: "",
value: ""
}, {
fieldId: "",
value: ""
}]
}]
})
```
## Erklärung einzelner Parameter
Folgend wird dir aufgeschlüsselt, welche Parameter du verwenden kannst und was du jeweils eintragen musst.
### uniqueId (Pflichtfeld)
Die `uniqueId` ist eine eindeutige Kennung des Buttons innerhalb der Seite. Sie wird intern für das Styling (CSS-Selektoren) und zur technischen Identifizierung des Buttons verwendet.
**Typ:** `text`
**Beispiel:** `"create-button-123"` oder `"delete " + Nr`
Diese ID sollte:
- **pro Komponente eindeutig** sein (z. B. durch Kombination aus Text und Datensatz-ID)
- **keine Sonderzeichen oder Leerzeichen** enthalten *(werden intern automatisch durch Bindestriche ersetzt)*
💡** *****Tipp:***** **Wenn du mehrere Buttons auf einer Seite nutzt, z. B. in einer Liste oder Tabelle, empfiehlt sich ein Format wie `"edit-" + Nr` oder `"btn-" + Nr`.
```javascript
uniqueId: Nr,
uniqueId: "Button 1", // Text in "
```
### title
Der `title` bestimmt den sichtbaren Text innerhalb des Buttons. Er sollte kurz und eindeutig formuliert sein, damit Nutzer sofort erkennen, was der Button auslöst.
**Typ:** `text`
**Beispiel:** `"Neuen Eintrag erstellen"` oder `"PDF herunterladen"`
💡** *****Tipp:***** **Wenn du einen reinen Icon-Button erstellen möchtest (z. B. nur ein Plus-Symbol), kannst du `title` einfach auf `"` setzen.
```javascript
title: "",
```
### width
Der Parameter `width` legt fest, wie breit der Button dargestellt wird. Wenn kein Wert angegeben wird, passt sich der Button automatisch dem Inhalt an.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"120px"`, `"100%"`
💡 *Tipp:* Verwende `"100%"`, wenn der Button die gesamte verfügbare Breite des Containers ausfüllen soll – z. B. bei responsiven Layout oder in mobilen Ansichten.
```javascript
width: "100%",// Prozent-Werte in "
width: "100px",// Pixel-Werte in "
```
### height
Der Parameter `height` legt fest, wie hoch der Button dargestellt wird. Wenn kein Wert angegeben wird oder `"auto"` gesetzt ist, richtet sich die Höhe nach dem Inhalt und dem Padding.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"40px"`, `"auto"`
💡 *Tipp:* Eine feste Höhe kann hilfreich sein, wenn du mehrere Buttons nebeneinander gleich hoch darstellen möchtest – z. B. in Toolbars oder Tabellen.
```javascript
height: "100%", // Prozent-Werte in "
height: "100px", // Pixel-Werte in "
height: "", // default: auto
```
### alignY
***alignY*** steuert die vertikale Ausrichtung des Buttons innerhalb seines Containers. Ohne Wert: zentriert.
```javascript
alignY: "top",
alignY: "center", // default
alignY: "bottom",
```
### alignX
***alignX*** steuert die horizontale Ausrichtung des Buttons innerhalb seines Containers. Ohne Wert: zentriert.
```javascript
alignX: "left",
alignX: "center", // default
alignX: "right",
```
### paddingX
***paddingX*** setzt den horizontalen Innenabstand (links/rechts) zum Text bzw. Icon. **Typ:** text (CSS-Einheit, z. B. `px`, `em`, `%`).
```javascript
paddingX: "10px",
paddingX: "1em",
```
Tipp: Mit `paddingX` kannst du die Buttonbreite optisch beeinflussen — unabhängig von `width`.
### paddingY
***paddingY*** setzt den vertikalen Innenabstand (oben/unten). **Typ:** text (CSS-Einheit).
```javascript
paddingY: "6px",
paddingY: "0.5em",
```
Tipp: `paddingY` sorgt für angenehme Klickflächen, besonders auf Touch-Geräten.
### gap
Der Parameter `gap` legt den Abstand zwischen Text und Icon im Inneren des Buttons fest. Wenn kein Wert gesetzt ist, beträgt der Standardabstand `5px`.
**Typ:** *text* (mit CSS-Einheit, z. B. `px`, `em`)
**Beispiel:** `"4px"`, `"0.5em"`, `"8px"`
💡 *Tipp:* Wenn du Buttons mit nur Text oder nur Icon verwendest, kannst du `gap` auch weglassen – relevant wird er nur, wenn beide Elemente vorhanden sind.
```javascript
gap: "10px", // z.B. Pixel-Werte
gap: "", // default: 5px
```
### prefix
Der Parameter `prefix` fügt einen freien Content-Slot **vor** dem Hauptinhalt (Icon + Text) ein. Er akzeptiert alle Mini-Widgets (`arcCustomIcon`, `arcCustomBadge`, `arcCustomLayout`, Plain-Text).
**Typ:** *Mini-Widget oder Text*
**Beispiel:**
```javascript
prefix: arcCustomIcon({ name: "calendar", color: "#888", size: "14px" }),
prefix: arcCustomBadge({ value: "Neu", backgroundColor: "#34C759", fontColor: "#fff", borderColor: "#34C759" }),
prefix: "", // default: kein Prefix
```
💡 *Tipp:* Für Buttons mit `width: "100%"` ist `prefix` ideal für ein Icon oder Badge auf der linken Seite, während `suffix` den rechten Rand besetzt.
### suffix
Der Parameter `suffix` fügt einen freien Content-Slot **nach** dem Hauptinhalt ein. Er wird automatisch an den **rechten Rand** gedrückt, sobald der Button eine explizite Breite hat (z. B. `width: "100%"`). Er akzeptiert alle Mini-Widgets.
**Typ:** *Mini-Widget oder Text*
**Beispiel:**
```javascript
suffix: arcCustomIcon({ name: "chevron-right", color: "#fff", size: "14px" }),
suffix: arcCustomBadge({ value: "Aktuell", backgroundColor: "#34C759", fontColor: "#fff", borderColor: "#34C759" }),
suffix: "", // default: kein Suffix
```
💡 *Tipp:* Klassischer Anwendungsfall — Listenelement-Button mit Text links und Chevron-Icon rechts:
```javascript
arcCustomButton({
uniqueId: "period-btn-" + Nr,
width: "100%",
title: "04.05.2026",
suffix: arcCustomIcon({ name: "chevron-right", color: "#fff", size: "14px" }),
backgroundColor: "#333",
fontColor: "#fff",
actions: [...]
})
```
### icon
Der Parameter `icon` ermöglicht es, dem Button ein beliebiges Icon hinzuzufügen. Das Icon wird mit Hilfe des Widgets [arcCustomIcon](/documentation/custom-icon) erzeugt und kann frei gestaltet werden (Name, Farbe, Größe etc.). Über dein [User Cockpit](https://www.arc-rider.de/documentation/user-cockpit) kannst du deine Wunsch Icons auswählen, die du verwenden möchtest.
**Typ:** *Widget* (`arcCustomIcon`)
**Beispiel:**
```javascript
icon: arcCustomIcon({
name: "plus-bold",
color: "#fff"
}), // arcCustomIcon einsetzen, um Icon einzufügen.
icon: "", // default: Kein Icon wird ausgegeben.
```
💡 *Tipp:* Du kannst den Button auch ohne Text verwenden (`title: "`) und nur über ein Icon darstellen – ideal für kompakte Toolbars oder Symbolleisten.
**title**, **subtitle** und **badgeTitle** (mit `showBadge: true`) können ebenfalls Mini-Widgets sein – z. B. `badgeTitle: arcCustomBadge({ value: "3", ... })` – nicht nur Plain-Text.
### iconPosition
Der Parameter `iconPosition` legt fest, wo das Icon im Verhältnis zum Text angezeigt wird. Wenn kein Wert gesetzt ist, wird das Icon links vom Text dargestellt.
**Typ:** text
**Beispiel: **
```javascript
iconPosition: "left", // Icon erscheint links vom Text.
iconPosition: "right", // Icon erscheint rechts vom Text.
iconPosition: "top", // Icon erscheint oben vom Text.
iconPosition: "buttom", // Icon erscheint unten vom Text.
iconPosition: "", // default: links
```
### fontSize
Der Parameter `fontSize` legt die Schriftgröße des Button-Texts fest. Wird kein Wert gesetzt, beträgt die Standardgröße `13px`.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"14px"`
💡 *Tipp:* Wenn du Buttons in unterschiedlichen Kontexten einsetzt (z. B. in Karten oder Listen), kannst du mit `fontSize` eine visuelle Hierarchie erzeugen – z. B. kleinere Buttons für Nebenaktionen, größere für zentrale Funktionen.
```javascript
fontSize: "18px",// Pixel-Werte in "
```
### fontColor
Der Parameter `fontColor` legt die Farbe des Button-Texts fest. Wenn kein Wert gesetzt ist, wird standardmäßig ein dunkles Grau (`#515971`) verwendet.
**Typ:** *text* (Hex-Code oder CSS-Farbname)
**Beispiel:** `"#ffffff"`, `"black"`, `"rgb(255, 0, 0)"`
💡 *Tipp:* Achte auf ausreichenden Kontrast zur Hintergrundfarbe (`backgroundColor`), um Lesbarkeit und Barrierefreiheit sicherzustellen – besonders bei farbigen Buttons oder dunklen Themes.
```javascript
fontColor: "#ffffff", // HEX-Wert in "
```
### backgroundColor
Der Parameter `backgroundColor` definiert die Hintergrundfarbe des Buttons. Wenn kein Wert angegeben wird, verwendet das Widget standardmäßig ein helles Grau (`#F7F8FC`).
**Typ:** *text* (Hex-Code oder CSS-Farbname)
**Beispiel:** `"#0062AA"`, `"white"`, `"rgba(0, 0, 0, 0.1)"`
💡 *Tipp:* Für eine klare visuelle Rückmeldung bei Aktionen empfiehlt sich ein kräftiger Farbton – ideal in Kombination mit weißer Schrift (`fontColor: "#ffffff"`).
```javascript
backgroundColor: "#4970ff", // HEX-Wert in "
```
### borderColor
Der Parameter `borderColor` legt die Rahmenfarbe des Buttons fest. Wenn kein Wert angegeben wird, wird standardmäßig ein dezentes Hellgrau verwendet (`#E9ECF4`).
**Typ:** *text* (Hex-Code oder CSS-Farbname)
**Beispiel:** `"#0062AA"`, `"transparent"`, `"rgba(0, 0, 0, 0.2)"`
💡 *Tipp:* Wenn du einen vollständig flächigen Button ohne sichtbaren Rahmen gestalten möchtest, kannst du `borderColor` auf `"transparent"` setzen – oder passend zur Hintergrundfarbe.
```javascript
borderColor: "#EEEEEE", // HEX-Wert in "
```
### borderRadius
Der Parameter `borderRadius` bestimmt, wie stark die Ecken des Buttons abgerundet sind. Wird kein Wert gesetzt, verwendet das Widget standardmäßig `3px`.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"0px"` (rechteckig), `"5px"` (leicht abgerundet), `"50px"` (pillenförmig)
💡 *Tipp:* Für moderne UI-Elemente eignen sich leicht abgerundete Ecken (`4–8px`).
```javascript
borderRadius: "50px", // 50px = ganz abgerundet // default Wert sind: 3px
```
### embedded
Der Parameter `embedded` steuert, ob das Widget innerhalb eines anderen Widgets (z. B. in einer Karte oder einem Layout-Container) eingebettet ist.
**Typ:** *boolean* (`true` / `false`)
**Standardwert:** `false`
```javascript
embedded: false, // ermöglicht den Standalone Einsatz des Widgets (nicht eingebettet in anderen Widgets)
embedded: true, // Fallback
```
### Badge
Mit dem Badge-System kannst du dem Button eine kleine Zusatzmarkierung hinzufügen – z. B. einen Zähler, ein Label („Neu“, „!“, „3“), oder ein Symbol für besondere Hinweise. Der Badge wird optisch abgesetzt dargestellt und lässt sich farblich sowie in der Position anpassen.
Parameter
Typ
Beschreibung
`showBadge`
*boolean*
Legt fest, ob ein Badge angezeigt wird (`true` / `false`). Kann auch per Skript bestimmt werden: `if cnt(Dokumente)>0 then true end `
`badgeTitle`
*text*
Text oder Zahl im Badge
`badgeColor`
*text*
Textfarbe im Badge (z. B. `"#ffffff"`)
`badgeBackground`
*text*
Hintergrundfarbe des Badges (z. B. `"#e9595d"`)
`badgeBorderColor`
*text*
Rahmenfarbe des Badges (z. B. `"#ffffff"`)
`badgePosition`
*text*
Zusätzliche Positionierung des Badges *(z. B. *`*"outside"*`* für Darstellung außerhalb des Buttons)*
`badgeGap`
*text*
Abstand zwischen Button-Inhalt und Badge in der Standard-Position (Standard: `"6px"`). Wird bei `badgePosition: "outside"` nicht angewendet.
### hoverActions
Mit `hoverActions` kannst du definieren, wie sich der Button visuell verhält, wenn der Nutzer mit der Maus darüberfährt („Hover-Effekt“). Du kannst damit gezielt Farbe, Rahmen und Animation verändern – sowohl für den Button selbst als auch das Icon.
```javascript
hoverActions: {
fontColor: "#ffffff",
iconColor: "#ffffff",
backgroundColor: "#0062AA",
borderColor: "#0062AA",
animation: "0.1s"
},
```
💡 *Tipp:* Wenn du gar keine Hover-Effekte brauchst, kannst du `hoverActions` komplett weglassen. Wenn dein Button eine **helle Hintergrundfarbe** hat, empfiehlt sich beim Hover ein **dunklerer Farbton** mit **weißem Text**, um Interaktivität und Kontrast zu erhöhen. So wird die Aktion visuell klar erkennbar und barriereärmer.
Feld
Typ
Beschreibung
Beispielwert
`fontColor`
*text*
Textfarbe beim Hover
`"#ffffff"`
`backgroundColor`
*text*
Hintergrundfarbe beim Hover
`"#004C8A"`
`borderColor`
*text*
Rahmenfarbe beim Hover
`"#003366"`
`iconColor`
*text*
Farbe des Icons beim Hover (nur bei SVG-Icons relevant)
`"#ffffff"`
`animation`
*text*
CSS-Transition-Zeit für sanfte Effekte
`"0.25s"`
### actions ✅
Mit dem Parameter `actions` definierst du, was passieren soll, wenn der Button geklickt wird. Du kannst eine oder mehrere Aktionen hinterlegen – von einfachem URL-Öffnen über das Erstellen neuer Datensätze bis hin zu benutzerdefiniertem JavaScript.
**State-Bags:** Für partielle Updates in JSON-Töpfen (`type: "update"`) siehe [`data-bag-actions`](../patterns/data-bag-actions.md) (`dataBag` + `patch` statt gesamtes Feld überschreiben).
**Polling:** Wiederholtes `update` (z. B. Trigger-Feld) mit `polling: { intervalMs, maxAttempts, active }` — siehe [`action-polling`](../patterns/action-polling.md). Passt zu Loading/`sequences.when`.
**Typ:** *Liste von Objekten* (Array mit mindestens einem Action-Objekt)
**Aufbau einer Action: **Jede Action ist ein Objekt mit mindestens dem Feld `type` – je nach Typ sind weitere Felder erforderlich oder optional.
#### Unterstützte Aktionstypen
💡 *Tipp:* Du kannst mehrere Aktionen hintereinander ausführen, indem du sie im Array kombinierst. Die Ausführung erfolgt in der Reihenfolge, in der sie im Array angegeben sind.
### loading
Zeigt nach dem Klick einen Ladezustand an – **im Button** oder als **Overlay** (Backdrop über der ganzen App).
```javascript
loading: {
show: true,
hideOnFinish: true,
minDuration: 300,
indicator: {
type: "dots",
color: "#fff",
width: "60px",
height: "12px"
},
position: "right",
hideTitle: false,
hideIcon: false,
overlay: { /* siehe unten */ }
}
```
| Property | Typ | Default | Beschreibung |
|----------|-----|---------|--------------|
| `show` | boolean | — | Loading aktivieren |
| `hideOnFinish` | boolean | `true` | Nach Ende der Aktionen ausblenden |
| `minDuration` | number (ms) | `0` | Mindest-Anzeigedauer (verhindert Flackern) |
| `indicator` | object | siehe unten | Erscheinungsbild des Lade-Indikators |
| `position` | text | `right` | In-Button only: `left` / `right` (inline next to content), **`prefix`** / **`suffix`** (pinned to slot — `suffix` replaces chevron on full-width buttons; pair with `hide.suffix: true`) |
| `hide` | object | — | Slots beim In-Button-Loading ausblenden – siehe Tabelle unten |
| `hideTitle` | boolean | `false` | *Legacy* – blendet den gesamten Inhaltsbereich aus. Bevorzuge `hide.title` |
| `hideIcon` | boolean | `false` | *Legacy* – blendet Icon aus wenn auf Indicator-Seite. Bevorzuge `hide.icon: "auto"` |
| `styles` | text / object | `hover`* | Nur In-Button: welche Farben während Loading gelten (*Default: `hoverActions`, sonst Normal) |
| `overlay` | boolean / object | — | gesetzt = Overlay-Modus; fehlt = In-Button |
#### hide (In-Button-Loading)
Mit `loading.hide` kannst du einzelne Slots des Buttons während des Ladevorgangs ausblenden.
| Slot | Typ | Beschreibung |
|------|-----|--------------|
| `icon` | boolean / `"auto"` | `true` = immer ausblenden · `false` = nie · `"auto"` = nur wenn Icon auf Indicator-Seite liegt (Legacy-Verhalten von `hideIcon`) |
| `title` | boolean | Text des Buttons ausblenden |
| `subtitle` | boolean | Untertitel ausblenden |
| `badge` | boolean | Badge ausblenden |
| `prefix` | boolean | Prefix-Slot ausblenden |
| `suffix` | boolean | Suffix-Slot ausblenden |
```javascript
loading: {
show: true,
position: "suffix",
hide: {
suffix: true,
},
indicator: { type: "spinner", color: "#fff", width: "18px", height: "18px" }
}
```
💡 *Tipp:* Bei `width: "100%"` mit Chevron rechts: `suffix` + `loading.position: "suffix"` + `hide.suffix: true` — der Spinner sitzt dann exakt an der Stelle des Chevrons, der Text bleibt links.
#### styles (In-Button-Loading)
Während des Ladens bleibt der Button nicht auf `:hover` (Mausbewegung/`pointer-events`), sondern bekommt **fest eingefrorene** Farben – damit Indikator-Farbe zum sichtbaren Zustand passt.
| Wert | Verhalten |
|------|-----------|
| *(weglassen)* oder `"hover"` | `hoverActions` als feste Button-Farben (wenn gesetzt) |
| `"default"` | Normale Button-Farben (`backgroundColor`, `fontColor`, …) |
| `{ backgroundColor, fontColor, borderColor, iconColor }` | Eigene Loading-Farben (gleiche Felder wie `hoverActions`) |
```javascript
loading: {
show: true,
styles: "hover",
indicator: { type: "dots", color: "#fff" }
}
```
#### indicator
Gilt für In-Button und als Basis für Overlay. Kann in `overlay.indicator` und pro Eintrag in `sequences[].indicator` überschrieben werden.
| Feld | Typ | Default | Beschreibung |
|------|-----|---------|--------------|
| `type` | text | `dots` | `dots` (drei Punkte), `spinner` (Kreis), `pulse` (pulsierender Punkt) |
| `color` | text | `#4970ff` | Farbe |
| `width` | text | `60px` (Button) / `60px` (Overlay) | CSS-Breite |
| `height` | text | `12px` (Button) / `14px` (Overlay) | CSS-Höhe |
#### overlay (zusätzlich)
Steuert die **weiße Dialog-Karte** (nicht den Indikator).
| Feld | Typ | Default | Beschreibung |
|------|-----|---------|--------------|
| `width` | text | `300px` | Breite der Overlay-Karte |
| `height` | text | `280px` | Höhe der Overlay-Karte |
| `backgroundColor` | text | `#ffffff` | Hintergrundfarbe der Overlay-Karte |
| `indicator` | object | von `loading.indicator` | Optional anderer Indikator im Overlay |
| `title` | text / object | — | Überschrift (Plain-Text oder `{ value, styles }`) |
| `message` | text / object | — | Beschreibung (Plain-Text oder `{ value, styles }`) |
**`title` und `message`** — wie bei Layout-Blocks: Plain-String oder Objekt mit optionalem CSS (`styles` überschreibt die Default-Klassen `.arc_loading_title` / `.arc_loading_message`):
```javascript
overlay: {
title: { value: "Wird gespeichert…", styles: "font-size: 18px; font-weight: 700; color: #0f766e;" },
message: { value: "Bitte warten.", styles: "font-size: 13px; color: #64748b;" }
}
```
`value` kann auch ein Mini-Widget sein (z. B. `arcCustomText({...})`), nicht nur Text.
#### Overlay-Modi
| `overlay` | Verhalten |
|-----------|-----------|
| `true` | Nur Backdrop + Spinner |
| `{ title, message }` | Feste Meldung (Dialog wie Bestätigung, ohne Buttons) |
| `{ sequences: [...] }` | Dynamische Meldungen (Zeit +/oder Ninox-Booleans) |
#### sequences – kombinierte Timeline
Jede Sequence kann **Zeit** (`after`), **Bedingung** (`when`) oder **beides** haben:
```javascript
overlay: {
width: "320px",
backgroundColor: "#f8fafc",
title: "Einen Moment…",
indicator: { type: "spinner", color: "#3e6fff", width: "32px", height: "32px" },
sequences: [
{ after: 0, title: "Starte…", priority: 5 },
{ after: 800, title: "Verarbeite…", priority: 5 },
{ when: helper_uploading, title: "Upload läuft…", priority: 40, indicator: { type: "pulse" } },
{ after: 3000, when: helper_stillBusy, message: "Noch einen Moment…", priority: 15 }
]
}
```
| Feld (pro Sequence) | Typ | Beschreibung |
|------------------|-----|--------------|
| `after` | number (ms) | optional; ab Overlay-Start |
| `when` | boolean | optional; Ninox-Feld, bei jedem Reload neu |
| `priority` | number | optional; höher = wichtiger bei Überlappung |
| `title` / `message` | text / object | mindestens eines erforderlich; optional `{ value, styles }` |
| `indicator` | object | optional; vollständiges `indicator`-Objekt für diese Sequence (ersetzt/ergänzt `type`, `color`, `width`, `height`) |
**Resolver:** Eine Sequence ist aktiv, wenn Zeit- und Boolean-Bedingung erfüllt sind. Bei mehreren aktiven Sequences gewinnt die höchste `priority`.
**Ninox-Tipp für `when`:** Hilfsfelder (boolean) per Trigger setzen, damit die Formel während langer Aktionen neu berechnet wird und der Overlay-Text wechselt.
### Fazit
Das `arcCustomButton`-Widget ist ein vielseitiges Werkzeug, um Aktionen in deiner Ninox-App sichtbar und interaktiv zu machen – egal ob du einfache Links, komplexe Workflows oder optisch ansprechende Dashboards gestalten möchtest. Dank der flexiblen Gestaltungsmöglichkeiten und des leistungsstarken Aktionssystems lässt sich der Button nahtlos in bestehende Layouts und Komponenten integrieren.
💡 *Pro-Tipp:* In Kombination mit anderen arcWidgets – z. B. `arcCustomText` oder `arcCustomCard` – kannst du komplette UI-Bausteine entwickeln, die sowohl funktional als auch visuell überzeugen.
# Button
## AI Defaults (read first)
- **uniqueId**: Required, e.g. `"btn-save-" + Nr`.
- **title**: Button label (use `""` for icon-only buttons).
- **actions**: Array of `{ type: "update", recordId: Nr, field: fieldId(Nr, "Feld"), value: ... }`. Prefer `type: "update"` over `customJS`.
- **Icon-only button**: Use `arcCustomButton` with `icon: arcCustomIcon({...})`, NOT a layout wrapper with `clickAction`.
- **Nested widgets**: `icon`, `title`, `subtitle`, and badge text (`badgeTitle` with `showBadge: true`) may use `arcCustomIcon`, `arcCustomBadge`, or other mini-widgets – not only strings.
- **prefix / suffix**: Mini-widget slots rendered before (`prefix`) and after (`suffix`) the main content. `suffix` is automatically pushed to the right edge when the button has an explicit `width` (e.g. `"100%"`). Both accept any mini-widget (`arcCustomIcon`, `arcCustomBadge`, `arcCustomLayout`, plain text).
- **loading**: After click, `{ show: true, indicator: { type, color, width, height }, hideOnFinish, minDuration, position, hideTitle, hideIcon, styles }`; set **`overlay`** (`true`, `{ title, message }`, or `{ sequences: [...] }`) for fullscreen overlay. Types: `dots`, `spinner`, `pulse`. In-button loading keeps **hover colors** by default (`styles` omitted or `"hover"`); use `"default"` or a `styles` object to override. **`position`**: `left` / `right` (inline next to content), **`prefix`** / **`suffix`** (pinned to slot — use `suffix` when replacing a chevron on full-width buttons). Use **`loading.hide`** to control per-slot visibility: `{ icon, title, subtitle, badge, prefix, suffix }` — `true` always hides, `false` never, `"auto"` (icon only) hides when on the same side as the indicator. Legacy `hideIcon` / `hideTitle` still work.
- **Badge**: Use flat properties `showBadge`, `badgeTitle`, `badgeColor`, `badgeBackground` – NOT a nested `badge: {}` object.
- **width/height**: Set directly, e.g. `width: "30px"`, `height: "30px"` for icon buttons.
- **borderRadius**: `"50%"` for round buttons, `"8px"` for rounded rectangles.
# Interaktive Buttons
Das Button-Widget ist über ein Config-Objekt steuerbar: Label, Icon, Farben, Loading, Actions.
Zusätzlich kannst du Aussehen und Verhalten des Buttons individuell gestalten: Farben, Schriftgrößen, Icons, Abstände, Ausrichtung und Hover-Effekte lassen sich per Konfigurationsobjekt steuern. Auch ein optionales Badge (z. B. zur Anzeige eines Counters) ist integrierbar.
Das Widget eignet sich besonders für:
- **interaktive Dashboards** (z. B. Schnellaktionen wie „neuen Auftrag anlegen“),
- **Kundencockpits** (z. B. „PDF herunterladen“, „Support kontaktieren“),
- **Workflow-Steuerung** (z. B. „Status ändern“, „Nächster Schritt“),
- oder jede andere Stelle, an der du Aktionen visuell zugänglich machen willst.
Wie bei allen arcWidgets erfolgt die Konfiguration direkt über einen Anwendungscode (JSON-Objekt) Formel-Feld solo, bzw. in einem anderen Widget integriert.
## Gesamter Anwendungscode
Folgend siehst du einen beispielhaften Anwendungscode für einen Button:
```javascript
arcCustomButton({
uniqueId: "Button " + Nr,
title: "Neuen Eintrag erstellen",
width: "",
height: "",
alignY: "",
alignX: "",
paddingX: "",
paddingY: "",
gap: "5px",
icon: arcCustomIcon({
name: "plus-bold",
color: "#fff"
}),
iconPosition: "left",
fontSize: "",
fontColor: "#fff",
backgroundColor: "#0062AA",
borderColor: "#0062AA",
borderRadius: "5px",
showBadge: false,
badgeTitle: "",
badgeColor: "",
badgeBackground: "",
badgeBorderColor: "",
badgePosition: "",
badgeGap: "6px",
hoverActions: {
fontColor: "",
iconColor: "",
backgroundColor: "",
borderColor: "",
animation: "0.25s"
},
actions: [{
type: "create",
tableId: "",
popup: true,
changeFieldValues: [{
fieldId: "",
value: ""
}, {
fieldId: "",
value: ""
}]
}]
})
```
## Erklärung einzelner Parameter
Folgend wird dir aufgeschlüsselt, welche Parameter du verwenden kannst und was du jeweils eintragen musst.
### uniqueId (Pflichtfeld)
Die `uniqueId` ist eine eindeutige Kennung des Buttons innerhalb der Seite. Sie wird intern für das Styling (CSS-Selektoren) und zur technischen Identifizierung des Buttons verwendet.
**Typ:** `text`
**Beispiel:** `"create-button-123"` oder `"delete " + Nr`
Diese ID sollte:
- **pro Komponente eindeutig** sein (z. B. durch Kombination aus Text und Datensatz-ID)
- **keine Sonderzeichen oder Leerzeichen** enthalten *(werden intern automatisch durch Bindestriche ersetzt)*
💡** *****Tipp:***** **Wenn du mehrere Buttons auf einer Seite nutzt, z. B. in einer Liste oder Tabelle, empfiehlt sich ein Format wie `"edit-" + Nr` oder `"btn-" + Nr`.
```javascript
uniqueId: Nr,
uniqueId: "Button 1", // Text in "
```
### title
Der `title` bestimmt den sichtbaren Text innerhalb des Buttons. Er sollte kurz und eindeutig formuliert sein, damit Nutzer sofort erkennen, was der Button auslöst.
**Typ:** `text`
**Beispiel:** `"Neuen Eintrag erstellen"` oder `"PDF herunterladen"`
💡** *****Tipp:***** **Wenn du einen reinen Icon-Button erstellen möchtest (z. B. nur ein Plus-Symbol), kannst du `title` einfach auf `"` setzen.
```javascript
title: "",
```
### width
Der Parameter `width` legt fest, wie breit der Button dargestellt wird. Wenn kein Wert angegeben wird, passt sich der Button automatisch dem Inhalt an.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"120px"`, `"100%"`
💡 *Tipp:* Verwende `"100%"`, wenn der Button die gesamte verfügbare Breite des Containers ausfüllen soll – z. B. bei responsiven Layout oder in mobilen Ansichten.
```javascript
width: "100%",// Prozent-Werte in "
width: "100px",// Pixel-Werte in "
```
### height
Der Parameter `height` legt fest, wie hoch der Button dargestellt wird. Wenn kein Wert angegeben wird oder `"auto"` gesetzt ist, richtet sich die Höhe nach dem Inhalt und dem Padding.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"40px"`, `"auto"`
💡 *Tipp:* Eine feste Höhe kann hilfreich sein, wenn du mehrere Buttons nebeneinander gleich hoch darstellen möchtest – z. B. in Toolbars oder Tabellen.
```javascript
height: "100%", // Prozent-Werte in "
height: "100px", // Pixel-Werte in "
height: "", // default: auto
```
### alignY
***alignY*** steuert die vertikale Ausrichtung des Buttons innerhalb seines Containers. Ohne Wert: zentriert.
```javascript
alignY: "top",
alignY: "center", // default
alignY: "bottom",
```
### alignX
***alignX*** steuert die horizontale Ausrichtung des Buttons innerhalb seines Containers. Ohne Wert: zentriert.
```javascript
alignX: "left",
alignX: "center", // default
alignX: "right",
```
### paddingX
***paddingX*** setzt den horizontalen Innenabstand (links/rechts) zum Text bzw. Icon. **Typ:** text (CSS-Einheit, z. B. `px`, `em`, `%`).
```javascript
paddingX: "10px",
paddingX: "1em",
```
Tipp: Mit `paddingX` kannst du die Buttonbreite optisch beeinflussen — unabhängig von `width`.
### paddingY
***paddingY*** setzt den vertikalen Innenabstand (oben/unten). **Typ:** text (CSS-Einheit).
```javascript
paddingY: "6px",
paddingY: "0.5em",
```
Tipp: `paddingY` sorgt für angenehme Klickflächen, besonders auf Touch-Geräten.
### gap
Der Parameter `gap` legt den Abstand zwischen Text und Icon im Inneren des Buttons fest. Wenn kein Wert gesetzt ist, beträgt der Standardabstand `5px`.
**Typ:** *text* (mit CSS-Einheit, z. B. `px`, `em`)
**Beispiel:** `"4px"`, `"0.5em"`, `"8px"`
💡 *Tipp:* Wenn du Buttons mit nur Text oder nur Icon verwendest, kannst du `gap` auch weglassen – relevant wird er nur, wenn beide Elemente vorhanden sind.
```javascript
gap: "10px", // z.B. Pixel-Werte
gap: "", // default: 5px
```
### prefix
Der Parameter `prefix` fügt einen freien Content-Slot **vor** dem Hauptinhalt (Icon + Text) ein. Er akzeptiert alle Mini-Widgets (`arcCustomIcon`, `arcCustomBadge`, `arcCustomLayout`, Plain-Text).
**Typ:** *Mini-Widget oder Text*
**Beispiel:**
```javascript
prefix: arcCustomIcon({ name: "calendar", color: "#888", size: "14px" }),
prefix: arcCustomBadge({ value: "Neu", backgroundColor: "#34C759", fontColor: "#fff", borderColor: "#34C759" }),
prefix: "", // default: kein Prefix
```
💡 *Tipp:* Für Buttons mit `width: "100%"` ist `prefix` ideal für ein Icon oder Badge auf der linken Seite, während `suffix` den rechten Rand besetzt.
### suffix
Der Parameter `suffix` fügt einen freien Content-Slot **nach** dem Hauptinhalt ein. Er wird automatisch an den **rechten Rand** gedrückt, sobald der Button eine explizite Breite hat (z. B. `width: "100%"`). Er akzeptiert alle Mini-Widgets.
**Typ:** *Mini-Widget oder Text*
**Beispiel:**
```javascript
suffix: arcCustomIcon({ name: "chevron-right", color: "#fff", size: "14px" }),
suffix: arcCustomBadge({ value: "Aktuell", backgroundColor: "#34C759", fontColor: "#fff", borderColor: "#34C759" }),
suffix: "", // default: kein Suffix
```
💡 *Tipp:* Klassischer Anwendungsfall — Listenelement-Button mit Text links und Chevron-Icon rechts:
```javascript
arcCustomButton({
uniqueId: "period-btn-" + Nr,
width: "100%",
title: "04.05.2026",
suffix: arcCustomIcon({ name: "chevron-right", color: "#fff", size: "14px" }),
backgroundColor: "#333",
fontColor: "#fff",
actions: [...]
})
```
### icon
Der Parameter `icon` ermöglicht es, dem Button ein beliebiges Icon hinzuzufügen. Das Icon wird mit Hilfe des Widgets [arcCustomIcon](/documentation/custom-icon) erzeugt und kann frei gestaltet werden (Name, Farbe, Größe etc.). Über dein [User Cockpit](https://www.arc-rider.de/documentation/user-cockpit) kannst du deine Wunsch Icons auswählen, die du verwenden möchtest.
**Typ:** *Widget* (`arcCustomIcon`)
**Beispiel:**
```javascript
icon: arcCustomIcon({
name: "plus-bold",
color: "#fff"
}), // arcCustomIcon einsetzen, um Icon einzufügen.
icon: "", // default: Kein Icon wird ausgegeben.
```
💡 *Tipp:* Du kannst den Button auch ohne Text verwenden (`title: "`) und nur über ein Icon darstellen – ideal für kompakte Toolbars oder Symbolleisten.
**title**, **subtitle** und **badgeTitle** (mit `showBadge: true`) können ebenfalls Mini-Widgets sein – z. B. `badgeTitle: arcCustomBadge({ value: "3", ... })` – nicht nur Plain-Text.
### iconPosition
Der Parameter `iconPosition` legt fest, wo das Icon im Verhältnis zum Text angezeigt wird. Wenn kein Wert gesetzt ist, wird das Icon links vom Text dargestellt.
**Typ:** text
**Beispiel: **
```javascript
iconPosition: "left", // Icon erscheint links vom Text.
iconPosition: "right", // Icon erscheint rechts vom Text.
iconPosition: "top", // Icon erscheint oben vom Text.
iconPosition: "buttom", // Icon erscheint unten vom Text.
iconPosition: "", // default: links
```
### fontSize
Der Parameter `fontSize` legt die Schriftgröße des Button-Texts fest. Wird kein Wert gesetzt, beträgt die Standardgröße `13px`.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"14px"`
💡 *Tipp:* Wenn du Buttons in unterschiedlichen Kontexten einsetzt (z. B. in Karten oder Listen), kannst du mit `fontSize` eine visuelle Hierarchie erzeugen – z. B. kleinere Buttons für Nebenaktionen, größere für zentrale Funktionen.
```javascript
fontSize: "18px",// Pixel-Werte in "
```
### fontColor
Der Parameter `fontColor` legt die Farbe des Button-Texts fest. Wenn kein Wert gesetzt ist, wird standardmäßig ein dunkles Grau (`#515971`) verwendet.
**Typ:** *text* (Hex-Code oder CSS-Farbname)
**Beispiel:** `"#ffffff"`, `"black"`, `"rgb(255, 0, 0)"`
💡 *Tipp:* Achte auf ausreichenden Kontrast zur Hintergrundfarbe (`backgroundColor`), um Lesbarkeit und Barrierefreiheit sicherzustellen – besonders bei farbigen Buttons oder dunklen Themes.
```javascript
fontColor: "#ffffff", // HEX-Wert in "
```
### backgroundColor
Der Parameter `backgroundColor` definiert die Hintergrundfarbe des Buttons. Wenn kein Wert angegeben wird, verwendet das Widget standardmäßig ein helles Grau (`#F7F8FC`).
**Typ:** *text* (Hex-Code oder CSS-Farbname)
**Beispiel:** `"#0062AA"`, `"white"`, `"rgba(0, 0, 0, 0.1)"`
💡 *Tipp:* Für eine klare visuelle Rückmeldung bei Aktionen empfiehlt sich ein kräftiger Farbton – ideal in Kombination mit weißer Schrift (`fontColor: "#ffffff"`).
```javascript
backgroundColor: "#4970ff", // HEX-Wert in "
```
### borderColor
Der Parameter `borderColor` legt die Rahmenfarbe des Buttons fest. Wenn kein Wert angegeben wird, wird standardmäßig ein dezentes Hellgrau verwendet (`#E9ECF4`).
**Typ:** *text* (Hex-Code oder CSS-Farbname)
**Beispiel:** `"#0062AA"`, `"transparent"`, `"rgba(0, 0, 0, 0.2)"`
💡 *Tipp:* Wenn du einen vollständig flächigen Button ohne sichtbaren Rahmen gestalten möchtest, kannst du `borderColor` auf `"transparent"` setzen – oder passend zur Hintergrundfarbe.
```javascript
borderColor: "#EEEEEE", // HEX-Wert in "
```
### borderRadius
Der Parameter `borderRadius` bestimmt, wie stark die Ecken des Buttons abgerundet sind. Wird kein Wert gesetzt, verwendet das Widget standardmäßig `3px`.
**Typ:** *text* (mit CSS-Einheit)
**Beispiel:** `"0px"` (rechteckig), `"5px"` (leicht abgerundet), `"50px"` (pillenförmig)
💡 *Tipp:* Für moderne UI-Elemente eignen sich leicht abgerundete Ecken (`4–8px`).
```javascript
borderRadius: "50px", // 50px = ganz abgerundet // default Wert sind: 3px
```
### embedded
Der Parameter `embedded` steuert, ob das Widget innerhalb eines anderen Widgets (z. B. in einer Karte oder einem Layout-Container) eingebettet ist.
**Typ:** *boolean* (`true` / `false`)
**Standardwert:** `false`
```javascript
embedded: false, // ermöglicht den Standalone Einsatz des Widgets (nicht eingebettet in anderen Widgets)
embedded: true, // Fallback
```
### Badge
Mit dem Badge-System kannst du dem Button eine kleine Zusatzmarkierung hinzufügen – z. B. einen Zähler, ein Label („Neu“, „!“, „3“), oder ein Symbol für besondere Hinweise. Der Badge wird optisch abgesetzt dargestellt und lässt sich farblich sowie in der Position anpassen.
Parameter
Typ
Beschreibung
`showBadge`
*boolean*
Legt fest, ob ein Badge angezeigt wird (`true` / `false`). Kann auch per Skript bestimmt werden: `if cnt(Dokumente)>0 then true end `
`badgeTitle`
*text*
Text oder Zahl im Badge
`badgeColor`
*text*
Textfarbe im Badge (z. B. `"#ffffff"`)
`badgeBackground`
*text*
Hintergrundfarbe des Badges (z. B. `"#e9595d"`)
`badgeBorderColor`
*text*
Rahmenfarbe des Badges (z. B. `"#ffffff"`)
`badgePosition`
*text*
Zusätzliche Positionierung des Badges *(z. B. *`*"outside"*`* für Darstellung außerhalb des Buttons)*
`badgeGap`
*text*
Abstand zwischen Button-Inhalt und Badge in der Standard-Position (Standard: `"6px"`). Wird bei `badgePosition: "outside"` nicht angewendet.
### hoverActions
Mit `hoverActions` kannst du definieren, wie sich der Button visuell verhält, wenn der Nutzer mit der Maus darüberfährt („Hover-Effekt“). Du kannst damit gezielt Farbe, Rahmen und Animation verändern – sowohl für den Button selbst als auch das Icon.
```javascript
hoverActions: {
fontColor: "#ffffff",
iconColor: "#ffffff",
backgroundColor: "#0062AA",
borderColor: "#0062AA",
animation: "0.1s"
},
```
💡 *Tipp:* Wenn du gar keine Hover-Effekte brauchst, kannst du `hoverActions` komplett weglassen. Wenn dein Button eine **helle Hintergrundfarbe** hat, empfiehlt sich beim Hover ein **dunklerer Farbton** mit **weißem Text**, um Interaktivität und Kontrast zu erhöhen. So wird die Aktion visuell klar erkennbar und barriereärmer.
Feld
Typ
Beschreibung
Beispielwert
`fontColor`
*text*
Textfarbe beim Hover
`"#ffffff"`
`backgroundColor`
*text*
Hintergrundfarbe beim Hover
`"#004C8A"`
`borderColor`
*text*
Rahmenfarbe beim Hover
`"#003366"`
`iconColor`
*text*
Farbe des Icons beim Hover (nur bei SVG-Icons relevant)
`"#ffffff"`
`animation`
*text*
CSS-Transition-Zeit für sanfte Effekte
`"0.25s"`
### actions ✅
Mit dem Parameter `actions` definierst du, was passieren soll, wenn der Button geklickt wird. Du kannst eine oder mehrere Aktionen hinterlegen – von einfachem URL-Öffnen über das Erstellen neuer Datensätze bis hin zu benutzerdefiniertem JavaScript.
**State-Bags:** Für partielle Updates in JSON-Töpfen (`type: "update"`) siehe [`data-bag-actions`](../patterns/data-bag-actions.md) (`dataBag` + `patch` statt gesamtes Feld überschreiben).
**Polling:** Wiederholtes `update` (z. B. Trigger-Feld) mit `polling: { intervalMs, maxAttempts, active }` — siehe [`action-polling`](../patterns/action-polling.md). Passt zu Loading/`sequences.when`.
**Typ:** *Liste von Objekten* (Array mit mindestens einem Action-Objekt)
**Aufbau einer Action: **Jede Action ist ein Objekt mit mindestens dem Feld `type` – je nach Typ sind weitere Felder erforderlich oder optional.
#### Unterstützte Aktionstypen
💡 *Tipp:* Du kannst mehrere Aktionen hintereinander ausführen, indem du sie im Array kombinierst. Die Ausführung erfolgt in der Reihenfolge, in der sie im Array angegeben sind.
### loading
Zeigt nach dem Klick einen Ladezustand an – **im Button** oder als **Overlay** (Backdrop über der ganzen App).
```javascript
loading: {
show: true,
hideOnFinish: true,
minDuration: 300,
indicator: {
type: "dots",
color: "#fff",
width: "60px",
height: "12px"
},
position: "right",
hideTitle: false,
hideIcon: false,
overlay: { /* siehe unten */ }
}
```
| Property | Typ | Default | Beschreibung |
|----------|-----|---------|--------------|
| `show` | boolean | — | Loading aktivieren |
| `hideOnFinish` | boolean | `true` | Nach Ende der Aktionen ausblenden |
| `minDuration` | number (ms) | `0` | Mindest-Anzeigedauer (verhindert Flackern) |
| `indicator` | object | siehe unten | Erscheinungsbild des Lade-Indikators |
| `position` | text | `right` | In-Button only: `left` / `right` (inline next to content), **`prefix`** / **`suffix`** (pinned to slot — `suffix` replaces chevron on full-width buttons; pair with `hide.suffix: true`) |
| `hide` | object | — | Slots beim In-Button-Loading ausblenden – siehe Tabelle unten |
| `hideTitle` | boolean | `false` | *Legacy* – blendet den gesamten Inhaltsbereich aus. Bevorzuge `hide.title` |
| `hideIcon` | boolean | `false` | *Legacy* – blendet Icon aus wenn auf Indicator-Seite. Bevorzuge `hide.icon: "auto"` |
| `styles` | text / object | `hover`* | Nur In-Button: welche Farben während Loading gelten (*Default: `hoverActions`, sonst Normal) |
| `overlay` | boolean / object | — | gesetzt = Overlay-Modus; fehlt = In-Button |
#### hide (In-Button-Loading)
Mit `loading.hide` kannst du einzelne Slots des Buttons während des Ladevorgangs ausblenden.
| Slot | Typ | Beschreibung |
|------|-----|--------------|
| `icon` | boolean / `"auto"` | `true` = immer ausblenden · `false` = nie · `"auto"` = nur wenn Icon auf Indicator-Seite liegt (Legacy-Verhalten von `hideIcon`) |
| `title` | boolean | Text des Buttons ausblenden |
| `subtitle` | boolean | Untertitel ausblenden |
| `badge` | boolean | Badge ausblenden |
| `prefix` | boolean | Prefix-Slot ausblenden |
| `suffix` | boolean | Suffix-Slot ausblenden |
```javascript
loading: {
show: true,
position: "suffix",
hide: {
suffix: true,
},
indicator: { type: "spinner", color: "#fff", width: "18px", height: "18px" }
}
```
💡 *Tipp:* Bei `width: "100%"` mit Chevron rechts: `suffix` + `loading.position: "suffix"` + `hide.suffix: true` — der Spinner sitzt dann exakt an der Stelle des Chevrons, der Text bleibt links.
#### styles (In-Button-Loading)
Während des Ladens bleibt der Button nicht auf `:hover` (Mausbewegung/`pointer-events`), sondern bekommt **fest eingefrorene** Farben – damit Indikator-Farbe zum sichtbaren Zustand passt.
| Wert | Verhalten |
|------|-----------|
| *(weglassen)* oder `"hover"` | `hoverActions` als feste Button-Farben (wenn gesetzt) |
| `"default"` | Normale Button-Farben (`backgroundColor`, `fontColor`, …) |
| `{ backgroundColor, fontColor, borderColor, iconColor }` | Eigene Loading-Farben (gleiche Felder wie `hoverActions`) |
```javascript
loading: {
show: true,
styles: "hover",
indicator: { type: "dots", color: "#fff" }
}
```
#### indicator
Gilt für In-Button und als Basis für Overlay. Kann in `overlay.indicator` und pro Eintrag in `sequences[].indicator` überschrieben werden.
| Feld | Typ | Default | Beschreibung |
|------|-----|---------|--------------|
| `type` | text | `dots` | `dots` (drei Punkte), `spinner` (Kreis), `pulse` (pulsierender Punkt) |
| `color` | text | `#4970ff` | Farbe |
| `width` | text | `60px` (Button) / `60px` (Overlay) | CSS-Breite |
| `height` | text | `12px` (Button) / `14px` (Overlay) | CSS-Höhe |
#### overlay (zusätzlich)
Steuert die **weiße Dialog-Karte** (nicht den Indikator).
| Feld | Typ | Default | Beschreibung |
|------|-----|---------|--------------|
| `width` | text | `300px` | Breite der Overlay-Karte |
| `height` | text | `280px` | Höhe der Overlay-Karte |
| `backgroundColor` | text | `#ffffff` | Hintergrundfarbe der Overlay-Karte |
| `indicator` | object | von `loading.indicator` | Optional anderer Indikator im Overlay |
| `title` | text / object | — | Überschrift (Plain-Text oder `{ value, styles }`) |
| `message` | text / object | — | Beschreibung (Plain-Text oder `{ value, styles }`) |
**`title` und `message`** — wie bei Layout-Blocks: Plain-String oder Objekt mit optionalem CSS (`styles` überschreibt die Default-Klassen `.arc_loading_title` / `.arc_loading_message`):
```javascript
overlay: {
title: { value: "Wird gespeichert…", styles: "font-size: 18px; font-weight: 700; color: #0f766e;" },
message: { value: "Bitte warten.", styles: "font-size: 13px; color: #64748b;" }
}
```
`value` kann auch ein Mini-Widget sein (z. B. `arcCustomText({...})`), nicht nur Text.
#### Overlay-Modi
| `overlay` | Verhalten |
|-----------|-----------|
| `true` | Nur Backdrop + Spinner |
| `{ title, message }` | Feste Meldung (Dialog wie Bestätigung, ohne Buttons) |
| `{ sequences: [...] }` | Dynamische Meldungen (Zeit +/oder Ninox-Booleans) |
#### sequences – kombinierte Timeline
Jede Sequence kann **Zeit** (`after`), **Bedingung** (`when`) oder **beides** haben:
```javascript
overlay: {
width: "320px",
backgroundColor: "#f8fafc",
title: "Einen Moment…",
indicator: { type: "spinner", color: "#3e6fff", width: "32px", height: "32px" },
sequences: [
{ after: 0, title: "Starte…", priority: 5 },
{ after: 800, title: "Verarbeite…", priority: 5 },
{ when: helper_uploading, title: "Upload läuft…", priority: 40, indicator: { type: "pulse" } },
{ after: 3000, when: helper_stillBusy, message: "Noch einen Moment…", priority: 15 }
]
}
```
| Feld (pro Sequence) | Typ | Beschreibung |
|------------------|-----|--------------|
| `after` | number (ms) | optional; ab Overlay-Start |
| `when` | boolean | optional; Ninox-Feld, bei jedem Reload neu |
| `priority` | number | optional; höher = wichtiger bei Überlappung |
| `title` / `message` | text / object | mindestens eines erforderlich; optional `{ value, styles }` |
| `indicator` | object | optional; vollständiges `indicator`-Objekt für diese Sequence (ersetzt/ergänzt `type`, `color`, `width`, `height`) |
**Resolver:** Eine Sequence ist aktiv, wenn Zeit- und Boolean-Bedingung erfüllt sind. Bei mehreren aktiven Sequences gewinnt die höchste `priority`.
## Vue
Das `data`-Objekt wird als Prop an die Vue-Komponente übergeben.
```vue
```
---
# Cards
Source: https://www.arc-rider.com/docs/mini-widgets/cards
# Cards
## AI Defaults (read first)
- **Function name**: `arcCustomCard`.
- **uniqueId**: Required when using actions, e.g. `"card-" + Nr`.
- **title**, **subtitle**, **value**: Main content properties.
- **Use inside arcCustomLayout blocks**: Set `clickAction` on the block, not the card, for navigation.
- **No `else "" end`**: Omit else branches for optional content.
# Custom Cards
Die Custom Cards kannst du entweder einzeln in Formel-Felder verwenden oder in komplexere Oberflächen mit[ Custom Layout ](/documentation/custom-layout)integrieren. Der Vorteil bei dem Layout ist der, dass du die Card innerhalb der Blocks klickbar machen kannst und so auf andere Tabellen, bzw. Datensätze verlinken kannst.
## Anwendungscode
```javascript
let data := {
uniqueId: "",
width: "",
height: "",
borderRadius: "",
icon: arcCustomIcon({
name: "",
containerSize: "",
borderSize: "",
borderColor: "",
iconSize: "",
borderRadius: "",
color: "",
backgroundColor: "",
}),
borderColor: "",
borderWidth: "",
backgroundColor:",
paddingY: "",
paddingX: "",
title: "",
value: ""
};
arcCustomCard(data)
```
## Erklärung einzelner Parameter
***width*** gibt die Breite deiner Card an.
```javascript
width: "100%", // 100% füllt die gesamte Breite des Formelfeldes aus.
width: "200px", // Pixel-Wert definiert fixe Breite
```
***height*** definiert die Höhe der Karte.
```javascript
height: "100%", // 100% füllt die gesamte Höhe des Formelfeldes aus.
height: "200px", // Pixel-Wert definiert fixe Höhe
```
***borderRadius*** definiert die Abrundungen der Ecken.
```javascript
borderRadius: "15px",
```
***icon*** wird in der Karte oben links dargestellt. Dieses kannst du ausgeben, musst du aber nicht. Ein Icon kannst du mit dem [Mini-Widget customIcon](/documentation/custom-icon) definieren. Hier kannst du nur das Icon ausgeben lassen oder auch mit Hintergrundfarben arbeiten.
```javascript
icon: arcCustomIcon({
name: "",
containerSize: "",
borderSize: "",
borderColor: "",
iconSize: "",
borderRadius: "",
color: "",
backgroundColor: ""
})
```
***title*** definiert den Titel und deiner Karte.
```javascript
title: "Mitarbeiter", // Text in "
title: Mitarbeiter.Name, // Ninox-Refrenz-Feld in Text Form
```
***value*** definiert den Body deiner Karte. Hier kannst du entweder mit text arbeiten oder aber andere Mini-Widgets verwenden, wie etwa [eine Progress Bar](/documentation/progress-bar).
```javascript
value: "Subtitel", // Text in "
value: Mitarbeiter.Info // Ninox-Refrenz-Feld in Text Form
value: arcCustomProgressBar({
uniqueId: "",
width: "",
fontSize: "",
fontColor: "",
backgroundColor: "",
progressColor: "",
valueTotal: "",
valueProgress: "",
valueText: ""
}), // Andere Widgets oder Mini-Widgets einsetzen
```
## Standard Werte als Fallback
```javascript
let data := {
uniqueId: "",
width: "", // Fallback: 100%
height: "", // Fallback: auto
borderRadius: "", // Fallback: 15px
icon: "",
title: "Titel",
value: "Lorem Ipsum is simply dummy text Lorem Ipsum is simply dummy text"
};
arcCustomCard(data)
```
---
# Chart Circle
Source: https://www.arc-rider.com/docs/mini-widgets/chart-circle
# Chart Circle
## AI Defaults (read first)
- **Function name**: `arcCustomChartCircle`.
- **value**: Percentage (0–100), as number.
- **size**: Circle diameter, e.g. `"120px"`.
- **strokeWidth**: Ring thickness, e.g. `"10"`.
- **color**: Fill color for the progress arc.
- **backgroundColor**: Background ring color.
- **No uniqueId needed** for display-only charts.
# arcCustomChartCircle
Das Widget `arcCustomChartCircle` ermöglicht die Visualisierung von Kreisdiagrammen (Pie- und Donut-Charts) direkt in deiner Ninox-Datenbank. Ob als Übersicht über Lagerbestände, Verteilungen, Auslastungen oder Projektanteile – dieses Widget bringt deine Daten in ansprechender, interaktiver Form auf die Oberfläche.
Dank flexibler Parameter lässt sich das Design des Charts präzise anpassen: Farben, Größen, Legenden, zentrale Beschriftung, Abstand zwischen Segmenten und vieles mehr. Du kannst mehrere Charts gleichzeitig darstellen – mit jeweils eigener Konfiguration, ohne dass sie sich gegenseitig beeinflussen.
**Use Cases:**
- Lagerkapazitäten & Auslastungen visualisieren
- Projektanteile oder Auftragsverteilungen zeigen
- Vergleich von Soll-/Ist-Werten in grafischer Form
- Dynamische Dashboards mit mehreren Kreisdiagrammen aufbauen
Das Widget funktioniert sowohl eingebettet in andere Komponenten als auch als eigenständiges Element. Dank der `uniqueId` bleibt jede Instanz klar unterscheidbar.
## uniqueId
Die `uniqueId` ist ein Pflichtfeld und sorgt dafür, dass jedes Diagramm eindeutig auf deiner Oberfläche erkannt wird. Das ist besonders wichtig, wenn du mehrere `arcCustomChartCircle`-Widgets gleichzeitig anzeigst – nur so bleiben Layout und Farben getrennt und überschreiben sich nicht gegenseitig.
💡 Tipp: Verwende eine Kombination aus statischem Text und einem eindeutigen Feld (z. B. `Nr`), um die ID automatisch pro Datensatz zu erzeugen.
```javascript
uniqueId: Nr, // Ninox-Feld
uniqueId: "Aufgabe Beschreibung", // Text in "
```
## embedded
Der Parameter `embedded` steuert, ob das Widget innerhalb eines anderen Widgets eingebettet ist oder eigenständig auf der Seite steht. In der Regel musst du nichts ändern, denn `embedded` ist standardmäßig auf `true` gesetzt.
```javascript
embedded: false // wenn das Widget NICHT eingebettet in andere Widgets ist
embedded: true // default
```
## width
Mit `width` bestimmst du die Breite des äußeren Containers des Diagramms. Dieser Container umschließt das Donut- oder Kreisdiagramm sowie ggf. die Legende.
Du kannst jede gültige CSS-Weite angeben:
- Prozentangaben (`"100%"`)
- feste Pixelwerte (`"300px"`)
- automatische Größe (`"auto"`)
Standardwert: Wenn kein Wert angegeben ist, wird automatisch `"100%"` verwendet.
```javascript
width: "auto" // passt sich automatisch an
width: "100%" // in px oder Prozent
```
## height
Mit `height` legst du die Höhe des Widget-Containers fest. Dieser Wert beeinflusst nicht nur die Fläche, in der das Diagramm gerendert wird, sondern auch die vertikale Ausrichtung (z. B. der Legende).
Du kannst alle gängigen CSS-Höhenwerte verwenden:
- `"auto"` → automatische Höhe basierend auf Inhalt (Standard)
- `"300px"` → feste Höhe
- `"100%"` → gesamte Höhe des Eltern-Elements
Standardwert: Ohne Angabe wird `"auto"` gesetzt.
```javascript
height: "auto" // passt sich automatisch an
height: "200px" // in px oder Prozent
```
⚠️ Wenn du `height` auf einen fixen Wert setzt, achte darauf, dass dein Chart (und ggf. die Legende) genug Platz zum Anzeigen hat.
## type
Mit dem Parameter `type` bestimmst du, ob dein Diagramm als Donut oder als klassisches Kreisdiagramm (Pie Chart) dargestellt wird.
Optionen:
- `"donut"` → Ringförmige Darstellung mit optionaler Mittelbeschriftung
- `"pie"` → Vollflächiges Kreisdiagramm ohne Loch in der Mitte
```javascript
type: "donut" // stellt das Chart als Donut dar
type: "pie" // stellt das Chart als Pie dar
type: "" // default: pie
```
💡 Hinweis: Nur bei `type: "donut"` werden die Parameter `thickness` und `center` berücksichtigt.
Ein `pie`-Chart ignoriert diese Einstellungen und zeigt einen einfachen Kreis.
## size
Der Parameter `size` definiert die Gesamtgröße des Charts (Breite und Höhe des SVG-Kreises in einem). Dies wirkt sich direkt auf die Darstellung des Kreises oder Donuts aus – unabhängig vom äußeren `width`-/`height`-Container.
- Du kannst alle gängigen CSS-Größen verwenden (z. B. `"160px"` oder `"100%"`), wobei Pixelangaben empfohlen werden.
- Standardwert: Wenn kein Wert angegeben ist, wird automatisch `"160px"` verwendet.
```javascript
size: "160px"
size: "" // default: 160px
```
## thickness
Der Parameter `thickness` definiert die Dicke des Rings bei einem Donut-Chart (`type: "donut"`).
Je höher der Wert, desto schmaler das Loch in der Mitte.
Dieser Parameter hat nur eine Wirkung bei `type: "donut"` – bei `type: "pie"` wird er ignoriert.
- Einheit: in px angeben z. B. `"30px"` oder `"50px"`
- Standardverhalten: Wenn kein Wert gesetzt wird, berechnet das Widget die Ringdicke automatisch auf Basis von `size`.
```javascript
thickness: "30px"
thickness: "" // default: 120px
```
⚠️ Zu große Werte können den Ring visuell zu schmal oder sogar unsichtbar machen – ideal sind Werte zwischen 20–60 px.
## gap
Mit `gap` bestimmst du den **Abstand zwischen den einzelnen Segmenten** im Chart – sowohl bei `pie` als auch bei `donut`.
Ein größerer Wert erzeugt mehr visuelle Trennung zwischen den Bereichen. Der Abstand wird **in Pixeln** angegeben, intern aber auf den **Winkel** umgerechnet (abhängig vom Radius).
- **Einheit: **Nur Zahlenwerte in px, z. B. `"2px"` oder `"8px"`
- **Standardwert: **Wenn kein Wert gesetzt ist, beträgt der Abstand `0px`, also **kein sichtbarer Abstand**.
```javascript
gap: "5px"
gap: "" // default: 0px
```
💡 **Tipp:** Ein kleiner Abstand (2–6px) kann helfen, Segmente besser unterscheidbar zu machen – besonders bei ähnlichen Farben.
## legend settings
Mit der `legend`-Gruppe kannst du steuern, **ob und wie die Legende angezeigt wird**, und deren **Position, Schriftart, Farben und Abstände** festlegen. Die Legende zeigt kleine Farb-Dots und einen Text (je nach Einstellung `title`, `value` oder `percent`).
```javascript
legend: {
position: "right", // left, right, bottom, top // default: right
label: "title", // Bezeichnung
fontSize: "12px", // Schriftgröße
fontWeight: "normal", // Schriftstärke
fontColor: "#333", // Schriftfarbe
gap: "6px" // Abstand zwischen den Legenden Items
}
```
**Einzelne Einstellungen:**
Paramter
**Beschreibung**
visible
Zeigt die Legende an (`true`) oder blendet sie aus (`false`).
position
Platzierung: `"left"`, `"right"`, `"top"` oder `"bottom"`
label
Was soll in der Legende stehen? Ninox Felder referenzieren oder eigene Textbezeichnungen wählen.
fontSize
Schriftgröße der Labels, z. B. `"12px"`
fontWeight
Schriftstärke: `"normal"`, `"bold"`, `"500"` usw.
fontColor
Farbe des Legendentextes, z. B. `"#333"`
gap
Abstand zwischen den Einträgen, z. B. `"6px"`
## center Settings
Mit der `center`-Gruppe kannst du einen Titel und Untertitel in der Mitte des Donut-Charts anzeigen lassen. Diese Anzeige ist nur bei `type: "donut"` sichtbar, da bei `pie` kein Platz in der Mitte vorhanden ist.
Ideal für Werte wie Gesamtzahl, Prozentsumme, Statusangaben o. ä.
**Einzelne Einstellungen:**
Paramter
**Beschreibung**
title
Haupttext in der Mitte (z. B. „Gesamt“)
subtitle
Untertitel direkt darunter (z. B. eine Zahl oder Status)
fontSize
Größe beider Texte (gilt für beide), z. B. `"18px"`
fontColor
Farbe der Schrift, z. B. `"#444"`
```javascript
center: {
title: "Gesamt", // title im Center des Widgets
subtitle: "2000", // subtitle im Center des Widgets
fontSize: "18px", // Schriftgröße im Center des Widgets
fontColor: "#444", // Schriffarbe im Center des Widgets
},
```
## items
Die items-Liste enthält alle **einzelnen Segmente deines Kreisdiagramms**. Jedes Item definiert:
- **Titel** für die Legende
- **Wert**, der die Segmentgröße bestimmt
- **Farbe**, in der das Segment dargestellt wird (und der Dot in der Legende)
Die items können entweder statisch, einzeln als items definiert werden oder du greifst auf eine dynamische Liste (Tabelle in Ninox) zurück, aus dem sich die Werte, die du angibst gezogen werden.
```javascript
items: [{
title: "Belegung", // Beschriftung in der Legende
value: sum(Lager.Belegung), // Wert, der die Größe des Segments bestimmt
color: "#3e6fff", // Farbe, in der das Segment dargestellt werden soll (sowie der Dot in der Legende)
}, {
title: "Gesamtkapazität",
value: sum (Lager.Frei+Lager.Belegung),
color: "#d3d5de",
}]
```
```javascript
items: list_Lager.[{
title: Lagername,
value: sum_lagerbestand,
fontSize: "12px",
color: helper_hex_code,
}
```
**🧠 Wichtig:**
- Alle Werte zusammen ergeben die Gesamtfläche (`value` wird relativ zum Gesamtwert berechnet).
- Farben sollten kontrastreich gewählt werden – vor allem, wenn kein `gap` gesetzt ist.
- Die Reihenfolge der Items entspricht der Reihenfolge im Chart (beginnend bei 12 Uhr, im Uhrzeigersinn).
---
# Check Box
Source: https://www.arc-rider.com/docs/mini-widgets/check-box
# Check Box
## AI Defaults (read first)
- **Function name**: `arcCustomCheckBox`.
- **uniqueId**: Required, e.g. `"checkbox-" + Nr`.
- **recordId**: Required, use raw `Nr`.
- **field**: Required, use `fieldId(Nr, "Feldname")` – must be a boolean/yes-no field.
- **value**: Current boolean state from the field.
# Check Box
Die Check Box kannst du für die optische Darstellung von deinen Ja/Nein Ninox-Feldern nutzen.
Um die Check Box darstellen zu können, fügst du den Anwendungscode in ein Ninox Formel-Feld ein und passt die Parameter nach deinen Wünschen an. Du kannst dieses Mini-Widget auch in andere Widgets, wie die [Custom Table](/custom-table) integrieren.
Dies ist der gesamte Anwendungscode mit allen Parametern, die aktuell für die Check Box zur Verfügung stehen:
```javascript
arcCheckBox({
uniqueId: "uniqueName",
value: 'Ja / Nein',
embedded: true,
width: "",
height: "",
boxSize: "",
borderRadius: "",
strokeWidth: "",
activeSettings: {
backgroundColor: "",
borderColor: "",
color: ""
},
inactiveSettings: {
backgroundColor: "",
borderColor: "",
color: ""
},
labelSettings: {
title: "Erledigt",
position: "",
fontSize: "",
fontColor: ""
},
clickAction: {
recordId: Nr,
fieldId: "",
value: if 'Ja / Nein' = true then null else true end
}
})
```
## Erklärung einzelner Parameter
Folgend wird dir aufgeschlüsselt, welche Parameter du verwenden kannst und was du jeweils eintragen musst.
### uniqueId
Die*** uniqueId*** vergibst du individuell, sie sollte einzigartig sein. Sinn dahinter ist: Wenn du mehrere Check Boxen mit unterschiedlichen Settings auf deiner Oberfläche erstellst, überschreiben sich die Styles nicht.
```javascript
uniqueId: Nr, // Ninox-Feld
uniqueId: "Checkbox 1", // Text in "
```
### value
Bei dem ***value*** gibst du den Namen deines Ninox-Ja/Nein-Feldes an.
```javascript
value: 'Ja / Nein', // Ninox-Ja/Nein-Feld
value: Erledigt, // Ninox-Ja/Nein-Feld, welches du Erledigt genannt hast
```
### embedded
***embedded*** benutzt du, wenn du die Check Box **nicht***** ***innerhalb eines anderen Widgets einsetzt. Standardmäßig ist dies aber auf true gesetzt.
```javascript
embedded: false, // ermöglicht den Standalone Einsatz des Widgets (nicht eingebettet in anderen Widgets)
embedded: true, // wenn das CheckBox Widget in einem anderen Widget eingesetzt wird
embedded: "", // default: false
```
### width
Mit ***width*** bestimmst du die Breite des gesamten Check Box Elements.
```javascript
width: "100%", // Prozent-Werte in "
width: "100px", // Pixel-Werte in "
width: "", // default: auto
```
### height
Mit ***height*** bestimmst du die Höhe des gesamten Check Box Elements.
```javascript
height: "100%", // Prozent-Werte in "
height: "100px", // Pixel-Werte in "
height: "", // default: auto
```
### boxSize
Mit ***boxSize*** bestimmst du, wie groß die Check Box sein soll.
```javascript
boxSize: "40px", // Pixel-Werte in "
boxSize: "", // default: 20px
```
### borderRadius
Mit ***borderRadius*** bestimmst du die Abrundung deiner Check Box. Du kannst px Werte und % Werte eintragen.
```javascript
borderRadius: "50px", // runde Check Box
borderRadius: "3%", // eckige Check Box
borderRadius: "", // default: 4px
```
### strokeWidth
Mit ***strokeWidth*** bestimmst du die Linienstärke für die Umrandung der Checkbox sowie für die Check-Linie des Icons.
```javascript
strokeWidth: "0.5px", // Pixel-Werte in "
strokeWidth: "2px", // Pixel-Werte in "
strokeWidth: "", // default: 1px
```
### **activeSettings** Block
Mit dem ***activeSettings Block*** kannst du die backgroundColor, borderColor der Check Box und color der Check-Linie bei der aktiven Checkbox einstellen.
```javascript
activeSettings: {
backgroundColor: "",
borderColor: "",
color: ""
},
activeSettings: {
backgroundColor: "", // default: #0066FF
borderColor: "", // default: #0066FF
color: "" // default: #FFF
},
```
### **inactiveSettings** Block
Mit dem ***inactiveSettings Block*** kannst du die backgroundColor, borderColor der Check Box und color der Check-Linie bei der inaktiven Checkbox einstellen.
```javascript
inactiveSettings: {
backgroundColor: "",
borderColor: "",
color: ""
},
inactiveSettings: {
backgroundColor: "", // default: #C8CCD4
borderColor: "", // default: #C8CCD4
color: "" // default: none
},
```
### labelSettings Block
Mit dem ***labelSettings Block*** kannst du deiner Check Box ein Label geben. Du kannst bei ***title ***den Text eingeben, der beim Label ausgegeben werden soll. Du kannst auch Ninox-Felder angeben oder Variablen definieren. Wichtig ist hier, dass Text ausgegeben wird.
Du kannst außerdem mit ***position ***bestimmen, ob das Label "left" oder "right" sein soll, mit ***fontSize*** die Schriftgröße und mit ***color*** die Schriftfarbe des Labels einstellen.
```javascript
labelSettings: {
title: "Erledigt", // "text" oder Ninox-Feld (wichtig ist dass hier Text ausgegeben wird)
position: "right",
fontSize: "17px",
fontColor: "#0066FF"
},
labelSettings: {
title: "", // default: Gebt ihr keinen Titel ein, wird kein Label angezeigt.
position: "", // default: right
fontSize: "", // default: 13px
fontColor: "" // default: #262f4d
},
```
### clickAction Block
Bei dem ***clickAction Block*** trägst du relevante Infos für die Click Aktion ein. Bei ***recordId ***gibst du die record ID des Ninox Records an. Bei der ***fieldId ***gibst du die Field ID des Ninox-Feldes an, auf das die Action angewendet wird. Im ***value*** definierst du, was mit dem Ninox-Feld passieren soll, wenn man die Check Box anklickt.
```javascript
clickAction: {
recordId: Nr,
fieldId: "G",
value: if 'Ja / Nein' = true then null else true end
}
```
💡 **Hinweis: **Um die Ninox Feld-ID bestimmter Felder herauszufinden verwendest am besten die nützliche [Funktion arcFieldFinder().](https://www.arc-rider.de/documentation/field-finder)
## Beispiel und Vorlage
**Beispiel: Check Box in einer Spalte der **[**Custom Table**](/custom-table)**.**
**Vorlage: Anwendungs-Code mit dynamischem Label**
Du kannst dir folgenden Code kopieren und mit kleinen Anpassungen, hast du dieses fertige Design mit dynamischem Label:
Die Stellen, wo du Werte ändern oder anpassen musst sind mit // markiert. Denk daran, diese Passagen aus deinem fertigen Code zu entfernen.
💡 **Tipp: **Wenn du z.B. kein Label bei deiner Check Box brauchst, kannst du den gesamten labelSettings Block aus deinem Anwendungs-Code löschen.** **
```javascript
arcCheckBox({
uniqueId: "styled_CheckBox",
value: 'Ja / Nein Feld', // mit deinem Wert ersetzen
width: "",
height: "",
boxSize: "",
embedded: false, // true eingeben, wenn die Checkbox in einem anderen Widget liegt
borderRadius: "",
activeSettings: {
backgroundColor: "#99CCA5",
borderColor: "#239B56",
color: "#239B56"
},
inactiveSettings: {
backgroundColor: "#FFBFBE",
borderColor: "#FF7977",
color: ""
},
labelSettings: {
title: if 'Ja / Nein Feld' = true then
"erledigt"
else
"offen"
end, // 'Ja / Nein Feld' mit deinem Wert ersetzen und ggf. den Text anpassen
position: "right",
fontSize: "",
fontColor: ""
},
clickAction: {
recordId: Nr,
fieldId: "J", // mit deinem Wert ersetzen
value: if 'Ja / Nein Feld' = true then
null
else
true
end // 'Ja / Nein Feld' mit deinem Wert ersetzen oder ggf. alles mit deiner Variable austauschen
}
})
```
---
# Clock
Source: https://www.arc-rider.com/docs/mini-widgets/clock
# Clock
## AI Defaults (read first)
- **Function name**: `arcCustomClock`.
- **uniqueId**: Required, e.g. `"clock-" + Nr`.
- **Standalone widget**: Typically needs no `recordId` or `field`.
# Clock
## Anwendungscode
```javascript
arcCustomClock({
uniqueId: "",
timezone: "Europe/Berlin"
})
```
### timezone
***timezone*** definiert in welcher Zeitzone deine Zeit angezeigt werden soll.
```javascript
timezone: "Europe/Berlin",
timezone: "", // Fallback-Wert:
```
---
# Field Finder
Source: https://www.arc-rider.com/docs/mini-widgets/field-finder
# Field Finder
## AI Defaults (read first)
- **Function name**: `arcFieldFinder`.
- **Purpose**: Utility widget to discover Ninox field IDs. Not for production UIs.
- **Usage**: Place in a formula field to display field IDs for a table.
# Field Finder
Mit dem Field Finder kannst du schnell und einfach die eindeutige ID eines Ninox-Feldes ermitteln. Diese ID wird in vielen Widgets benötigt, um Aktionen wie z. B. **„update“** gezielt auf ein bestimmtes Feld auszuführen.
## Anwendungscode
```javascript
arcFieldFinder({
apiKey: "YOUR_API_KEY",
table: "A",
field: "editing"
})
```
💡 **Hinweis**: Wenn du dir im Globalen Code eine Funktion für deinen API-Key baust, dann musst du diesen nicht immer eingeben. :) Dann könnte dein Anwendungscode besipielsweise so aussehen:
```javascript
arcFieldFinder({
apiKey: apiKey(),
table: tableId(this),
field: "editing"
})
```
## Beispiel
Du kannst für die Parameter natürlich auf Ninox-Felder zurückgreifen. So auch in folgendem Beispiel:
```javascript
arcFieldFinder({
apiKey: apiKey(),
table: table,
field: field
})
```
Ausgegeben wird dir nun die Field ID "B", die du für deine Aktionen in anderen Widgets angeben kannst.
---
# Icon
Source: https://www.arc-rider.com/docs/mini-widgets/custom-icon
# Icon in React
Ein Symbol aus einem unterstützten Icon-Set darstellen, etwa als Statusindikator oder innerhalb eines Buttons.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetIcon } from '@arcrider/arcwidgets-react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
return (
);
}
```
## Features ausprobieren
### Symbol, Strichstärke und Größe
Wechsle zwischen Phosphor-Symbolen und Varianten. Das Beispiel verwendet die reale Icon-Laufzeit inklusive SVG-Laden.
```tsx
import { useState } from 'react';
import { ArcWidgetIcon } from '@arcrider/arcwidgets-react';
export default function Example() {
const [name, setName] = useState('star');
const [style, setStyle] = useState('regular');
const [size, setSize] = useState(32);
return (
<>
{name} · {style} · {size}px
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetIconData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
Dieses Widget ist eine Darstellungskomponente und stellt keine eigenen Interaktions-Callbacks bereit.
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### iconSet
Name des verwendeten Icon-Sets.
Typ: `'phosphor' | 'openmoji' | 'material_symbols' | 'material' | string`.
### name
Name des Symbols im gewählten Set.
Typ: `string`.
### style
Variante innerhalb des Icon-Sets.
Typ: `string`.
### iconSize
Größe des Symbols.
Typ: `string`.
### color
Symbol- oder Inhaltsfarbe.
Typ: `string`.
### containerSize
Größe des umgebenden Symbolbereichs.
Typ: `string`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
### borderSize
Rahmenstärke.
Typ: `string`.
### borderColor
Rahmenfarbe.
Typ: `string`.
## Verhalten und Grenzen
- Icons werden bei Bedarf geladen und im Browser zwischengespeichert. Phosphor- und Material-SVGs nutzen bei leerem Cache `https://universe.arc-rider.com/cdn/`; diese Verbindung muss erreichbar und in der Content Security Policy deiner App erlaubt sein.
- Setze `iconSet` und den dazu passenden `name`. Größe und Farbe gehören in `iconSize` und `color`.
- Das Widget ist eine Darstellungskomponente. Interaktion und zugängliche Beschriftung liegen beim umgebenden Steuerelement.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetIconData extends ArcWidgetBaseData {
iconSet?: 'phosphor' | 'openmoji' | 'material_symbols' | 'material' | string;
name: string;
style?: string;
iconSize?: string;
color?: string;
containerSize?: string;
backgroundColor?: string;
borderRadius?: string;
borderSize?: string;
borderColor?: string;
}
```
## Einsatzbeispiele
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Icon
## AI Defaults (read first)
- **Function name**: `arcCustomIcon`.
- **iconSet**: `"phosphor"` (default if unset), `"openmoji"`, `"material_symbols"` (alias `"material"`).
- **name**: Glyph name (e.g. `"user"`, `"trash"`). Phosphor legacy: style in name (`"trash-bold"`) still works and overrides explicit **style**.
- **style**: Phosphor: `regular` | `bold` | `duotone` | `light` | `thin` | `fill`. Material: `outlined` | `rounded` | `sharp` | `rounded-fill` | … (default Phosphor `regular`, Material `outlined`).
- **iconSize**, **color**: Icon size and fill color (e.g. `"24px"`, `"#818599"`).
- **containerSize**, **backgroundColor**, **borderRadius**, **borderSize**, **borderColor**: Built-in container – do NOT wrap in `arcCustomLayout` for styling.
- **No uniqueId needed** for display-only icons.
# Custom Icon
Jeder Kunde erhält zum Start seiner Lizenz ein Standard Icon-Set. Solltest du mehr Icons benötigen, kontaktiere uns über [support@arc-rider.com](mailto:support@arc-rider.com) oder in unserem [Discord-Channel.](https://discord.com/invite/Fg67f8qX3K)
💡** Hinweis**: Custom Icon unterstützt [Phosphor-Icons](https://phosphoricons.com/), [Material Symbols](https://fonts.google.com/icons) (`iconSet: "material"` oder `"material_symbols"`) und [OpenMoji](https://openmoji.org/). Nach dem ersten Laden werden Phosphor- und Material-Icons im Browser zwischengespeichert – wiederholte Aufrufe sind schneller und funktionieren offline, sobald das Set einmal vollständig geladen wurde (keine Extra-Konfiguration nötig).
Um Icons zu deinem Projekt hinzuzufügen, gehst du über dein User Cockpit zum Bereich Icons und wählst diese einfach an (siehe weiter unten die Erklärung).
##
Anwendungscode
```javascript
arcCustomIcon({
iconSet: "phosphor",
name: "trash",
containerSize: "40px",
borderSize: "",
borderColor: "",
borderRadius: "7px",
iconSize: "30px",
color: "#FF2222",
backgroundColor: "#fcdfde"
})
```
```javascript
arcCustomIcon({
iconSet: "openmoji",
name: "envelope-with-arrow-color",
containerSize: "50px",
borderSize: "1px",
borderColor: "",
iconSize: "50px",
borderRadius: "50px",
color: "#C637E4",
backgroundColor: "#FAE6FF"
}),
```
iconSet definiert das Iconset.
```javascript
iconSet: "phosphor", // Standard-Fallback
iconSet: "material", // Alias für material_symbols
iconSet: "material_symbols",
iconSet: "openmoji",
```
Wenn du **kein** `iconSet` angibst, nutzt das Widget das zuerst vollständig vorinstallierte Set (Reihenfolge: Phosphor → Material → OpenMoji), sonst Phosphor.
style (optional) wählt die Variante innerhalb des Sets.
**Phosphor** — `regular` (Standard), `bold`, `duotone`, `light`, `thin`, `fill`:
```javascript
arcCustomIcon({ iconSet: "phosphor", name: "trash", style: "bold", color: "#c00" })
```
**Legacy:** Stil im Namen (`name: "trash-bold"`) funktioniert weiterhin und hat Vorrang vor einem gesetzten `style`.
**Material Symbols** — `outlined` (Standard), `rounded`, `sharp`, gefüllte Varianten mit Suffix `-fill` (z. B. `rounded-fill`):
```javascript
arcCustomIcon({ iconSet: "material", name: "home", style: "rounded-fill", iconSize: "24px" })
```
name definiert den Glyph-Namen (ohne Stil-Suffix, wenn du `style` separat setzt). Namen findest du im Cockpit bzw. in den jeweiligen Icon-Katalogen.
```javascript
name: "trash", // Titel immer in " schreiben
```
containerSize definiert, ob und in welcher Größe du deinen Container/Background des Icons anzeigen lassen möchtest.
```javascript
containerSize: "30px", // Pixel-Wert in " angeben
containerSize: "" // Kein Fallback-Wert
```
***borderSize*** definiert, wie dick deine Umrandung sein soll.
```javascript
borderSize: "1px", // Pixel-Wert in " angeben
borderSize: "", // Kein Fallback-Wert
```
***borderColor*** gibt die Farbe deiner Border/Umrandung an.
```javascript
borderColor: "#000", // HEX Code in " angeben
borderColor: "", // Kein Fallback-Wert
```
***borderRadius*** gibt die Abrundung deiner Border-Ecken an.
```javascript
borderRadius: "7px", // Pixel-Wert in " angeben
borderRadius: "", // Kein Fallback
```
***iconSize*** gibt die Größe deines Icons an.
```javascript
iconSize: "20px", // Pixel-Wert in " angeben
iconSize: "", // Fallback: "15px"
```
***color*** gibt die Farbe deines Icons an.
```javascript
color: "#FF2222", // Hex-Wert in " angeben
color: "", // Kein Fallback-Wert
```
***backgroundColor*** gibt die Hintergrund-Farbe des Containers an.
```javascript
backgroundColor: "#fcdfde", //
backgroundColor: "", // Kein Fallbackwert
```
##
Icons über dein Cockpit hinzufügen
Du kannst die deine Aktuelle Sammlung und die verfügbaren Iconsets anzeigen lassen. Filter für Icon Styles oder Icon Gruppen findest du auf der rechten Seit.
Um ein Icon an- oder abzuwählen, klicke es einfach an.
Kopiere dann den Widget Code und füge ihn in deinen globalen Code. Schon kannst du sie im Anwedungscode nutzen.
---
# Images
Source: https://www.arc-rider.com/docs/mini-widgets/images
# Images
## AI Defaults (read first)
- **Function name**: `arcCustomImage`.
- **value**: Image URL or Base64 string.
- **width**, **height**: Set dimensions directly.
- **borderRadius**: E.g. `"8px"` for rounded corners, `"50%"` for circular.
- **objectFit**: `"cover"` (crop to fill) or `"contain"` (fit inside).
# Custom Image
Mit Images kannst du Bilder in Tabellen, Kanban oder anderen Widgets laden. Du hast etliche Einstellungen, von Umrandung bis Abrundung über Größeneinstellungen.
```javascript
arcCustomImage({
uniqueId: "ProjektBild"+Nr,
title: "Logo",
width: "80px",
height: "80px",
backgroundSize: "cover",
backgroundColor: "",
style: "", // Hier kannst du eigene CSS Styles hinterlegen.
radius: "5px",
borderColor: "",
link: text(Projekt.'Bild URL') // Hier musst du immer einen shareLink deines Bildes hinterlegen.
})
```
#### Allgemeine Settings
### uniqueId
Die ***uniqueId*** vergibst du individuell und sollte einzigartig sein. Sinn dahinter ist: Wenn du mehrere Images mit unterschiedlichen Settings auf deiner Oberfläche erstellst, überschreiben sich die Styles nicht.
```javascript
uniqueId: "ProjektBild" + Nr // Text in " + Ninox Nr
```
### title
```javascript
title: "Logo",
```
### width
Mit*** width*** kannst du die Breite des Bild Containers einstellen.
```javascript
width: "100%", // Prozent-Werte. Hier: volle Breite.
width: "100px", // Pixel-Werte
```
### height
Mit*** height*** kannst du die Höhe des Bilde Containers einstellen.
```javascript
height: "auto", // Automatisch an den Inhalt angepasste Höhe.
height: "300px", // Pixel-Werte
```
### backgroundSize
Mit ***backgroundSize*** definierst du die Größe des Bildes im Container.
```javascript
backgroundSize: "cover", // Füllt den Container komplett aus, kann dazu führen, dass das Bild abgeschnitten wird.
backgroundSize: "contain", // Das Bild wird komplett in dem Container angezeigt.
backgroundSize: "50%",
backgroundSize: "auto", // Bild wird in der Originalgröße angezeigt.
backgroundSize: "15px 10px", // Gibt Breite und Höhe in Pixel an.
```
### backgroundColor
Mit ***backgroundColor*** kannst du die Farbe des Hintergrundes bestimmen. Vor allem nützlich, wenn kein Bild angezeigt wird oder für Bilder, die nicht auf die Gesamtgröße angepasst wurden. Es ist auch möglich, den Hintergrund transparent zu machen.
```javascript
backgroundColor: "#1D8C96", // HEX-Code für Farben
backgroundColor: "transparent", // für einen transparenten Hintergrund
```
### style
Bei dem*** style*** Parameter kannst du eigene CSS styles hinzufügen.
```javascript
style: "opacity 30%;", // CSS styles
```
---
# Input
Source: https://www.arc-rider.com/docs/mini-widgets/input
# Input in React
Text, Zahlen, Datum oder Uhrzeit erfassen. Das Beispiel filtert über React-State und zeigt die Rückmeldung beim Bestätigen oder Zurücksetzen.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetInput } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
const [query, setQuery] = useState('');
const [last, setLast] = useState('');
return (
<>
setQuery(String(value ?? ''))}
onActions={(_value, source) => setLast(source)}
/>
);
}
```
## Features ausprobieren
### Live-Update, Debounce, Enter und Reset
Tippe einen Suchbegriff, ändere die Verzögerung und teste Enter sowie das Zurücksetzen. Unter dem Feld siehst du den übernommenen React-State.
```tsx
import { useState } from 'react';
import { ArcWidgetInput } from '@arcrider/arcwidgets-react';
export default function Example() {
const [value, setValue] = useState('');
const [delay, setDelay] = useState(300);
const [event, setEvent] = useState('Noch kein Ereignis');
return (
<>
setValue(String(next ?? ''))}
onActions={(next, source) => setEvent(`${source}: ${next}`)}
/>
React-State: {value || 'leer'} · {event}
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetInputData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
### onChange
Übernimmt den neuen Eingabewert in deinen State.
```typescript
onChange?: (value: string | number | null) => void | Promise;
```
### onActions
Meldet Bestätigung oder Zurücksetzen. Der Wert ist ein String; `source` unterscheidet beide Vorgänge.
```typescript
onActions?: (value: string, source: 'submit' | 'reset') => void;
```
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### title
Beschriftung; als Slot auch mit JSX möglich.
Typ: `ArcWidgetSlot`.
### placeholder
Hinweis bei leerem Wert.
Typ: `string`.
### type
Eingabetyp. Im Beispiel wird Text verwendet.
Typ: `'text' | 'number' | 'date' | 'time' | 'textarea' | string`.
### value
Anzuzeigender bzw. aktuell bearbeiteter Wert.
Typ: `unknown`.
### disabled
Deaktiviert die Eingabe.
Typ: `boolean`.
### tempStorage
Unterdrückt den Change-Callback; nur für bewusst lokal gehaltene Werte.
Typ: `boolean`.
### suffix
Inhalt nach der Beschriftung oder Einheit.
Typ: `ArcWidgetSlot`.
### width
Breite des Widgets als Größenangabe.
Typ: `string`.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### alignX
Horizontale Ausrichtung.
Typ: `string`.
### paddingX
Innerer Abstand links und rechts.
Typ: `string`.
### paddingY
Innerer Abstand oben und unten.
Typ: `string`.
### fontColor
Schriftfarbe.
Typ: `string`.
### fontSize
Schriftgröße als CSS-Wert.
Typ: `string`.
### fontWeight
Schriftstärke.
Typ: `string | number`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### borderWidth
Rahmenstärke.
Typ: `string`.
### borderColor
Rahmenfarbe.
Typ: `string`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
### autocomplete
Autovervollständigung der Eingabe.
Typ: `boolean`.
### editable
Bearbeitbarkeit des Inhalts.
Typ: `boolean`.
### focusAction
Einstellungen beim Fokussieren, etwa `autoFocus`.
Typ: `{ autoFocus?: boolean; [key: string]: unknown }`.
### placeholderSettings
Text und Darstellung des leeren Felds.
Typ: `ArcWidgetInputPlaceholderSettings`.
### labelSettings
Beschriftung und ihre Ausrichtung.
Typ: `ArcWidgetInputLabelSettings`.
### numberFormat
Dezimalstellen und Trennzeichen für Zahlen.
Typ: `ArcWidgetInputNumberFormat`.
### numpad
Bildschirmtastatur für Zahleneingaben.
Typ: `ArcWidgetInputNumpad`.
### reset
Konfiguration der Rücksetzfunktion.
Typ: `ArcWidgetInputReset`.
### timeSettings
Zeitbereich und Raster; Einheiten sind Millisekunden.
Typ: `{ format?: string; minuteStep?: number; showNow?: boolean; [key: string]: unknown }`.
### liveUpdate
Laufende Übernahme bei Texteingabe, optional mit Verzögerung (`debounce`) und Mindestlänge.
Typ: `boolean | { debounce?: number; minLength?: number; actions?: boolean; [key: string]: unknown }`.
## Verhalten und Grenzen
- `onChange` übergibt den neuen Wert; `onActions(value, source)` meldet Bestätigung oder Reset mit `source: "submit" | "reset"`.
- Für Suche eignet sich `liveUpdate: { debounce: 200, minLength: 0 }`. Ohne Live-Update wird beim Bestätigen oder Verlassen übernommen.
- Bei `tempStorage: true` bleibt der Wert lokal im Widget und `onChange` entfällt; nutze das nur bewusst.
- Der Zahlen-Numpad bestätigt über Fertig, Blur oder Enter. `liveUpdate` wirkt dort nicht wie bei Text. `reset` muss für einen sichtbaren Reset konfiguriert werden.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetInputReset {
title?: ArcWidgetSlot;
hide?: boolean;
visible?: boolean;
value?: unknown;
icon?: ArcWidgetSlot;
color?: string;
backgroundColor?: string;
borderRadius?: string;
[key: string]: unknown;
}
export interface ArcWidgetInputNumberFormat {
digits?: number;
decimalSeparator?: string;
thousandSeparator?: string;
}
export interface ArcWidgetInputNumpad {
enabled?: boolean;
size?: string;
openOnFocus?: boolean;
allowNegative?: boolean;
maxDecimals?: number;
suffix?: string;
[key: string]: unknown;
}
export interface ArcWidgetInputPlaceholderSettings {
value?: string;
fontColor?: string;
backgroundColor?: string;
[key: string]: unknown;
}
export interface ArcWidgetInputLabelSettings {
title?: ArcWidgetSlot;
fontSize?: string;
fontColor?: string;
alignX?: string;
gap?: string;
[key: string]: unknown;
}
export interface ArcWidgetInputData extends Omit {
title?: ArcWidgetSlot;
placeholder?: string;
type?: 'text' | 'number' | 'date' | 'time' | 'textarea' | string;
value?: unknown;
disabled?: boolean;
tempStorage?: boolean;
suffix?: ArcWidgetSlot;
width?: string;
height?: string;
alignX?: string;
paddingX?: string;
paddingY?: string;
fontColor?: string;
fontSize?: string;
fontWeight?: string | number;
backgroundColor?: string;
borderWidth?: string;
borderColor?: string;
borderRadius?: string;
autocomplete?: boolean;
editable?: boolean;
focusAction?: { autoFocus?: boolean; [key: string]: unknown };
placeholderSettings?: ArcWidgetInputPlaceholderSettings;
labelSettings?: ArcWidgetInputLabelSettings;
numberFormat?: ArcWidgetInputNumberFormat;
numpad?: ArcWidgetInputNumpad;
reset?: ArcWidgetInputReset;
timeSettings?: { format?: string; minuteStep?: number; showNow?: boolean; [key: string]: unknown };
liveUpdate?: boolean | { debounce?: number; minLength?: number; actions?: boolean; [key: string]: unknown };
}
export interface ArcWidgetInputProps extends ArcReactWidgetProps {
onChange?: (value: string | number | null) => void | Promise;
onActions?: (value: string, source: 'submit' | 'reset') => void;
}
```
## Einsatzbeispiele
- [Status auswählen und speichern](/docs/react/examples/status-als-buttons-ausgeben)
- [Ein Formular in Schritten](/docs/react/examples/datenaufnahme-in-schritten)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Input
## AI Defaults (read first)
- **uniqueId**: Required, e.g. `"input-name-" + Nr`.
- **recordId**: Required for Ninox binding, use raw `Nr`. Core does not read it — Ninox handler builds the `update` from `ui.data`.
- **field**: Required for Ninox, use `fieldId(Nr, "Feldname")` (alias `fieldId`). Adapter-only.
- **placeholder**: Optional hint text.
- **type**: `"text"` (default), `"number"`, `"date"`, `"time"`, `"textarea"`.
- **focusAction**: Set `{ autoFocus: false }` for tablet compatibility.
- **Mobile (iPhone/iPad/Android, schmale Viewports)**: Text/textarea use keyboard dock above the on-screen keyboard; `type: "date"` / `"time"` / `"number"` use the custom picker (not native / not system keyboard). Reset supports `arcCustomIcon` in the dock (text) or the shared icon slot (date/time/number).
- **numberFormat** (only `type: "number"`): `{ digits, decimalSeparator, thousandSeparator }` — default DE: `digits: 2`, `","` / `"."`.
- **numpad** (only `type: "number"`): `{ enabled, size, openOnFocus, allowNegative, maxDecimals, suffix }` — popup numpad (default `enabled: true`). Not the same as the standalone `arcCustomNumPad` widget.
- **Persistence**: Core emits semantic `change` (field value) and `actions` (`inputValue` + `source: "submit" | "reset"`). Ninox adapter writes `type: "update"` with `fieldId` and runs formula `actions` / `reset.actions` (with `##inputValue##`). React: `onChange(value)` / `onActions(inputValue, source)`.
- **actions**: Optional (Ninox formula). Array of action objects, fired on submit (Enter/blur / numpad Fertig) and on reset. Use `##inputValue##` placeholder to inject the current input value. Resolved in the Ninox handler (not passed through React callbacks).
- **reset.actions**: Optional. If set inside `reset: { actions: [...] }`, only these actions fire on reset (not top-level `actions`). Submit still uses `actions`.
- **liveUpdate**: Optional. `true` or `{ debounce: 300, minLength: 0, actions: true }`. Fires updates while typing (debounced). On blur, only fires if value changed since last live update. **Not used by the number numpad** (commit on Fertig / outside / Enter only).
# Input
`arcCustomInput` ist ein vielseitiges und anpassbares Mini-Widget zur Darstellung und Bearbeitung von Eingabefeldern in deiner Ninox-Datenbank. Es ersetzt das Standard-Eingabefeld durch ein flexibles, visuell anpassbares Interface, das du direkt in **Formel-Feldern oder komplexeren Widgetcodes **einsetzen kannst – z. B. auf Detailansichten, Dashboards oder in Kombination mit anderen Widgets wie `arcCustomTable`.
Mit `arcCustomInput` lassen sich Texteingaben, Zahlen, Datums- oder Uhrzeitwerte gezielt steuern, visuell hervorheben oder mit **eigenen Platzhaltern, Labels und Fokus-Verhalten** versehen. Auch mehrzeilige Eingaben (`textarea`) werden unterstützt.
### 🚀 Hauptfunktionen
- **Komplett visuell konfigurierbar** (Farben, Schriftgrößen, Rahmen, Ausrichtung usw.)
- **Single-Line oder Multiline** (Text vs. Textarea) – automatisch je nach `type`
- **Tab-Steuerung zwischen Feldern** (auch zwischen `arcCustomInput` und `arcCustomSelect`)
- **Live-Fokus & Loop-Logik**: Automatisches Reinspringen in Felder (direkt tippen ohne das Input anzuklicken)
- **Autofokus bei Start oder Klick**
- **Read-Only-Ansicht**, wenn `disabled: true`
- **Platzhalter-Designs** für visuelles Feedback bei leeren Feldern
- **Reset-Button** zum Zurücksetzen des Werts (nur sichtbar, wenn ein Wert vorhanden ist)
- **Zahlen-Numpad** bei `type: "number"` (Popup wie Date/Time; Locale über `numberFormat`)
- **Actions** bei Submit (Enter/blur / Numpad-Fertig) und Reset – z. B. für Suchfelder, Barcode-Scanner oder Trigger-Logik
## Gesamter Anwendungscode
Folgend siehst du einen beispielhaften Anwendungscode für ein Input Field
```javascript
arcCustomInput({
uniqueId: "Mein-Input-" + Nr,
recordId: Nr,
fieldId: "",
title: text(Zahl),
value: text(Zahl),
type: "text",
embedded: true,
disabled: false,
tempStorage: false,
suffix: "",
width: "",
height: "",
alignX: "left",
paddingY: "",
paddingX: "",
fontColor: "",
fontSize: "",
fontWeight: "",
backgroundColor: "",
borderWidth: "",
borderColor: "",
borderRadius: "",
numberFormat: {
digits: 2,
decimalSeparator: ",",
thousandSeparator: "."
},
numpad: {
enabled: true,
size: "default",
openOnFocus: false,
allowNegative: false,
maxDecimals: 2,
suffix: "€"
},
placeholderSettings: {
value: "",
fontColor: "",
backgroundColor: ""
},
reset: {
visible: false,
value: null,
icon: "",
color: "",
backgroundColor: "",
borderRadius: ""
},
focusAction: {
width: "",
showFocusOutline: false,
outlineWidth: "",
outlineColor: "",
loop:",
nextField: ""
},
actions: [
{ type: "update", recordId: Nr, field: fieldId(Nr, "Feld"), value: "##inputValue##" }
],
liveUpdate: false,
labelSettings: {
title: "",
fontSize: "",
alignX: "",
gap: ""
}
})
```
## Erklärung einzelner Parameter
Folgend wird dir aufgeschlüsselt, welche Parameter du verwenden kannst und was du jeweils eintragen musst.
### uniqueId
`uniqueId` vergibst du individuell und sollte einzigartig sein. Sinn dahinter ist: Wenn du mehrere Inputfelder mit unterschiedlichen Settings auf deiner Seite erstellst, überschrieben sich die Styles nicht.
```javascript
uniqueId: Nr,
```
### recordId
`recordId` gibt an in welchem Record die Änderung vorgenommen werden soll.
```javascript
recordId: Nr,
```
### fieldId
`fieldId` gibt an, welches Feld beschrieben werden soll. Die Field ID findest du mit dem Mini Widget [***Field Finder***](/documentation/field-finder) heraus.
```javascript
fieldId: "",
```
### value
`value` gibt an, welcher Wert in der Oberfläche angezeigt werden soll. Das ist das Feld, dessen Field ID du ausgibst. Zum Beispiel Menge.
**Bei `type: "date"`:** Übergib den Wert als **Millisekunden** (Unix-Timestamp). Ninox speichert Datumsfelder intern so – du kannst das Feld direkt übergeben, ohne `text()` oder `format()`:
```javascript
value: Startdatum,
```
Das Widget konvertiert intern für Anzeige und speichert bei Änderung wieder Millisekunden. Fallback: DD.MM.YYYY-String wird ebenfalls akzeptiert.
```javascript
value: "",
```
### type
`type` definiert den Feldtypen deines Inputs. Den type *number* nutzt du, wenn du ein Ninox Zahlenfeld wiedergeben möchtest und *text*, wenn du ein Ninox Textfeld wiedergeben möchtest. Indem du *textarea* beim type eingibst, wird das Input als mehrzeiliges Feld angezeigt.
Die types ***date*** und ***time*** nutzen auf **Desktop** Segment-Eingabe plus Custom-Picker. Auf **Mobil** (iPhone, iPad, Android oder Viewport ≤ 768px) öffnet Tippen auf das Feld den **arcCustom Date-/Time-Picker** – nicht die System-Tastatur.
**`type: "number"`** nutzt ein **Numpad-Popup** (analog Date/Time), gesteuert über `numberFormat` und `numpad` (siehe unten). Auf Mobil öffnet Tippen auf das Feld immer das Numpad. Auf Desktop kannst du tippen und optional per Rechner-Icon (oder `numpad.openOnFocus: true`) das Popup öffnen.
Für **text** und **textarea** auf Mobil: Beim Fokus wird das Feld in ein **Keyboard-Dock** über der Bildschirm-Tastatur angehoben, damit Eingabe und Reset sichtbar bleiben.
```javascript
type: "number" // Zahlen-Feld mit Numpad-Popup (Z. B. Betrag, Menge)
type: "text" // Text-Feld (Z. B. für Volltextsuchen)
type: "date" // Datums-Feld mit Datepicker
type: "time" // Zeit-Feld mit Timepicker
type: "textarea" // Mehrzeiliges Input-Feld
type: "" // default: text
```
### numberFormat (nur bei `type: "number"`)
Steuert die **Anzeige** und das **Zurückparsen** von Zahlen (Locale). Speichern / `##inputValue##` liefern eine normale Zahl (Punkt-Dezimal intern).
```javascript
numberFormat: {
digits: 2, // Nachkommastellen in der Anzeige (Default: 2). null = so viele wie nötig
decimalSeparator: ",", // Default: "," (DE)
thousandSeparator: "." // Default: "." (DE). EN-Beispiel: "." / ","
}
```
| Property | Default | Beschreibung |
|----------|---------|--------------|
| `digits` | `2` | Feste Nachkommastellen nach Commit (z. B. `14,50`). Während des Tippens im Numpad siehst du den Rohwert (`14,5`). `null` = keine Auffüllung. |
| `decimalSeparator` | `","` | Dezimaltrenner in der UI |
| `thousandSeparator` | `"."` | Tausendertrenner in der UI (z. B. `1.234,56`) |
**Englisch (Punkt-Dezimal):**
```javascript
numberFormat: {
digits: 2,
decimalSeparator: ".",
thousandSeparator: ","
}
```
### numpad (nur bei `type: "number"`)
Steuert das **Numpad-Popup** im Input. Das ist **nicht** das eigenständige Widget [`arcCustomNumPad`](/documentation/custom-numpad) (Fullscreen-/Inline-Numpad mit eigenem Submit) – hier geht es um den Feld-Picker wie beim Datepicker.
```javascript
numpad: {
enabled: true, // Default: true. false = nur Tippen (Desktop), kein Popup
size: "default", // "default" | "mini"
openOnFocus: false, // Desktop: true = Klick ins Feld öffnet Numpad (statt Tippen)
allowNegative: false, // ±-Taste
maxDecimals: 2, // Max. Nachkommastellen beim Tippen (Default: numberFormat.digits)
suffix: "€" // Anzeige im Feld + im Numpad (optional; Fallback: top-level suffix)
}
```
| Property | Default | Beschreibung |
|----------|---------|--------------|
| `enabled` | `true` | Numpad an/aus |
| `size` | `"default"` | `"mini"` = kompakteres Panel |
| `openOnFocus` | `false` | Desktop: Feldklick öffnet Numpad. Mobil: immer Numpad beim Tap |
| `allowNegative` | `false` | Vorzeichen umschalten |
| `maxDecimals` | `numberFormat.digits` | Begrenzt Nachkommastellen während der Eingabe; `0` = kein Komma |
| `suffix` | `""` / top-level `suffix` | z. B. `€`, `Stk` – erscheint in der Feldanzeige (`14,50 €`) und im Numpad-Display |
**Verhalten**
- Wert wird erst bei **Fertig**, Klick außerhalb oder **Enter** geschrieben (kein `liveUpdate` über das Numpad).
- Escape schließt ohne zu speichern.
- Das Zahlenfeld bleibt sichtbar; das Numpad dockt am Feld (bevorzugt darüber).
- **Reset:** Bei `reset.visible: true` und vorhandenem Wert erscheint **nur das X** (wie bei Date) – kein Rechner + X gleichzeitig. Leer / ohne Reset → Rechner-Icon öffnet das Numpad.
**Beispiel: Betrag mit Mini-Numpad**
```javascript
arcCustomInput({
uniqueId: "betrag-" + Nr,
recordId: Nr,
fieldId: fieldId(Nr, "Betrag"),
value: Betrag,
type: "number",
alignX: "right",
numberFormat: {
digits: 2,
decimalSeparator: ",",
thousandSeparator: "."
},
numpad: {
enabled: true,
size: "mini",
openOnFocus: true,
suffix: "€"
},
reset: { visible: true },
placeholderSettings: { value: "0,00" },
labelSettings: { title: "Betrag" }
})
```
**Beispiel: Ganzzahl (Menge)**
```javascript
arcCustomInput({
uniqueId: "menge-" + Nr,
recordId: Nr,
fieldId: fieldId(Nr, "Menge"),
value: Menge,
type: "number",
alignX: "right",
numberFormat: { digits: 0, decimalSeparator: ",", thousandSeparator: "." },
numpad: { enabled: true, maxDecimals: 0, suffix: "Stk" },
placeholderSettings: { value: "0" }
})
```
### timeSettings (nur bei `type: "time"`)
Bei `type: "time"` steuert `timeSettings` den Custom Time Picker (analog zum Date Picker):
```javascript
timeSettings: {
format: "24h", // "24h" (default) oder "12h" (AM/PM links)
minuteStep: 5, // Minuten-Schritte: 5 (00,05,10...) oder 1
showNow: true, // "Jetzt"-Button (default: true)
hours: [ // Optional: Overrides für einzelne Stunden
{ value: 10, label: "10", backgroundColor: "#e8f4fd", fontColor: "#1a73e8" }
],
minutes: [ // Optional: Overrides für einzelne Minuten
{ value: 30, label: "½", backgroundColor: "#f0f0f0" }
],
labels: [{ hours: "Stunden", minutes: "Minuten" }] // Optional: Übersetzung
}
```
- **format**: `"24h"` (default) zeigt 00–23, `"12h"` zeigt 01–12 mit AM/PM-Umschalter links.
- **minuteStep**: `5` für 5er-Schritte (00, 05, 10 … 55), `1` für volle Minutenauflösung.
- **showNow**: `true` zeigt den „Jetzt“-Button. Klick auf Minute schließt den Picker.
- **hours** / **minutes**: Arrays mit Overrides. Nur angegebene Einträge überschreiben Defaults (`value`, `label`, `backgroundColor`, `fontColor`).
- **labels**: Array mit Objekt für übersetzbare Sektions-Labels. Beispiel: `labels: [{ hours: "Stunden", minutes: "Minuten" }]`. Es wird das erste Element verwendet. Fehlende Keys nutzen Defaults (`"HOURS"`, `"MINUTES"`).
### embedded
`embedded` benutzt du, wenn du den Button ***nicht ***innerhalb eines anderen Widgets einsetzt. Standardmäßig ist dies aber auf true gesetzt.
```javascript
embedded: false, // ermöglicht den Standalone Einsatz des Widgets (nicht eingebettet in anderen Widgets)
embedded: true, // Fallback
```
### tempStorage
Mit `tempStorage`**: true/false **kann der eingegebene Wert übernommen werden, ohne dass ein Ninox Feld dahinter steht. Dieser Anwendungsfall macht nur Sinn, wenn Daten nur temporär eingegeben werden sollen und nicht in Ninox direkt gespeichert werden sollen. Kombiniert mit `actions` kannst du z. B. ein Suchfeld bauen: Der Wert wird nicht gespeichert, aber beim Submit feuern die Actions (z. B. ein Update auf ein Helper-Feld oder eine URL mit `##inputValue##`).
```javascript
tempStorage: "true", // der eingegebene Wert wird nur temporär gespeichert
tempStorage: "false", // default
```
### width
`width` gibt die Breite deines Inputfeldes an.
```javascript
width: "50px", // Pixel Werte in "
width: "100%", // Prozent Werte in "
```
### height
`height` gibt die Höhe deines Input-Feldes an.
```javascript
height: "50px", // Pixel-Werte in "
```
### color
`color` gibt die Schriftfarbe des Eingabetextes an.
```javascript
color: "#000000", // HEX Wert in "
```
### background
`background` gibt die Hintergundfarbe deines Inputfeldes an.
💡 Tipp: Wenn du das Input in ein anderes Widget, wie [Layout](https://www.arc-rider.de/documentation/custom-layout), [Table](/documentation/custom-table), [Card](/documentation/cards) etc. einfügst, kannst du bei Hintergrundfarbe auf `background: "transparent"` einstellen. So wirkt das Input nachtlos und fügt sich optisch perfekt in den Hintergrund ein.
```javascript
background: "#EEEEEE", // HEX Wert in "
backgrond: "transparent" // keine Hintergrundfarbe
```
### fontSize
`fontSize` gibt die Schriftgröße deiner Input-Texte an.
```javascript
fontSize: "12px" // Pixel Werte in "
```
### fontWeight
`fontWeight` gibt die Dicke deiner Schrift an.
```javascript
fontWeight: "800", // Zahl in " Default sind 400
```
### alignX
`alignX` gibt die Ausrichtung deines Textes an.
```javascript
alignX: "left", // left orientiert deinen Text linksbündig innerhalb des Input-Feldes
alignX: "center", // center orientiert deinen Text zentriert innerhalb des Input-Feldes
alignX: "right", // right orientiert deinen Text rechtsbündig innerhalb des Input-Feldes
```
### paddingY
`paddingY`* *gibt den Abstand zwischen dem Inhalt (hier: Inhalt des Inputs) und dem Rand jeweils oben und unten an. Dieser Parameter ist hauptsächlich beim type= "textarea" sinnvoll.
```javascript
paddingY: "20px", // Pixel-Werte
paddingY: "", // default: 2px
```
### paddingX
`paddingX`* gibt den Abstand zwischen dem Inhalt (hier: Inhalt des Inputs) und dem Rand jeweils links und rechts an. *
```javascript
paddingX: "20px", // Pixel-Werte
paddingX: "", // default: 8px
```
### suffix
`suffix` definiert eine Nachsilbe in der **Anzeige** (nicht Teil des gespeicherten Werts). Bei `type: "number"` kannst du dasselbe auch unter `numpad.suffix` setzen (`numpad.suffix` hat Vorrang).
```javascript
suffix: "€", // Anzeige z. B. 1.234,56 € — gespeichert wird nur die Zahl
```
### Placeholder Settings Block
`placeholderSettings` erlauben es Einstellungen für den placeholder des Input-Felds zu setzen. Es gibt dabei folgende Optionen unter anderem: ***value***: gibt an, was als Platzhalter vor dem Reinschreiben anzeigt werden soll. Zum Beispiel: "0" oder "Suche" oder auch Ninox Formeln & Konditionen (wie z.B. if cnt(Ergebnisse)!= null then "Suche" else " end).:
```javascript
placeholderSettings: {
value: "Suche", // Wert der ausgegeben werden soll
fontColor: "#000", // Schriftfarbe
backgroundColor: "" // Hintergrundfarbe
},
```
### reset Block
Der `reset`-Block steuert einen **Zurücksetzen-Button** rechts im Eingabefeld. Der Button wird nur angezeigt, wenn ein Wert im Feld steht – bei leerem Feld verschwindet er automatisch.
- `visible` – Wenn `true`, wird der Reset-Button angezeigt (sofern ein Wert vorhanden ist).
- `value` – Optional. Der Wert, der beim Klick gesetzt wird. Default: `null`. Bei `type: "date"` als **Millisekunden** übergeben (z. B. `number(date(calYear, calMonth, 1))` für 1. des Monats, `today()` für heute). Dieser Wert wird 1:1 als `##inputValue##` in den Actions eingesetzt.
- `icon` – Optional. Eigenes Icon als HTML-String (z. B. via `arcCustomIcon`). Ohne Angabe wird ein Standard-X-Icon verwendet.
- `color` – Optional. Farbe des Icons (für Default-Icon) bzw. Text (für später).
- `backgroundColor` – Optional. Hintergrundfarbe des Reset-Buttons.
- `borderRadius` – Optional. Abrundung der Ecken des Reset-Buttons.
- `actions` – Optional. Eigenes Action-Array nur für den Reset. Wenn gesetzt, feuern beim Reset nur diese Actions statt der Top-Level-`actions`. `##inputValue##` wird durch `reset.value` ersetzt.
```javascript
reset: {
visible: true,
value: null,
icon: arcCustomIcon({
name: "x",
color: "#666666",
iconSize: "14px"
}),
color: "#555555",
backgroundColor: "#f0f0f0",
borderRadius: "4px",
actions: []
}
```
**💡 Hinweise**
- Der Reset-Button erscheint nur, wenn das Feld einen Wert enthält.
- Bei `type: "date"` / `"time"` / `"number"` (mit Numpad) wird **ein** Icon rechts genutzt: Picker-Icon wenn leer, **X** wenn Wert + `reset.visible: true` (nie zwei Icons übereinander).
- Bei `reset.visible: true` wird `reset.value` beim Klick verwendet (z. B. Sprung auf 1. des Monats statt Leeren).
- Bei `disabled: true` wird der Reset-Button nicht angezeigt.
- Ohne `icon` wird ein Standard-X-Icon (Phosphor) verwendet.
### actions
Mit `actions` kannst du ein Array von Aktionen definieren, die beim **Submit** (Enter oder Blur bei Wertänderung) und beim **Reset** ausgeführt werden. Das entspricht dem gleichen Pattern wie bei `arcCustomButton`.
**Trigger-Zeitpunkte**
- **Submit**: Wenn der Nutzer Enter drückt oder das Feld verlässt und sich der Wert geändert hat.
- **Reset**: Wenn der Nutzer auf den Reset-Button klickt (nach dem DB-Update).
**Platzhalter `##inputValue##`**
In allen String-Properties der Action-Objekte kannst du `##inputValue##` verwenden. Der Platzhalter wird zur Laufzeit durch den aktuellen (formatierten) Input-Wert ersetzt – beim Submit durch den eingegebenen Wert, beim Reset durch `reset.value` (oder leer, wenn `reset.value` nicht gesetzt ist). Bei `type: "date"` ist das Format immer **Millisekunden-String** (Submit und Reset).
**Unterstützte Action-Typen**
Wie bei `arcCustomButton`: `update`, `popup`, `openRecord`, `delete`, `openUrl`, `customJS`, `create` usw. Für `openUrl` und `customJS` kannst du `action` statt `actionValue` verwenden.
**Beispiele**
Suchfeld (mit `tempStorage: true` – Wert wird nicht gespeichert, Action feuert trotzdem):
```javascript
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "helper_search"), value: "##inputValue##" }]
```
Barcode-Scanner (Feld updaten und Popup öffnen):
```javascript
actions: [
{ type: "update", recordId: Nr, field: fieldId(Nr, "Barcode"), value: "##inputValue##" },
{ type: "popup", recordId: Nr }
]
```
URL mit Suchbegriff öffnen:
```javascript
actions: [{ type: "openUrl", action: "https://example.com/search?q=##inputValue##" }]
```
### reset.actions
Optional. Wenn innerhalb des `reset`-Blocks ein eigenes `actions`-Array definiert wird, feuern beim **Reset** nur diese Actions (nicht die Top-Level-`actions`). Beim **Submit** werden weiterhin die Top-Level-`actions` ausgeführt. Ohne `reset.actions` verhalten sich Submit und Reset wie bisher – beide nutzen `actions`.
**Beispiel: Kalender-Datumsfeld mit Reset auf 1. des Monats**
```javascript
arcCustomInput({
uniqueId: "cal-date-" + Nr,
recordId: Nr,
fieldId: fieldId(Nr, "cal_date"),
type: "date",
value: calDate,
reset: {
visible: true,
value: number(date(calYear, calMonth, 1)),
actions: [{ type: "update", recordId: Nr, field: stateField, value: stateReset }]
},
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "cal_date"), value: "##inputValue##" }]
})
```
### liveUpdate
Mit `liveUpdate` werden Werte **während des Tippens** an Ninox gesendet – nicht erst beim Verlassen des Felds (blur). Ideal für Echtzeit-Suchfelder, Live-Filter oder Preview-Szenarien.
**Einfache Variante** (Boolean – 300ms Debounce, Actions feuern mit):
```javascript
liveUpdate: true
```
**Objekt-Variante** (volle Kontrolle):
```javascript
liveUpdate: {
debounce: 300, // ms – Verzögerung zwischen Tastendrücken (Default: 300)
minLength: 3, // Mindestzeichen bevor gefeuert wird (Default: 0)
actions: false // Sollen actions[] auch live feuern? (Default: true)
}
```
**Optionen**
| Property | Typ | Default | Beschreibung |
|----------|-----|---------|-------------|
| `debounce` | `number` | `300` | Wartezeit in ms nach dem letzten Tastendruck |
| `minLength` | `number` | `0` | Mindestlänge des Eingabewerts bevor ein Update feuert |
| `actions` | `boolean` | `true` | Ob die `actions[]`-Array auch bei jedem Live-Update ausgeführt werden soll |
**Verhalten**
- Beim Blur wird nur noch gefeuert, wenn sich der Wert seit dem letzten Live-Update geändert hat (kein Doppel-Update).
- `tempStorage: true` wird respektiert – bei Live-Update wird dann kein DB-Update gemacht, aber Actions feuern trotzdem (wenn `actions: true`).
- `##inputValue##`-Platzhalter in Actions funktionieren auch bei Live-Updates.
**Beispiel: Live-Suchfeld**
```javascript
arcCustomInput({
uniqueId: "search-" + Nr,
recordId: Nr,
fieldId: fieldId(Nr, "helper_search"),
value: text(helper_search),
type: "text",
embedded: true,
placeholderSettings: { value: "Suche..." },
liveUpdate: { debounce: 400, minLength: 2 },
actions: [{ type: "update", recordId: Nr, field: fieldId(Nr, "helper_search"), value: "##inputValue##" }]
})
```
### Focus Action Block
In der `focusAction` definierst du, wie dein Inputfeld im aktiven Zustand aussieht. Also bei Klick in das Inputfeld. Hier kann die Breite des Inputfeldes während des Reinklickens angepasst werden. Außerdem kann man Einstellungen für die Outline vornehmen.
#### `loop` im Focus Action Block
Die Loop-Funktion sorgt dafür, dass der Cursor automatisch in das nächste oder sogar in das gleiche Eingabefeld springt.
**Anwendungsfall: Suchfeld mit automatischem Fokus**
Ein praktisches Beispiel ist ein Suchfeld, in das der Cursor nach einer Aktion automatisch zurückkehrt.
Beispielsweise:
- Ein Nutzer gibt einen Suchbegriff ein.
- Er wählt ein Produkt aus der Ergebnisliste und legt es in den Warenkorb.
- Statt das Suchfeld erneut anklicken zu müssen, springt der Cursor direkt wieder hinein.
**Ideal für Barcode-Workflows**
Besonders nützlich ist diese Funktion für Barcode-Workflows, bei denen das Eingabefeld nach jeder Bestätigung weiterhin beschreibbar bleiben muss. Wenn mehrere Felder mit der Loop-Option ausgestattet sind, springt der Fokus automatisch in das letzte Feld.
Diese Funktion spart Klicks und macht wiederholte Eingaben effizienter.
### Label Settings Block
`labelSettings` erlauben es ein Label über dem Input-Feld zu setzen. Es gibt dabei folgende Optionen:
```javascript
labelSettings: {
title: "Mein Label", // Die Beschriftung des Labels (Text oder Mini-Widget)
fontSize: "", // Die Größe des Labels (Default ist 11px)
fontColor: "#EEEEEE", // Schriftfarbe des Labels
alignX: "", // Die horizontale Anordnung ist über left oder right steuerbar
gap: "" // Wert in Pixel (3px) bestimmt den Abstand zum Input-Feld
}
```
## Standard-Werte als Fallback
💡 **Hinweis: **Trägst du keine Werte hinter die Parameter ein, so ist in den meisten Fällen ein Fallback-Wert im System hinterlegt. An manchen Stellen, wie Werte-Felder (Tatsächliche Zahlenwerte zum Beispiel) macht das keinen Sinn. In Style-Parametern, wie Farben oder Größen hingegen schon. Hier siehst du den Code ohne eingetragene Werte und in den Kommentaren dahinter die Standard-Werte:
```javascript
arcCustomInput({
uniqueId: Nr, // Kein Fallback
recordId: Nr, // Kein Fallback
fieldId: "", // Kein Fallback
value: "", // Kein Fallback
placeholder: "", // Kein Fallback
width: "", // Fallback: 100%
color: "", // Fallback: #000000
background: "", // Fallback: #FFFFFF
fontSize: "" // Fallback: 13px
})
```
---
## Feature-Idee: Nice Select (Inspiration für Input/Select)
💡 **Geplante Erweiterung:** [Nice Select](https://nerdy.dev/nice-select#try-it) – moderne native Select-Stilisierung mit `appearance: base-select`, Spring-Animationen, Squircle-Ecken, Light/Dark. Patterns übertragbar auf Input-Fokus, Theming, RTL. [CodePen](https://codepen.io/editor/argyleink/pen/019c1f28-bbc2-7bac-ad4a-a7e41d3730f1).
---
# Pagination
Source: https://www.arc-rider.com/docs/mini-widgets/pagination
# Pagination
## AI Defaults (read first)
- **Function name**: `arcCustomPagination`.
- **uniqueId**: Required, e.g. `"pagination-" + Nr`.
- **recordId**: Required, use raw `Nr`.
- **field**: Required, the field storing current page number (`fieldId(Nr, "Feldname")`).
- **totalPages**: Total number of pages (computed from data count / items per page).
- **currentPage**: Current page value from the field.
# arcCustomPagination
Mit `arcCustomPagination` lassen sich Inhalte elegant seitenweise anzeigen – besonders bei langen Listen oder Tabellen ist das ein echter Gamechanger in puncto Performance und Übersichtlichkeit. Statt alle Datensätze auf einmal zu laden, werden nur die gerade sichtbaren Einträge angezeigt. Das spart Ladezeit und macht deine Oberfläche deutlich flüssiger.
### Wann sollte man Pagination einsetzen?
Pagination empfiehlt sich vor allem dann, wenn:
- eine [Liste sehr viele Einträge](/documentation/custom-table) enthält (z. B. Nachrichten, Projekte, Kunden),
- das Rendering durch zu viele gleichzeitig geladene Elemente langsam wird,
- eine bessere Nutzerführung durch Seitenzahlen gewünscht ist,
- du UI/UX optimieren willst, z. B. für mobile Endgeräte.
## Beispiel für paginierte Liste
Bevor du deine Liste paginierst, musst du erstmal die Ninox-Liste an sich definieren. Mit dieser Schleife wird nur der entsprechende Abschnitt aus der Gesamtliste geladen – abhängig von der aktuellen Seitenzahl:
## Anwendungscode für das Widget
Diesen Anwendungscode fügst du an der Stelle ein, an der du die Pagination anzeigen lassen möchtest.
```javascript
arcCustomPagination({
uniqueId: Nr,
editable: true,
recordId: Nr,
fieldId: "S1", // fieldId vom Ninox Feld "Aktuelle Seite"
direction: "horizontal",
title: current.'Aktuelle Seite',
value: current.'Aktuelle Seite',
total: ceil(cnt(list) / 30),
totalPrefix: " von "
})
```
## Parameter
Parameter
Typ
Beschreibung
`uniqueId`
Text
Eindeutige ID für das Pagination-Element. Pflichtfeld.
`editable`
Boolean
Ermöglicht manuelle Eingabe der Seitenzahl im Input-Feld.
`recordId`
Text
ID des aktuellen Datensatzes, auf den das Update erfolgt. (Die Aktion ausgeführt wird)
`fieldId`
Text
Das Feld, das die aktuelle Seite speichert.
`direction`
Text
Layout der Pagination: `"horizontal"` (Standard) oder `"vertical"`.
`title`
Text
Der aktuell angezeigte Wert im Input-Feld.
`value`
Zahl
Aktuelle Seitenzahl – wichtig für Navigation und Bedingung von Buttons.
`total`
Zahl
Gesamtzahl an Seiten (z. B. `ceil(cnt(list) / 30)`).
`totalPrefix`
Text
Kleiner Zusatz vor der Gesamtseitenanzahl, z. B. `" von "`.
`valuePrefix`
Text
Optionaler String, der beim Update vor die Seitenzahl gesetzt wird.
`buttonFirst`
Widget
Optionaler Inhalt (Text oder Widget) für den „erste Seite“-Button.
`buttonMinus`
Widget
Optionaler Inhalt (Text oder Widget) für den „zurück“-Button.
`buttonPlus`
Widget
Optionaler Inhalt (Text oder Widget) für den „vor“-Button.
`buttonLast`
Widget
Optionaler Inhalt (Text oder Widget) für den „letzte Seite“-Button.
## Aufbau in einer Custom Table
```javascript
let current := this;
let projectList := filteredList_Personen;
let current := this;
let maxEntries := 'Einträge pro Seite';
let currentPage := 'Aktuelle Seite';
let list := filteredList_Personen;
let paginatedList := unique(record('Stammdaten Person',0))[!= 0];
for listItem in slice(list.Nr, maxEntries * (currentPage - 1), maxEntries * currentPage) do
paginatedList := unique(paginatedList, record('Stammdaten Person',listItem))
end;
let data := {
uniqueListId: "Personen " + Nr,
tableId: tableId(first(projectList)),
height: "100%",
embedded: true,
table: paginatedList.[{
recordId: Nr,
groupRowColor: text(designSystem().colors.borderBlue),
rowHeight: "auto",
rowPaddingY: "5px",
columns: [{
field: "Name",
title: "Name",
align: "left",
value: data.name
}, {
field: "Typ",
title: "Typ",
width: "120px",
align: "left",
value: html(data.monteur.badge)
},
{
field: "Adresse",
title: "Adresse",
align: "left",
alignY: "center",
value: data.address.block,
}
]
}],
footer: {
showFooter: true,
showActionButton: false,
leftSideContent:",
rightSideContent: arcCustomPagination({
uniqueId: "pagination-person" + Nr,
editable: true,
recordId: Nr,
fieldId: fieldId(current.Nr, "Aktuelle Seite"),
direction: "horizontal",
title: current.'Aktuelle Seite',
value: current.'Aktuelle Seite',
total: ceil(cnt(list) / 'Einträge pro Seite'),
totalPrefix: " von "
})
}
};
arcCustomTable(data)
```
## Anwendungscode Complex
```javascript
arcCustomPagination({
uniqueId: Nr,
editable: true,
recordId: Nr,
fieldId: "E2",
direction: "horizontal",
title: current.'Aktuelle Seite',
value: current.'Aktuelle Seite',
total: ceil(cnt(list) / maxEntries),
totalPrefix: " von ",
buttonMinus: arcCustomButton({
uniqueId: "ButtonMinus" + Nr,
icon: arcCustomIcon({
name: "caret-left",
color: "#555",
size: 20
}),
fontSize: "18px",
fontColor: "",
iconColor: "",
backgroundColor: "transparent",
borderColor: "transparent"
}),
buttonPlus: arcCustomButton({
uniqueId: "ButtonPlus" + Nr,
icon: arcCustomIcon({
name: "caret-right",
color: "#555",
size: 20
}),
fontSize: "18px",
fontColor: "",
iconColor: "",
backgroundColor: "transparent",
borderColor: "transparent"
}),
buttonFirst: arcCustomButton({
uniqueId: "ButtonFirst" + Nr,
icon: arcCustomIcon({
name: "caret-double-left",
color: "#555",
size: 20
}),
fontSize: "18px",
fontColor: "",
iconColor: "",
backgroundColor: "transparent",
borderColor: "transparent"
}),
buttonLast: arcCustomButton({
uniqueId: "ButtonLast" + Nr,
icon: arcCustomIcon({
name: "caret-double-right",
color: "#555",
size: 20
}),
fontSize: "18px",
fontColor: "",
iconColor: "",
backgroundColor: "transparent",
borderColor: "transparent"
})
})
```
**💡 Pro-Tipp: **Wenn du mehrere Listen auf einer Seite anzeigen willst, kannst du mit verschiedenen `uniqueId`-Werten und eigenen `fieldId`-Felder für jede Liste eine eigene Pagination bauen. So bleibt alles unabhängig.
### Fazit
`arcCustomPagination` ist perfekt, um große Datenmengen elegant, performant und nutzerfreundlich zu präsentieren. Ein Muss für alle, die mit langen Listen arbeiten – egal ob im CRM, bei Projekten oder Support-Tickets.
Let’s paginate smart. 🚀
---
# Progress Bar
Source: https://www.arc-rider.com/docs/mini-widgets/progress-bar
# ProgressBar in React
Einen Teilwert im Verhältnis zu einem Gesamtwert darstellen, etwa erledigte Aufgaben oder erreichte Ziele.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetProgressBar } from '@arcrider/arcwidgets-react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
export default function Example() {
return (
);
}
```
## Features ausprobieren
### Zielwerte, Übererfüllung und Farben
Ziehe den Wert auch über 100 Prozent. Ohne feste Farbe entscheidet das Widget anhand des Verhältnisses; die Konfiguration bleibt im Quellcode sichtbar.
```tsx
import { useState } from 'react';
import { ArcWidgetProgressBar } from '@arcrider/arcwidgets-react';
export default function Example() {
const [value, setValue] = useState(65);
const [automatic, setAutomatic] = useState(true);
return (
<>
{value}% des Ziels erreicht
);
}
```
## Komponenten-Props
### id
Optionale, stabile ID der Widget-Instanz. Ohne Angabe erzeugt React eine ID.
### data
Konfiguration vom Typ `ArcWidgetProgressBarData`. Übergib Änderungen als neue Objekte; verwalte fachliche Daten und Auswahl in React-State.
### onAction
Optionaler Fallback `(type: string, ...args: unknown[]) => unknown`. Der konkrete Callback hat Vorrang. Details: [State und Events](/docs/react/patterns/react-state-events).
Dieses Widget ist eine Darstellungskomponente und stellt keine eigenen Interaktions-Callbacks bereit.
## Konfiguration
Die folgenden Felder gehören in `data`. Größen werden als Strings angegeben, Zahlen und Zeitwerte entsprechend dem jeweiligen Typ.
### valueProgress
Aktueller Teilwert.
Typ: `number | string`.
### valueTotal
Gesamtwert; muss größer als null sein.
Typ: `number | string`.
### valueText
Eigene Beschriftung des Fortschritts.
Typ: `string`.
### progressColor
Farbe des gefüllten Fortschrittsbereichs.
Typ: `string`.
### backgroundColor
Hintergrundfarbe.
Typ: `string`.
### width
Breite des Widgets als Größenangabe.
Typ: `string`.
### height
Höhe des Widgets, z. B. `"320px"`. Prozentwerte benötigen einen Elterncontainer mit festgelegter Höhe.
Typ: `string`.
### borderRadius
Abrundung der Ecken.
Typ: `string`.
### fontColor
Schriftfarbe.
Typ: `string`.
### fontSize
Schriftgröße als CSS-Wert.
Typ: `string`.
## Verhalten und Grenzen
- `valueProgress` und `valueTotal` bilden das Verhältnis. Verwende einen Gesamtwert größer als null.
- `valueText` ist eine eigene Beschriftung. Die Berechnung und Formatierung fachlicher Werte erfolgt in React.
Unterstützte `ArcWidgetSlot`-Felder erlauben einzelne JSX-Elemente, Text oder Widget-Deskriptoren. Reiche fremden Text als JSX-Text weiter; HTML-Strings werden als HTML interpretiert. [Inhalte kombinieren](/docs/react/patterns/nested-widget-descriptors).
## Datentypen
Diese widgetbezogenen Typen werden aus dem Paket exportiert. Gemeinsame Typen wie `ArcWidgetSlot`, `ArcWidgetStyles` und `ArcReactWidgetProps` sind ebenfalls verfügbar. Indexsignaturen erlauben Erweiterungen; sie sind keine Zusage, dass beliebige Felder im Widget ausgewertet werden.
```typescript
export interface ArcWidgetProgressBarData extends ArcWidgetBaseData {
valueProgress?: number | string;
valueTotal?: number | string;
valueText?: string;
progressColor?: string;
backgroundColor?: string;
width?: string;
height?: string;
borderRadius?: string;
fontColor?: string;
fontSize?: string;
}
```
## Einsatzbeispiele
- [Dashboard mit CSS Grid](/docs/react/examples/dashboardansicht-mit-grid)
- [State und Events](/docs/react/patterns/react-state-events)
- [Fehlerbehebung](/docs/react/faq/react-troubleshooting)
# Progress Bar
## AI Defaults (read first)
- **Function name**: `arcCustomProgressBar`.
- **valueProgress**: Current progress (numerator), as number.
- **valueTotal**: Target / total (denominator), as number.
- **progressColor**: Fill color (optional; auto amber / green / black by ratio when omitted).
- **backgroundColor**: Track background color.
- **height**: Bar height, e.g. `"8px"`.
- **valueText**: Optional label beside the bar.
- Display-only — no `actions` / persist.
# Progress Bar
Die Progress Bar besteht aus einem Anwendungscode, den du in einem Ninox Formel-Feld auf deiner Wunschoberfläche in der Datenbank einfügst.
## Gesamter Anwendungscode
Folgend siehst du einen beispielhaften Anwendungscode für eine Progress Bar:
```javascript
arcCustomProgressBar({
uniqueId: "",
width: "",
height: "",
borderRadius: "",
fontSize: "",
fontColor: "",
backgroundColor: "",
progressColor: "",
valueTotal: "",
valueProgress: "",
valueText: ""
})
```
***uniqueId*** vergibst du individuell und sollte einzigartig auf deiner Oberfläche sein. Sinn dahinter ist: Wenn du mehrere Progress Bars mit unterschiedlichen Settings auf deiner Seite erstellst, überschrieben sich die Styles nicht.
```javascript
uniqueId: "Progress 1", // Text in "
```
***width*** gibt die Weite deiner Progress Bar an.
```javascript
width: "300px", // Pixel-Werte in "
width: "100%", // Prozent-Werte in " / Orientiert sich prozentual an der Breite des Formelfeldes.
```
***height*** gibt die Höhe deiner Progress Bar an.
```javascript
height: "300px", // Pixel-Werte in "
height: "100%", // Prozent-Werte in " / Orientiert sich prozentual an der Breite des Formelfeldes.
```
***borderRadius*** gibt die Abrundung der Progressbar-Ecken an.
```javascript
borderRadius: "4px", // Pixel-Werte in "
borderradius: "", // default: 50%
```
***fontSize*** gibt die Schriftgröße der Beschriftung von ***valueText ***wieder.
```javascript
fontSize: "14px", // Pixel-Werte in "
```
***fontColor*** gibt die Schriftfarbe der Beschriftung von ***valueText ***wieder.
```javascript
fontColor: "#FFFFFF", // HEX Code in "
```
***backgroundColor*** definiert die Hintergrundfarbe deiner Progress Bar
```javascript
backgroundColor: "#EEEEEE", // HEX Code in "
```
***progressColor*** definiert die Farbe des Fortschrittbalkens.
```javascript
progressColor: "#FFBF00", // HEX Coe in "
progressColor: if Status= 2 then "#FFBF00" else "#e9ecf4", // Ninox-Formeln, -Schreibweisen & -Konfditionen möglich. Wichtig ist, dass text() bei ausgegeben wird.
```
***valueTotal*** definiert den Gesamtwert deiner Progress Bar. Sozusagen den Nenner einer Bruchzahl.
```javascript
valueTotal: 20, // Zahlenwert
valueTotal: Projekt.umsatzZiel, // Referenzierte Ninox-Felder. Auch gehen Ninox-Funktionen & -Schreibweisen.
```
***valueProgress*** definiert den bislang erreichten Wert. Den Zähler einer Bruchzahl.
```javascript
valueProgress: 10, // Zahlenwert
valueProgress: Projekt.umsatzAktuell// Referenzierte Ninox-Felder. Auch gehen Ninox-Funktionen & -Schreibweisen.
```
***valueText*** gibt die Bezeichnung neben deiner Progress Bar aus. Sinnvoll ist es, hier die Werte als Text auszugeben,
```javascript
valueText: Projekt.umsatzAktuell + " / " + Projekt.umsatzZiel
```
## Standard-Werte als Fallback
💡 **Hinweis: **Trägst du keine Werte hinter die Parameter ein, so ist in den meisten Fällen ein Fallback-Wert im System hinterlegt. An manchen Stellen, wie Berechnungsfelder (Tatsächliche Zahlenwerte zum Beispiel) macht das keinen Sinn. In Style-Parametern, wie Farben oder Größen hingegen schon. Hier siehst du den Code ohne eingetragene Werte und in den Kommentaren dahinter die Standard-Werte:
```javascript
arcCustomProgressBar({
uniqueId: "", // Kein Fallback
width: "", // Fallback: 100%
fontSize: "", // Fallback: 12px
fontColor: "", // Fallbacke: #000000 (schwarz)
backgroundColor: "", // Fallback: #EEEEEE
progressColor: "", // Fallback:
if data.progressColor = " then
switch complete do
case true:
"#76CD3C" // gelb
case false:
if number(data.valueTotal) < number(data.valueProgress) then
"#000"
else
"#FFBF00" // grün
end
default:
"#e9ecf4"
end
else
text(data.progressColor)
end;
valueTotal: "", // Kein Fallback
valueProgress: "", // Kein Fallback
valueText: "" // Kein Fallback
})
```
---
# Select (Dropdown)
Source: https://www.arc-rider.com/docs/mini-widgets/select
# Select in React
Eine Option aus einer Liste wählen. Wert, sichtbare Beschriftung und aktive Einträge werden aus React-State abgeleitet.
Referenz für `@arcrider/arcwidgets-react@0.1.0-alpha.5`. [Installation](/docs/react/intro/setup-react) · [Alle Komponenten](/docs/react/intro/react-components).
## Vollständiges Beispiel
```tsx
import { ArcWidgetSelect } from '@arcrider/arcwidgets-react';
import { useState } from 'react';
const lang = document.documentElement.lang.startsWith('en')
? 'en'
: document.documentElement.lang.startsWith('es')
? 'es'
: 'de';
const requested = new URLSearchParams(location.search).get('data');
const pack = requested === 'empty' || requested === 'busy' ? requested : 'demo';
const t = (de: string, en: string, es: string) =>
lang === 'en' ? en : lang === 'es' ? es : de;
const demoOptions = [
{ value: 'open', title: t('Offen', 'Open', 'Abierto') },
{ value: 'work', title: t('In Arbeit', 'In progress', 'En curso') },
{ value: 'done', title: t('Erledigt', 'Done', 'Hecho') },
];
const busyOptions = [
...demoOptions,
{ value: 'wait', title: t('Wartet', 'Waiting', 'En espera') },
{ value: 'hold', title: t('Pausiert', 'On hold', 'En pausa') },
];
const options =
pack === 'empty' ? [] : pack === 'busy' ? busyOptions : demoOptions;
export default function Example() {
const [status, setStatus] = useState(null);
const all = t('Alle', 'All', 'Todos');
return (
<>
option.value === status)?.title ?? all,
items: options.map((option) => ({
...option,
active: option.value === status,
})),
reset: { title: all },
}}
onChange={setStatus}
/>
)}
);
}
```
## Features ausprobieren
### Mehrfachauswahl und Bildkonvertierung
Wähle eigene Bilder und vergleiche die Qualitätseinstellungen. Die Dateien werden ausschließlich lokal im Browser verarbeitet.
```tsx
import { useState } from 'react';
import { ArcWidgetUpload } from '@arcrider/arcwidgets-react';
export default function Example() {
const [quality, setQuality] = useState(80);
const [multiple, setMultiple] = useState(true);
const [files, setFiles] = useState<{ name: string; src: string }[]>([]);
return (
<>
})
`,
};
});
export default function Example() {
const [index, setIndex] = useState(0);
return (
<>